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

> Search a current TikTok Shop product page in one of 16 markets. Canonical product wrappers preserve prices, ratings, seller IDs, observed sold counts and merchandising signals. Missing fields remain null. Explicit page 1–100 is supported; source page sizes vary and continuation metadata is absent, so cursor is rejected instead of fabricated. Market currencies are validated. Nonempty uncached pages cost 1 credit; confirmed empty pages, errors, cache hits and replays are free. Currently operates within a finite 10-source-request verification ceiling, not a funded ongoing plan.

Read product wrappers with `price.current`, `rating.average`, `image_urls`, seller name, and `ext.seller_id` / `ext.sold_count`. Missing sales and ratings remain null. Search merchandising fields live under `ext.tiktokshop`.

Use `query`, `region` (default US) and explicit `page` (1–100). US and GB have passed live source checks, including a second US page. The remaining documented markets are supported by source configuration but have not all been live-tested. Currency is validated; the source does not echo the requested region.

The upstream gives no total match count or continuation flag. Consequently, `total`, `has_more` and `next_cursor` are null. `cursor` returns free 422. Explicit page requests are available, but universal cursor parity remains incomplete.

Nonempty uncached pages cost **1 credit**. Empty pages, errors, cache hits and successful idempotent replays are free. Use `X-Max-Credits: 1` to cap billing.

<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/search
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/search:
    get:
      tags:
        - TikTok Shop
      summary: TikTok Shop Search
      description: >-
        Search a current TikTok Shop product page in one of 16 markets.
        Canonical product wrappers preserve prices, ratings, seller IDs,
        observed sold counts and merchandising signals. Missing fields remain
        null. Explicit page 1–100 is supported; source page sizes vary and
        continuation metadata is absent, so cursor is rejected instead of
        fabricated. Market currencies are validated. Nonempty uncached pages
        cost 1 credit; confirmed empty pages, errors, cache hits and replays are
        free. Currently operates within a finite 10-source-request verification
        ceiling, not a funded ongoing plan.
      operationId: get_tiktokshop_search
      parameters:
        - name: query
          in: query
          required: true
          example: phone case
          schema:
            type: string
        - name: page
          in: query
          required: false
          schema:
            type: integer
            minimum: 1
            maximum: 100
          deprecated: false
          description: >-
            Explicit source page, from 1 to 100. Page sizes vary. The provider
            does not publish continuation metadata.
        - name: region
          in: query
          required: false
          schema:
            type: string
            enum:
              - US
              - GB
              - DE
              - FR
              - IT
              - ID
              - MY
              - MX
              - PH
              - SG
              - ES
              - TH
              - VN
              - BR
              - JP
              - IE
        - name: cursor
          in: query
          required: false
          schema:
            type: string
          description: >-
            Unavailable for this source: returns free 422. Use an explicit page
            number; next_cursor and has_more remain null.
        - 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: >-
            Search a current TikTok Shop product page in one of 16 markets.
            Canonical product wrappers preserve prices, ratings, seller IDs,
            observed sold counts and merchandising signals. Missing fields
            remain null. Explicit page 1–100 is supported; source page sizes
            vary and continuation metadata is absent, so cursor is rejected
            instead of fabricated. Market currencies are validated. Nonempty
            uncached pages cost 1 credit; confirmed empty pages, errors, cache
            hits and replays are free. Currently operates within a finite
            10-source-request verification ceiling, not a funded ongoing plan.
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/SocialQueryResponse'
                  - type: object
                    properties:
                      data:
                        type: object
                        properties:
                          items:
                            type: array
                            maxItems: 100
                            items:
                              type: object
                              properties:
                                product:
                                  type: object
                                  properties:
                                    id:
                                      type: string
                                    title:
                                      type: string
                                    url:
                                      type: string
                                      format: uri
                                    description:
                                      type:
                                        - string
                                        - 'null'
                                    image_urls:
                                      type: array
                                      items:
                                        type: string
                                    price:
                                      type: object
                                      properties:
                                        current:
                                          type:
                                            - number
                                            - 'null'
                                          minimum: 0
                                        original:
                                          type:
                                            - number
                                            - 'null'
                                          minimum: 0
                                        currency:
                                          type: string
                                      required:
                                        - current
                                        - original
                                        - currency
                                      additionalProperties: false
                                    rating:
                                      type: object
                                      properties:
                                        average:
                                          type:
                                            - number
                                            - 'null'
                                          minimum: 0
                                          maximum: 5
                                        count:
                                          type:
                                            - integer
                                            - 'null'
                                          minimum: 0
                                      required:
                                        - average
                                        - count
                                      additionalProperties: false
                                    seller:
                                      type:
                                        - string
                                        - 'null'
                                    brand:
                                      type: 'null'
                                    availability:
                                      type: 'null'
                                    reviews_count:
                                      type:
                                        - integer
                                        - 'null'
                                      minimum: 0
                                    features:
                                      type: 'null'
                                    specifications:
                                      type: 'null'
                                    variations:
                                      type: 'null'
                                    ext:
                                      type: object
                                      properties:
                                        seller_id:
                                          type:
                                            - string
                                            - 'null'
                                        sold_count:
                                          type:
                                            - integer
                                            - 'null'
                                          minimum: 0
                                        tiktokshop:
                                          type: object
                                          properties:
                                            trust_label:
                                              type:
                                                - string
                                                - 'null'
                                            ships_from:
                                              type:
                                                - string
                                                - 'null'
                                            promotion_labels:
                                              type: array
                                              items:
                                                type: string
                                            category_breadcrumb:
                                              type:
                                                - array
                                                - 'null'
                                              items: {}
                                            video: {}
                                          required:
                                            - trust_label
                                            - ships_from
                                            - promotion_labels
                                            - category_breadcrumb
                                            - video
                                          additionalProperties: false
                                      required:
                                        - seller_id
                                        - sold_count
                                        - tiktokshop
                                      additionalProperties: false
                                  required:
                                    - id
                                    - title
                                    - url
                                    - description
                                    - image_urls
                                    - price
                                    - rating
                                    - seller
                                    - brand
                                    - availability
                                    - reviews_count
                                    - features
                                    - specifications
                                    - variations
                                    - ext
                                  additionalProperties: false
                              required:
                                - product
                              additionalProperties: false
                          returned_count:
                            type: integer
                            minimum: 0
                          total:
                            type: 'null'
                          next_cursor:
                            type: 'null'
                          query:
                            type: string
                          region:
                            type: string
                          currency:
                            type: string
                          page:
                            type: integer
                            minimum: 1
                            maximum: 100
                          has_more:
                            type: 'null'
                          coverage_note:
                            type: string
                        required:
                          - items
                          - returned_count
                          - total
                          - next_cursor
                          - query
                          - region
                          - currency
                          - page
                          - has_more
                          - 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.