> ## 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.

# TikTok Shop Sales

> Aggregate one first-page product search per requested market (1–8 distinct markets). Reports observed lifetime units and current-price sales estimates in each market currency, listing coverage and top products. These are first-page listing estimates, not period sales or whole-market totals. Missing inputs are excluded with explicit coverage counts, never treated as zero. Empty/failed markets have null figures and cost zero; each nonempty market costs 1 credit. The request reserves one credit per market and settles only successful markets. Per-market request_id identifies the parent request, not separate billed child records. Partial failures are not cached. Provider free allowance is finite.

Send a keyword and up to eight comma-separated `regions`, for example `US,GB`. The adapter reads the same first-page product search used by `/v1/tiktokshop/search`. Duplicate markets are counted once; `top` selects 1–20 listings ranked by observed lifetime units sold (default 5).

Each market reports `listings`, `listings_with_sales`, `listings_with_estimate`, `units_sold`, `estimated_sales`, `currency`, `top_products` and completeness flags. Sales estimates multiply observed lifetime units by current prices. They are **first-page listing estimates**, not period sales or whole-market totals. Unknown inputs are excluded and disclosed; they never become zeros. Different calls can return different listings, so subtracting totals does not reliably measure period sales.

Empty or failed markets have null aggregate figures and cost zero. A nonempty market costs **1 credit**, even if its listings omit sales counts. The request reserves one credit for each requested distinct market, then releases unused credits. Set `X-Max-Credits` to the market count. Per-market `credits` describes original computation cost; the response envelope reports zero on cache or replay.

Per-market `request_id` is the parent API request ID. Separate child request records are not created. One market can fail while others succeed; inspect every `status`. Results containing failures are not cached. An all-failed collection is returned with `succeeded: 0` and no charge; it is not usable sales evidence.

<Note>This provider uses its existing free account within a non-resetting 10-source-request verification ceiling. Exhaustion fails closed. Ongoing funded capacity has not been configured; this is a bounded verified integration, not an availability guarantee.</Note>


## OpenAPI

````yaml GET /tiktokshop/sales
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:
  /tiktokshop/sales:
    get:
      tags:
        - TikTok Shop
      summary: TikTok Shop Sales
      description: >-
        Aggregate one first-page product search per requested market (1–8
        distinct markets). Reports observed lifetime units and current-price
        sales estimates in each market currency, listing coverage and top
        products. These are first-page listing estimates, not period sales or
        whole-market totals. Missing inputs are excluded with explicit coverage
        counts, never treated as zero. Empty/failed markets have null figures
        and cost zero; each nonempty market costs 1 credit. The request reserves
        one credit per market and settles only successful markets. Per-market
        request_id identifies the parent request, not separate billed child
        records. Partial failures are not cached. Provider free allowance is
        finite.
      operationId: get_tiktokshop_sales
      parameters:
        - name: query
          in: query
          required: true
          example: lip gloss
          schema:
            type: string
        - name: regions
          in: query
          required: false
          example: US,GB,MY
          schema:
            type: string
        - name: top
          in: query
          required: false
          schema:
            type: integer
            minimum: 1
            maximum: 20
        - 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
      responses:
        '200':
          description: >-
            Aggregate one first-page product search per requested market (1–8
            distinct markets). Reports observed lifetime units and current-price
            sales estimates in each market currency, listing coverage and top
            products. These are first-page listing estimates, not period sales
            or whole-market totals. Missing inputs are excluded with explicit
            coverage counts, never treated as zero. Empty/failed markets have
            null figures and cost zero; each nonempty market costs 1 credit. The
            request reserves one credit per market and settles only successful
            markets. Per-market request_id identifies the parent request, not
            separate billed child records. Partial failures are not cached.
            Provider free allowance is finite.
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/SocialQueryResponse'
                  - type: object
                    properties:
                      data:
                        type: object
                        properties:
                          query:
                            type: string
                          regions:
                            type: array
                            minItems: 1
                            maxItems: 8
                            items:
                              type: object
                              properties:
                                region:
                                  type: string
                                status:
                                  type: string
                                  enum:
                                    - ok
                                    - empty
                                    - failed
                                listings:
                                  type:
                                    - integer
                                    - 'null'
                                  minimum: 0
                                listings_with_sales:
                                  type:
                                    - integer
                                    - 'null'
                                  minimum: 0
                                listings_with_estimate:
                                  type:
                                    - integer
                                    - 'null'
                                  minimum: 0
                                units_sold:
                                  type:
                                    - integer
                                    - 'null'
                                  minimum: 0
                                estimated_sales:
                                  type:
                                    - number
                                    - 'null'
                                  minimum: 0
                                currency:
                                  type: string
                                top_products:
                                  type: array
                                  maxItems: 20
                                  items:
                                    type: object
                                    properties:
                                      id:
                                        type: string
                                      title:
                                        type: string
                                      url:
                                        type: string
                                      price:
                                        type:
                                          - number
                                          - 'null'
                                        minimum: 0
                                      units_sold:
                                        type: integer
                                        minimum: 0
                                      estimated_sales:
                                        type:
                                          - number
                                          - 'null'
                                        minimum: 0
                                    required:
                                      - id
                                      - title
                                      - url
                                      - price
                                      - units_sold
                                      - estimated_sales
                                    additionalProperties: false
                                sales_coverage_complete:
                                  type:
                                    - boolean
                                    - 'null'
                                estimate_coverage_complete:
                                  type:
                                    - boolean
                                    - 'null'
                                credits:
                                  type: integer
                                  minimum: 0
                                  maximum: 1
                                request_id:
                                  type: string
                                elapsed_ms:
                                  type: integer
                                  minimum: 0
                                error_code:
                                  type:
                                    - string
                                    - 'null'
                              required:
                                - region
                                - status
                                - listings
                                - listings_with_sales
                                - listings_with_estimate
                                - units_sold
                                - estimated_sales
                                - currency
                                - top_products
                                - sales_coverage_complete
                                - estimate_coverage_complete
                                - credits
                                - request_id
                                - elapsed_ms
                                - error_code
                              additionalProperties: false
                          markets_checked:
                            type: integer
                            minimum: 0
                          succeeded:
                            type: integer
                            minimum: 0
                          as_of:
                            type: string
                            format: date-time
                          coverage_note:
                            type: string
                        required:
                          - query
                          - regions
                          - markets_checked
                          - succeeded
                          - as_of
                          - coverage_note
                        additionalProperties: false
                    required:
                      - data
        '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.