> ## Documentation Index
> Fetch the complete documentation index at: https://socialquery.dev/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Batch public profiles

> Batch public profile lookup in input order, preserving custom_id. Supported platforms: instagram, tiktok, youtube, bluesky, threads, truthsocial, twitch, snapchat, kwai, facebook, twitter, linkedin. Source identities are checked before returning canonical Author objects. Missing fields remain null. Reserve one credit per input (five for LinkedIn), then charge only successful profiles at that rate and refund all other rows. Public source access and provider allowances apply; Truth Social is limited to prominent publicly accessible accounts. Unsupported platforms return an unbilled row. JSON only: posts, since, stop_at_id and SSE are not implemented. Four bounded source workers; unstarted rows are deferred and unbilled. No response cache; idempotent replay is free. The serialized items array must fit the 16,000-character parameter limit.

Pass 1–50 objects in `items`, each with `platform`, `handle`, and optional `custom_id`. Results retain input order and caller IDs. Handles may be bare, begin with `@`, or be canonical HTTPS profile URLs. URLs must match the selected platform; redirects, credentials, query strings and fragments are rejected.

**Supported platforms:** Instagram, TikTok, YouTube, Twitter, Threads, Twitch, Snapchat, Truth Social, Bluesky, Kwai, LinkedIn and Facebook. Social profiles use [ScrapeCreators](https://docs.scrapecreators.com/), YouTube uses its [official API](https://developers.google.com/youtube/v3/docs/channels/list), Bluesky uses its [public API](https://docs.bsky.app/docs/api/app-bsky-actor-get-profile), and LinkedIn uses [ScrapeBadger](https://docs.scrapebadger.com/). Other platform values return `unsupported`, with no final charge.

Truth Social is limited to prominent publicly accessible accounts. Facebook gated pages are rejected. LinkedIn's `id` is the returned public profile slug (`ext.id_kind: public_id`), not a numeric member ID. Twitch partnership and Twitter blue-verification flags remain separate from canonical verification. Kwai counts reflect the public source even when surprisingly small; no values are inferred. Truth Social's HTML biography remains in `ext.bio_html`, with canonical `bio` null. Provider access and available allowance determine whether a live lookup succeeds.

Posts, `since`, per-item `stop_at_id`, and SSE are not implemented. Supplied enrichment options or SSE requests return 422 before spending. The JSON-serialized `items` array must fit the 16,000-character parameter limit.

Every `ok` row contains a canonical Author in `data`. The returned identity must match the input. Unknown follower, verification or location fields remain null; hidden YouTube subscriber counts remain null. Provider errors are not treated as nonexistent accounts. A definitive source miss returns `not_found`.

The request holds one credit per input, or five for a LinkedIn input, then refunds every `not_found`, `unsupported`, `error` and `deferred` row. Each successful profile costs one credit, or five for LinkedIn. Repeated input rows are separate lookups. Include the summed hold in `X-Max-Credits`.

At most four source calls run concurrently, each with a twelve-second timeout. No new source work starts after twenty-eight seconds. Rows left unstarted return `deferred` and cost zero. A provider authentication or quota failure stops new calls to that provider while other providers continue. The response is never cached. Replay the same `Idempotency-Key` for zero-cost replay, or retry only failed/deferred rows with a new key.

For MCP use `execute_endpoint`. The Python skill requires `--allow-mutation`, the batch budget and an idempotency key. Both clients calculate the complete hold before sending the batch.


## OpenAPI

````yaml POST /prism/profiles
openapi: 3.1.0
info:
  title: SocialQuery API
  version: '2026-10-09'
  description: >-
    Documented requests for public-source records. Inspect accepted inputs and
    credit amounts, then verify the selected operation before integrating
    preview coverage.
servers:
  - url: https://socialquery.dev/v1
security:
  - apiKey: []
paths:
  /prism/profiles:
    post:
      tags:
        - Prism
      summary: Batch public profiles
      description: >-
        Batch public profile lookup in input order, preserving custom_id.
        Supported platforms: instagram, tiktok, youtube, bluesky, threads,
        truthsocial, twitch, snapchat, kwai, facebook, twitter, linkedin. Source
        identities are checked before returning canonical Author objects.
        Missing fields remain null. Reserve one credit per input (five for
        LinkedIn), then charge only successful profiles at that rate and refund
        all other rows. Public source access and provider allowances apply;
        Truth Social is limited to prominent publicly accessible accounts.
        Unsupported platforms return an unbilled row. JSON only: posts, since,
        stop_at_id and SSE are not implemented. Four bounded source workers;
        unstarted rows are deferred and unbilled. No response cache; idempotent
        replay is free. The serialized items array must fit the 16,000-character
        parameter limit.
      operationId: post_prism_profiles
      parameters:
        - name: Cache-Control
          in: header
          required: false
          example: no-cache
          schema:
            type: string
        - name: Idempotency-Key
          in: header
          required: false
          example: 7a5e1b4c-2d8f-4a3b-9c1e-6e8b4d2a1f3c
          schema:
            type: string
        - name: X-Max-Credits
          in: header
          required: false
          description: >-
            Optional nonnegative integer cap on the maximum request hold. A live
            request whose hold exceeds this cap returns 422
            CREDIT_BUDGET_EXCEEDED before spending. Metered holds use the
            requested limit; cache hits and successful idempotent replays cost
            zero.
          schema:
            type: integer
            minimum: 0
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - items
              properties:
                items:
                  type: array
                  minItems: 1
                  maxItems: 50
                  items:
                    type: object
                    required:
                      - platform
                      - handle
                    additionalProperties: false
                    properties:
                      platform:
                        type: string
                        pattern: ^[a-z_]{1,32}$
                      handle:
                        type: string
                        minLength: 1
                        maxLength: 2048
                      custom_id:
                        type: string
                        maxLength: 200
                  example:
                    - platform: bluesky
                      handle: bsky.app
                      custom_id: account-1
                    - platform: youtube
                      handle: '@GoogleDevelopers'
                      custom_id: account-2
                include:
                  type: string
                  enum:
                    - posts
                  description: >-
                    Not implemented in this release; returns 422 before
                    spending.
                since:
                  type: string
                  description: >-
                    Not implemented in this release; returns 422 before
                    spending.
      responses:
        '200':
          description: >-
            Batch public profile lookup in input order, preserving custom_id.
            Supported platforms: instagram, tiktok, youtube, bluesky, threads,
            truthsocial, twitch, snapchat, kwai, facebook, twitter, linkedin.
            Source identities are checked before returning canonical Author
            objects. Missing fields remain null. Reserve one credit per input
            (five for LinkedIn), then charge only successful profiles at that
            rate and refund all other rows. Public source access and provider
            allowances apply; Truth Social is limited to prominent publicly
            accessible accounts. Unsupported platforms return an unbilled row.
            JSON only: posts, since, stop_at_id and SSE are not implemented.
            Four bounded source workers; unstarted rows are deferred and
            unbilled. No response cache; idempotent replay is free. The
            serialized items array must fit the 16,000-character parameter
            limit.
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/SocialQueryResponse'
                  - type: object
                    properties:
                      data:
                        type: object
                        required:
                          - items
                          - returned_count
                          - succeeded
                          - next_cursor
                        properties:
                          items:
                            type: array
                            items:
                              type: object
                              required:
                                - platform
                                - handle
                                - status
                                - data
                                - credits_used
                                - ext
                              properties:
                                platform:
                                  type: string
                                handle:
                                  type: string
                                custom_id:
                                  type: string
                                status:
                                  type: string
                                  enum:
                                    - ok
                                    - not_found
                                    - unsupported
                                    - error
                                    - deferred
                                data:
                                  type:
                                    - object
                                    - 'null'
                                  properties:
                                    username:
                                      type:
                                        - string
                                        - 'null'
                                    display_name:
                                      type:
                                        - string
                                        - 'null'
                                    avatar_url:
                                      type:
                                        - string
                                        - 'null'
                                    bio:
                                      type:
                                        - string
                                        - 'null'
                                    url:
                                      type:
                                        - string
                                        - 'null'
                                    location:
                                      type:
                                        - string
                                        - 'null'
                                    external_url:
                                      type:
                                        - string
                                        - 'null'
                                    id:
                                      type: string
                                    verified:
                                      type:
                                        - boolean
                                        - 'null'
                                    followers:
                                      type:
                                        - integer
                                        - 'null'
                                      minimum: 0
                                    following:
                                      type:
                                        - integer
                                        - 'null'
                                      minimum: 0
                                    posts_count:
                                      type:
                                        - integer
                                        - 'null'
                                      minimum: 0
                                    likes_count:
                                      type:
                                        - integer
                                        - 'null'
                                      minimum: 0
                                    ext:
                                      type: object
                                credits_used:
                                  type: integer
                                  minimum: 0
                                ext:
                                  type: object
                                  properties:
                                    reason:
                                      type: string
                          returned_count:
                            type: integer
                          succeeded:
                            type: integer
                          next_cursor:
                            type: 'null'
        '400':
          $ref: '#/components/responses/Error400'
        '401':
          $ref: '#/components/responses/Error401'
        '402':
          $ref: '#/components/responses/Error402'
        '403':
          $ref: '#/components/responses/Error403'
        '404':
          $ref: '#/components/responses/Error404'
        '405':
          $ref: '#/components/responses/Error405'
        '409':
          $ref: '#/components/responses/Error409'
        '422':
          $ref: '#/components/responses/Error422'
        '429':
          $ref: '#/components/responses/Error429'
        '500':
          $ref: '#/components/responses/Error500'
        '502':
          $ref: '#/components/responses/Error502'
        '503':
          $ref: '#/components/responses/Error503'
        '504':
          $ref: '#/components/responses/Error504'
components:
  schemas:
    SocialQueryResponse:
      type: object
      required:
        - success
        - platform
        - endpoint
        - credits_used
        - credits_remaining
        - request_id
        - cached
        - data
      properties:
        success:
          type: boolean
          const: true
        platform:
          type: string
        endpoint:
          type: string
        credits_used:
          type: integer
          minimum: 0
        credits_remaining:
          type:
            - integer
            - 'null'
        request_id:
          type: string
        cached:
          type: boolean
        data:
          type: object
          additionalProperties: true
          description: >-
            The selected operation determines the resource fields in this
            object. Source data can omit a metric or report it as null.
    SocialQueryError:
      type: object
      required:
        - success
        - platform
        - endpoint
        - credits_used
        - credits_remaining
        - request_id
        - cached
        - error
      properties:
        success:
          type: boolean
          const: false
        platform:
          type: string
        endpoint:
          type: string
        credits_used:
          type: integer
          minimum: 0
        credits_remaining:
          type:
            - integer
            - 'null'
        request_id:
          type: string
        cached:
          type: boolean
        error:
          type: object
          required:
            - code
            - type
            - message
            - status
            - doc_url
          properties:
            code:
              type: string
            type:
              type: string
            message:
              type: string
            status:
              type: integer
            doc_url:
              type: string
              format: uri
  responses:
    Error400:
      description: Upstream rejected the request.
      headers:
        X-Request-Id:
          schema:
            type: string
        X-Credits-Used:
          schema:
            type: integer
        X-Credits-Remaining:
          schema:
            type: string
        X-Cache:
          schema:
            type: string
            enum:
              - HIT
              - MISS
              - BYPASS
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/SocialQueryError'
    Error401:
      description: Missing, expired, invalid, or revoked API key.
      headers:
        X-Request-Id:
          schema:
            type: string
        X-Credits-Used:
          schema:
            type: integer
        X-Credits-Remaining:
          schema:
            type: string
        X-Cache:
          schema:
            type: string
            enum:
              - HIT
              - MISS
              - BYPASS
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/SocialQueryError'
    Error402:
      description: Insufficient SocialQuery credits.
      headers:
        X-Request-Id:
          schema:
            type: string
        X-Credits-Used:
          schema:
            type: integer
        X-Credits-Remaining:
          schema:
            type: string
        X-Cache:
          schema:
            type: string
            enum:
              - HIT
              - MISS
              - BYPASS
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/SocialQueryError'
    Error403:
      description: Key scope or provider policy denied access.
      headers:
        X-Request-Id:
          schema:
            type: string
        X-Credits-Used:
          schema:
            type: integer
        X-Credits-Remaining:
          schema:
            type: string
        X-Cache:
          schema:
            type: string
            enum:
              - HIT
              - MISS
              - BYPASS
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/SocialQueryError'
    Error404:
      description: Endpoint or upstream resource not found.
      headers:
        X-Request-Id:
          schema:
            type: string
        X-Credits-Used:
          schema:
            type: integer
        X-Credits-Remaining:
          schema:
            type: string
        X-Cache:
          schema:
            type: string
            enum:
              - HIT
              - MISS
              - BYPASS
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/SocialQueryError'
    Error405:
      description: HTTP method is not supported.
      headers:
        X-Request-Id:
          schema:
            type: string
        X-Credits-Used:
          schema:
            type: integer
        X-Credits-Remaining:
          schema:
            type: string
        X-Cache:
          schema:
            type: string
            enum:
              - HIT
              - MISS
              - BYPASS
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/SocialQueryError'
    Error409:
      description: Idempotency conflict or request in progress.
      headers:
        X-Request-Id:
          schema:
            type: string
        X-Credits-Used:
          schema:
            type: integer
        X-Credits-Remaining:
          schema:
            type: string
        X-Cache:
          schema:
            type: string
            enum:
              - HIT
              - MISS
              - BYPASS
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/SocialQueryError'
    Error422:
      description: Invalid parameters.
      headers:
        X-Request-Id:
          schema:
            type: string
        X-Credits-Used:
          schema:
            type: integer
        X-Credits-Remaining:
          schema:
            type: string
        X-Cache:
          schema:
            type: string
            enum:
              - HIT
              - MISS
              - BYPASS
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/SocialQueryError'
    Error429:
      description: Request limit reached.
      headers:
        X-Request-Id:
          schema:
            type: string
        X-Credits-Used:
          schema:
            type: integer
        X-Credits-Remaining:
          schema:
            type: string
        X-Cache:
          schema:
            type: string
            enum:
              - HIT
              - MISS
              - BYPASS
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/SocialQueryError'
    Error500:
      description: Request processing failed.
      headers:
        X-Request-Id:
          schema:
            type: string
        X-Credits-Used:
          schema:
            type: integer
        X-Credits-Remaining:
          schema:
            type: string
        X-Cache:
          schema:
            type: string
            enum:
              - HIT
              - MISS
              - BYPASS
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/SocialQueryError'
    Error502:
      description: Upstream service failed.
      headers:
        X-Request-Id:
          schema:
            type: string
        X-Credits-Used:
          schema:
            type: integer
        X-Credits-Remaining:
          schema:
            type: string
        X-Cache:
          schema:
            type: string
            enum:
              - HIT
              - MISS
              - BYPASS
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/SocialQueryError'
    Error503:
      description: Provider or required service is unavailable.
      headers:
        X-Request-Id:
          schema:
            type: string
        X-Credits-Used:
          schema:
            type: integer
        X-Credits-Remaining:
          schema:
            type: string
        X-Cache:
          schema:
            type: string
            enum:
              - HIT
              - MISS
              - BYPASS
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/SocialQueryError'
    Error504:
      description: Upstream service timed out.
      headers:
        X-Request-Id:
          schema:
            type: string
        X-Credits-Used:
          schema:
            type: integer
        X-Credits-Remaining:
          schema:
            type: string
        X-Cache:
          schema:
            type: string
            enum:
              - HIT
              - MISS
              - BYPASS
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/SocialQueryError'
  securitySchemes:
    apiKey:
      type: apiKey
      in: header
      name: x-api-key

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.