> ## Documentation Index > Fetch the complete documentation index at: https://docs.agentkey.app/llms.txt > Use this file to discover all available pages before exploring further. # ecommerce.tiktok_shop.product.rank > Best-selling / trending product listings on TikTok Shop, optionally within a category. Returns a normalized Product page. ## OpenAPI ````yaml api-reference/openapi/v2.yaml POST /v2/ops/ecommerce.tiktok_shop.product.rank openapi: 3.1.0 info: description: >- Fixed, versioned, provider-independent methods over AgentKey's upstream catalog. Each method has a stable name, input schema and output schema; the server picks the upstream provider, fails over, normalizes fields and refunds failed attempts. Every response names the provider that served it, the credits charged and every attempt made. title: AgentKey Scenario Methods version: '2' servers: - url: https://api.agentkey.app security: [] paths: /v2/ops/ecommerce.tiktok_shop.product.rank: post: tags: - ecommerce/tiktok_shop summary: >- Best-selling / trending product listings on TikTok Shop, optionally within a category. Returns a normalized Product page. description: >- The platform's own best-seller or trending ranking on TikTok Shop. Pass a category when the platform ranks per category. Normalized to the Product object; page with next_cursor. Fixed price: 0.2 credits per successful call, whichever provider serves it. operationId: ecommerce_tiktok_shop_product_rank requestBody: content: application/json: schema: additionalProperties: false properties: category: description: >- Numeric TikTok Shop category id (required on TikTok Shop: the upstream lists products per category only; e.g. 601152 Beauty & Personal Care, 601739 Phones & Electronics). type: string cursor: description: >- Opaque pagination cursor from the previous response's next_cursor. Send the same parameters with it. type: string fields: $ref: '#/components/schemas/FieldsProjection' include_raw: $ref: '#/components/schemas/IncludeRaw' limit: default: 20 description: Maximum number of products to return. maximum: 20 minimum: 1 type: integer provider: $ref: '#/components/schemas/ProviderShorthand' region: default: US description: TikTok Shop market (ISO 3166-1 alpha-2). enum: - US - GB - SG - MY - PH - TH - VN - ID type: string routing: $ref: '#/components/schemas/Routing' type: object required: true responses: '200': content: application/json: schema: $ref: '#/components/schemas/ProductPageEnvelope' description: Success envelope '400': $ref: '#/components/responses/ValidationError' '402': $ref: '#/components/responses/InsufficientCredits' '404': $ref: '#/components/responses/NotFound' '429': $ref: '#/components/responses/RateLimited' '502': $ref: '#/components/responses/UpstreamFailed' '504': $ref: '#/components/responses/Timeout' security: - ApiKeyAuth: [] components: schemas: FieldsProjection: description: >- Projection: keep only these dotted paths of data, e.g. ["items.id", "items.text"]. items: type: string type: array IncludeRaw: default: false description: >- Attach the raw upstream payload as `raw` (not a stable contract; truncated above 256 KB). type: boolean ProviderShorthand: description: Shorthand for routing.only = [provider]. type: string Routing: additionalProperties: false description: >- Provider routing override. order: try these providers first; only: restrict to these (equivalent to pinning); allow_fallbacks: false tries only the first eligible provider. properties: allow_fallbacks: default: true description: false = try only the first eligible provider. type: boolean only: description: Restrict to these providers. items: type: string type: array order: description: Providers to try first, in order. items: type: string type: array strategy: default: auto description: >- How eligible providers are ordered. auto = the method's curated order. fastest / stable / popular are specified but not implemented yet (400 until then). The price is fixed whatever the strategy; mutually exclusive with order. enum: - auto type: string type: object ProductPageEnvelope: allOf: - $ref: '#/components/schemas/Envelope' - properties: data: $ref: '#/components/schemas/ProductPage' type: object description: Success envelope whose data is a ProductPage. Envelope: description: Success envelope. `data` is the method's output object. properties: attempts: items: $ref: '#/components/schemas/Attempt' type: array credits_charged: description: Credits charged for this call (the method's fixed price). type: number data: description: Method output (typed per method). op: description: Method name. type: string op_version: description: Method version that served the call. type: integer provider: description: Provider that actually served the call. type: string raw: description: Upstream payload, only with include_raw=true. Not a stable contract. raw_truncated: type: boolean request_id: description: Correlation id; quote it in support requests. type: string took_ms: type: integer unsupported_fields: description: >- Output paths this provider structurally does not supply; such fields are null for a different reason than 'missing on this record'. items: type: string type: array required: - op - op_version - provider - request_id - credits_charged - took_ms - attempts - unsupported_fields - data type: object ProductPage: additionalProperties: false description: One page of products. properties: items: items: $ref: '#/components/schemas/Product' type: array next_cursor: description: >- Opaque cursor for the next page; null when the result set is exhausted or the provider cannot page. Send it back unchanged with the same query parameters. type: - string - 'null' required: - items - next_cursor type: object ErrorEnvelope: properties: attempts: items: $ref: '#/components/schemas/Attempt' type: array code: type: integer error: description: Human-readable message. type: string error_type: description: >- validation | not_found | rate_limit | timeout | insufficient_credits | upstream_unauthorized | upstream_unavailable | provider_error type: string op: description: Method name. type: string request_id: description: Correlation id. type: string required: - error - code - error_type type: object Attempt: description: >- One upstream try. Present on success and failure so a failover is never invisible. properties: error_type: description: >- validation | not_found | rate_limit | timeout | upstream_unauthorized | upstream_unavailable | provider_error type: string provider: description: Provider slug. type: string refunded: description: true when the reservation for this attempt was refunded. type: boolean status: description: HTTP status AgentKey mapped this attempt to (200 on success). type: integer took_ms: type: integer tool: description: Registry tool name (Provider/operation) that was called. type: string upstream_status: description: The provider's real HTTP status; absent when nothing was received. type: integer required: - provider - tool - status - took_ms type: object Product: additionalProperties: false description: A product listing on an ecommerce platform, normalized across providers. properties: brand: description: Brand name when the platform reports one. type: - string - 'null' category: description: Platform category name (leaf) when reported. type: - string - 'null' description: description: >- Listing description / selling points as plain text; null when the endpoint returns only a card. type: - string - 'null' id: description: >- Platform-native product / item ID (ASIN on Amazon, item id on Taobao). type: string image_url: description: Main listing image URL (the cover every search card carries). type: - string - 'null' images: description: >- Listing image URLs, main image first. null when the provider exposes no images at all. items: type: string type: - array - 'null' in_stock: description: >- Whether the listing is purchasable right now; null when not reported. type: - boolean - 'null' monthly_sales_count: description: >- Units sold in the past month when that is what the platform shows (Amazon's "500+ bought in past month" badge, Douyin Shop's "月销" on search cards and shop listings). Not comparable with sales_count. type: - integer - 'null' platform: description: Platform slug, identical to the one in the method name. type: string price: description: >- Current price. amount is the displayed selling price; original_amount the struck-through list price when there is a discount. properties: amount: description: Selling price in major units (12.5 = 12.50). type: - number - 'null' currency: description: ISO 4217 currency code (CNY, USD, SGD …). type: - string - 'null' original_amount: description: List / pre-discount price when shown; null otherwise. type: - number - 'null' required: - amount - currency - original_amount type: object rating: properties: count: description: Number of ratings / reviews. type: - integer - 'null' score: description: >- Average rating on the platform's own scale (Amazon 0–5, Taobao 0–5). type: - number - 'null' required: - score - count type: object sales_count: description: >- Cumulative units sold / "已售" counter when the platform exposes one (approximate on platforms that report "1万+"). Platforms that only show a past-month figure report it in monthly_sales_count instead. type: - integer - 'null' sales_text: description: >- The platform's own sales line as displayed ("1万+人收货", "1.8K+ sold", "500+ bought in past month"); sales_count or monthly_sales_count is the number read from it. type: - string - 'null' shop: description: The seller of the listing. properties: id: description: Platform-native shop / seller ID. type: - string - 'null' name: description: Shop display name. type: - string - 'null' url: description: Shop page URL. type: - string - 'null' required: - id - name - url type: object title: description: Listing title. type: string url: description: Canonical product page URL. type: - string - 'null' required: - id - url - platform - title - description - brand - category - price - rating - sales_count - monthly_sales_count - sales_text - in_stock - image_url - images - shop type: object responses: ValidationError: content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' description: Validation error (unknown field, bad cursor, bad routing) InsufficientCredits: content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' description: Insufficient credits NotFound: content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' description: Not found (method, or upstream object) RateLimited: content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' description: Rate limited upstream UpstreamFailed: content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' description: All providers failed Timeout: content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' description: Timed out securitySchemes: ApiKeyAuth: description: AgentKey API key (ak_…). scheme: bearer type: http ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.