SocialScrape Linkbio API

openapi: 3.2.0
info:
  title: SocialScrape Linkbio API
  version: '1'
  description: 'Public social media data as an API: profiles, posts, comments, search, ads and transcripts across platforms, in one response shape.


    Authenticate with the `x-api-key` header. Every response is an envelope with `ok`, `credits_charged`, `credits_remaining`, `cached`, `cached_at` and `request_id`; failures are free and carry a stable `error.code` and a `retryable` flag. Send `Idempotency-Key` on a retried POST to get the first answer back without a second charge. Pass `max_age_days` (or ScrapeCreators'' `cache_max_age=7d`) to accept a cached result for free.'
servers:
- url: https://api.socialscrape.dev
security:
- ApiKeyAuth: []
tags:
- name: linkbio
paths:
  /v1/linkbio:
    get:
      operationId: linkbio
      summary: Lnk.Bio page
      tags:
      - linkbio
      parameters:
      - name: url
        in: query
        required: false
        description: Lnk.Bio page URL.
        schema:
          type: string
          format: uri
        x-hosts:
        - lnk.bio
      - name: handle
        in: query
        required: false
        description: Lnk.Bio username.
        schema:
          type: string
        x-aliases:
        - username
      - name: trim
        in: query
        required: false
        description: 'Smaller response: drops null fields and `extra`.'
        schema:
          type: boolean
          default: false
      - name: raw
        in: query
        required: false
        description: Also return the platform's original object as `raw`.
        schema:
          type: boolean
          default: false
      - name: max_age_days
        in: query
        required: false
        description: Serve a cached result fetched within this many days, for 0 credits. ScrapeCreators' `cache_max_age=7d` spelling is accepted too.
        schema:
          type: number
          minimum: 0
          maximum: 30
        x-aliases:
        - cache_max_age
      responses:
        '200':
          description: 'Success. Charge: 1 credit per successful request (a profile, a post, one page of a list).'
          headers:
            x-request-id:
              $ref: '#/components/headers/x-request-id'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessEnvelope_LinkPage_'
        '202':
          description: 'Still running: poll `data.poll_url` (free); the finished job returns the final envelope and charges then, once.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessEnvelope_JobAccepted_'
        '400':
          description: 'Error (always free): `invalid_params`, `unsupported_url`.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
        '401':
          description: 'Error (always free): `unauthorized`.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
        '402':
          description: 'Error (always free): `insufficient_credits`.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
        '403':
          description: 'Error (always free): `forbidden`, `private`, `age_restricted`.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
        '404':
          description: 'Error (always free): `not_found`, `transcript_unavailable`.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
        '409':
          description: 'Error (always free): `conflict`.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
        '410':
          description: 'Error (always free): `removed`.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
        '429':
          description: 'Error (always free): `rate_limited`.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
          headers:
            retry-after:
              description: Seconds to wait.
              schema:
                type: integer
        '451':
          description: 'Error (always free): `unavailable_in_region`.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
        '500':
          description: 'Error (always free): `internal`.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
        '501':
          description: 'Error (always free): `not_implemented`.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
        '503':
          description: 'Error (always free): `upstream_rate_limited`, `upstream_blocked`, `upstream_error`, `upstream_changed`, `upstream_timeout`, `overloaded`.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
      x-endpoint-id: linkbio
      x-credits: standard
      x-credit-rule: 1 credit per successful request (a profile, a post, one page of a list)
      x-status: ga
      x-pool: open
      x-mode: sync
      x-timeout-seconds: 30.0
      x-cache:
        cacheable: true
        ttl_days: 30
      description: 'A Lnk.Bio page: the creator''s name, bio, avatar, every link in page order and the social accounts it points to. Lnk.Bio only serves browser-like clients, so this one is slower. Pass the page `url` or just the `handle`.'
      x-one-of:
      - - url
        - handle
      x-examples:
      - url: https://lnk.bio/msjennafischer
