> ## 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 post statistics

> Refresh public engagement counts for 1–100 post URLs, in input order. Supported platforms: YouTube, Bluesky, Instagram, TikTok and LinkedIn. Reserve one credit per URL, two for Instagram or five for LinkedIn; charge only successful rows and refund all not_found, error, unsupported and deferred rows. Unknown counts remain null. Reads current provider responses with no SocialQuery response cache. JSON only; include and SSE are unavailable. Four source workers, twelve-second source deadlines, and no new work after twenty-eight seconds. The serialized urls array must fit the 16,000-character parameter limit.

Pass 1–100 post links in `urls`. Rows retain the original URL and input order. Supported platforms are YouTube, Bluesky, Instagram, TikTok and LinkedIn. Other hosts return an unbilled `unsupported` row. A recognized platform with an invalid post path returns an unbilled `error`. The serialized array must fit 16,000 characters.

Each successful row contains `engagement` with nullable `views`, `likes`, `comments`, `shares`, `saves` and `reposts`, plus a server `fetched_at` timestamp. Missing metrics remain null. Bluesky reposts are not relabeled as shares. Instagram save/repost counts appear only if the source returns them; `include=saves` is not implemented. Counts are public provider observations, not complete private analytics. LinkedIn accepts canonical `/posts/...-activity-...` links; feed URNs and shortened redirects are not supported. Instagram accepts both `/p/code/` and `/<handle>/p/code/` permalinks, as well as reels.

The hold is one credit per URL, two for Instagram and five for LinkedIn. Every successful row costs that tier; `not_found`, `error`, `unsupported` and `deferred` rows cost zero. No result is charged unless the source identity matches and at least one valid engagement count is available. Only a definitive empty YouTube or Bluesky post result becomes `not_found`; other source failures stay `error`.

Four workers run at most twelve seconds per source lookup, with no new work started after twenty-eight seconds. Unstarted rows are deferred and refunded. A provider quota/authentication failure stops new requests to that provider. There is no SocialQuery response caching. Source freshness is provider-dependent. Use an `Idempotency-Key` for free replay; retry failed/deferred rows with a new key. SSE and `include` options return 422 before spending.

Sources: [YouTube Data API](https://developers.google.com/youtube/v3/docs/videos/list), [Bluesky](https://docs.bsky.app/docs/api/app-bsky-feed-get-posts), [ScrapeCreators](https://docs.scrapecreators.com/), and [ScrapeBadger](https://docs.scrapebadger.com/). Their available allowance determines live availability. MCP `execute_endpoint` and the Python skill calculate the full URL-based hold before calling; the Python skill also requires `--allow-mutation` and an idempotency key.


## OpenAPI

````yaml POST /prism/post-stats
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/post-stats:
    post:
      tags:
        - Prism
      summary: Batch public post statistics
      description: >-
        Refresh public engagement counts for 1–100 post URLs, in input order.
        Supported platforms: YouTube, Bluesky, Instagram, TikTok and LinkedIn.
        Reserve one credit per URL, two for Instagram or five for LinkedIn;
        charge only successful rows and refund all not_found, error, unsupported
        and deferred rows. Unknown counts remain null. Reads current provider
        responses with no SocialQuery response cache. JSON only; include and SSE
        are unavailable. Four source workers, twelve-second source deadlines,
        and no new work after twenty-eight seconds. The serialized urls array
        must fit the 16,000-character parameter limit.
      operationId: post_prism_post_stats
      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:
                - urls
              properties:
                urls:
                  type: array
                  minItems: 1
                  maxItems: 100
                  items:
                    type: string
                    minLength: 1
                    maxLength: 2048
                  example:
                    - https://www.youtube.com/watch?v=jNQXAC9IVRw
                include:
                  type: string
                  description: Not implemented; returns 422 before spending.
      responses:
        '200':
          description: >-
            Refresh public engagement counts for 1–100 post URLs, in input
            order. Supported platforms: YouTube, Bluesky, Instagram, TikTok and
            LinkedIn. Reserve one credit per URL, two for Instagram or five for
            LinkedIn; charge only successful rows and refund all not_found,
            error, unsupported and deferred rows. Unknown counts remain null.
            Reads current provider responses with no SocialQuery response cache.
            JSON only; include and SSE are unavailable. Four source workers,
            twelve-second source deadlines, and no new work after twenty-eight
            seconds. The serialized urls 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:
                                - url
                                - platform
                                - status
                                - engagement
                                - fetched_at
                                - credits_used
                                - ext
                              properties:
                                url:
                                  type: string
                                platform:
                                  type:
                                    - string
                                    - 'null'
                                status:
                                  type: string
                                  enum:
                                    - ok
                                    - not_found
                                    - error
                                    - unsupported
                                    - deferred
                                engagement:
                                  type:
                                    - object
                                    - 'null'
                                  properties:
                                    views:
                                      type:
                                        - integer
                                        - 'null'
                                      minimum: 0
                                    likes:
                                      type:
                                        - integer
                                        - 'null'
                                      minimum: 0
                                    comments:
                                      type:
                                        - integer
                                        - 'null'
                                      minimum: 0
                                    shares:
                                      type:
                                        - integer
                                        - 'null'
                                      minimum: 0
                                    saves:
                                      type:
                                        - integer
                                        - 'null'
                                      minimum: 0
                                    reposts:
                                      type:
                                        - integer
                                        - 'null'
                                      minimum: 0
                                fetched_at:
                                  type:
                                    - string
                                    - 'null'
                                  format: date-time
                                credits_used:
                                  type: integer
                                  minimum: 0
                                ext:
                                  type: object
                          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.