components:
  schemas:
    LinkPage:
      additionalProperties: false
      description: A link-in-bio page (Linktree, Komi, Pillar, Linkbio, Linkme).
      properties:
        object:
          const: link_page
          default: link_page
          title: Object
          type: string
        platform:
          $ref: '#/components/schemas/Platform'
        handle:
          anyOf:
          - type: string
          - type: 'null'
          default: null
          title: Handle
        url:
          anyOf:
          - type: string
          - type: 'null'
          default: null
          title: Url
        name:
          anyOf:
          - type: string
          - type: 'null'
          default: null
          title: Name
        bio:
          anyOf:
          - type: string
          - type: 'null'
          default: null
          title: Bio
        avatar_url:
          anyOf:
          - type: string
          - type: 'null'
          default: null
          title: Avatar Url
        links:
          anyOf:
          - items:
              $ref: '#/components/schemas/Link'
            type: array
          - type: 'null'
          default: null
          title: Links
        socials:
          anyOf:
          - items:
              $ref: '#/components/schemas/Link'
            type: array
          - type: 'null'
          default: null
          title: Socials
        extra:
          anyOf:
          - additionalProperties: true
            type: object
          - type: 'null'
          default: null
          title: Extra
      required:
      - platform
      title: LinkPage
      type: object
    ErrorEnvelope:
      properties:
        ok:
          const: false
          default: false
          title: Ok
          type: boolean
        error:
          $ref: '#/components/schemas/ErrorBody'
        credits_charged:
          const: 0
          default: 0
          title: Credits Charged
          type: integer
        request_id:
          title: Request Id
          type: string
      required:
      - error
      - request_id
      title: ErrorEnvelope
      type: object
    ErrorBody:
      properties:
        code:
          $ref: '#/components/schemas/ErrorCode'
        message:
          title: Message
          type: string
        retryable:
          title: Retryable
          type: boolean
      required:
      - code
      - message
      - retryable
      title: ErrorBody
      type: object
    SuccessEnvelope_LinkPage_:
      properties:
        ok:
          const: true
          default: true
          title: Ok
          type: boolean
        credits_charged:
          title: Credits Charged
          type: integer
        credits_remaining:
          anyOf:
          - type: integer
          - type: 'null'
          title: Credits Remaining
        cached:
          title: Cached
          type: boolean
        cached_at:
          anyOf:
          - format: date-time
            type: string
          - type: 'null'
          title: Cached At
        request_id:
          title: Request Id
          type: string
        data:
          $ref: '#/components/schemas/LinkPage'
        cursor:
          anyOf:
          - type: string
          - type: 'null'
          default: null
          title: Cursor
        has_more:
          anyOf:
          - type: boolean
          - type: 'null'
          default: null
          title: Has More
        raw:
          default: null
          title: Raw
      required:
      - credits_charged
      - credits_remaining
      - cached
      - cached_at
      - request_id
      - data
      title: SuccessEnvelope[LinkPage]
      type: object
    SuccessEnvelope_JobAccepted_:
      properties:
        ok:
          const: true
          default: true
          title: Ok
          type: boolean
        credits_charged:
          title: Credits Charged
          type: integer
        credits_remaining:
          anyOf:
          - type: integer
          - type: 'null'
          title: Credits Remaining
        cached:
          title: Cached
          type: boolean
        cached_at:
          anyOf:
          - format: date-time
            type: string
          - type: 'null'
          title: Cached At
        request_id:
          title: Request Id
          type: string
        data:
          $ref: '#/components/schemas/JobAccepted'
        cursor:
          anyOf:
          - type: string
          - type: 'null'
          default: null
          title: Cursor
        has_more:
          anyOf:
          - type: boolean
          - type: 'null'
          default: null
          title: Has More
        raw:
          default: null
          title: Raw
      required:
      - credits_charged
      - credits_remaining
      - cached
      - cached_at
      - request_id
      - data
      title: SuccessEnvelope[JobAccepted]
      type: object
    Platform:
      enum:
      - youtube
      - tiktok
      - instagram
      - reddit
      - bluesky
      - threads
      - truthsocial
      - pinterest
      - twitch
      - kick
      - snapchat
      - linktree
      - komi
      - pillar
      - linkbio
      - linkme
      - twitter
      - facebook
      - linkedin
      - amazon
      - spotify
      - apple_music
      - soundcloud
      - github
      - kwai
      - rumble
      - telegram
      - google
      - cosmos
      - web
      title: Platform
      type: string
    JobAccepted:
      additionalProperties: false
      description: Answer for a job that is still running. Poll `poll_url` (free).
      properties:
        object:
          const: job
          default: job
          title: Object
          type: string
        job_id:
          title: Job Id
          type: string
        status:
          enum:
          - pending
          - running
          title: Status
          type: string
        poll_url:
          title: Poll Url
          type: string
      required:
      - job_id
      - status
      - poll_url
      title: JobAccepted
      type: object
    Link:
      additionalProperties: false
      properties:
        title:
          anyOf:
          - type: string
          - type: 'null'
          default: null
          title: Title
        url:
          title: Url
          type: string
      required:
      - url
      title: Link
      type: object
    ErrorCode:
      enum:
      - invalid_params
      - unsupported_url
      - unauthorized
      - insufficient_credits
      - forbidden
      - rate_limited
      - conflict
      - not_found
      - private
      - age_restricted
      - removed
      - unavailable_in_region
      - transcript_unavailable
      - upstream_rate_limited
      - upstream_blocked
      - upstream_error
      - upstream_changed
      - upstream_timeout
      - overloaded
      - not_implemented
      - internal
      title: ErrorCode
      type: string
  headers:
    x-request-id:
      description: The request id, also in the body. Quote it to support.
      schema:
        type: string
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: x-api-key