Every API here is available over the APIs.io API and to AI agents over MCP.
openapi: 3.2.0
info:
title: Insightsocial App Tiktokshop API
version: 2.0.0
description: 'Operations tagged tiktokshop across 2 of this provider''s published API definitions: openapi.json, insightsocial-app-openapi.json. Each path carries the servers of the definition it was published in.'
servers:
- url: https://api.insightsocial.app
security:
- apiKey: []
tags:
- name: tiktok shop
paths:
/v1/tiktokshop/product:
get:
operationId: tiktokshop_product
summary: Product
description: 'Returns one TikTok Shop product in full: description, price and discount, rating, review count, brand, specs, stock, seller details, shipping estimate, and images.
Use it when you have a product URL or ID and need the full listing; use products to list a storefront''s catalogue, or search to find products by keyword.
**Metered: 10–40 credits.** We reserve the ceiling when the call starts and charge what it actually used when it finishes.'
tags:
- tiktok shop
parameters:
- name: url
in: query
required: false
description: 'Full URL of the TikTok Shop product page (`www.tiktok.com/shop/pdp/...` or `shop.tiktok.com/.../pdp/...`). Provide this or `product_id`. Provide at least one of: `url`, `product_id`.'
schema:
type: string
example: https://www.tiktok.com/shop/pdp/goli-ashwagandha-gummies-with-vitamin-d-ksm-66-vegan-non-gmo/1729587769570529799
- name: product_id
in: query
required: false
description: 'Numeric TikTok Shop product id, as returned in `product.id` by tiktokshop/search, tiktokshop/products and tiktokshop/user/showcase. Provide this or `url`. Provide at least one of: `url`, `product_id`.'
schema:
type: string
example: '1729587769570529799'
- name: region
in: query
required: false
description: 'ISO 3166-1 alpha-2 region for the lookup. Default US. Served: US, GB, ID, SG, MY, TH, VN, PH. Other values are rejected before billing.'
schema:
type: string
enum:
- US
- GB
- ID
- MY
- TH
- SG
- VN
- PH
- name: include
in: query
required: false
description: Set to `details` (one token only) to add the listing description (`product.description`), brand, specifications, and the shipping fee, free-shipping flag, delivery estimate and official-shop badge (`shop_identity`) under `product.ext.tiktokshop` when the plain call came back without them.
schema:
type: string
enum:
- details
- name: max_age_s
in: query
required: false
description: 'The oldest cached copy you accept, in seconds. A copy that old or younger is served, with its age in `age_s` and the `X-Cache-Age` header. Without it a copy up to 600 seconds old is served; this endpoint keeps copies for 3600 seconds, so a value up to 3600 can save a call. A lower value fetches fresh (billed) when the copy is older, and 0 always fetches live, like `Cache-Control: no-cache`.'
schema:
type: integer
minimum: 0
maximum: 3600
- name: dry_run
in: query
required: false
description: 'Set to 1 to get the price of this call without making it: data.dry_run carries credits_min and credits_max. Nothing is charged.'
schema:
type: string
enum:
- '1'
x-credits:
min: 10
max: 40
x-group: Product
responses:
'200':
description: Success.
content:
application/json:
schema:
allOf:
- $ref: '#/components/schemas/Envelope2'
- type: object
properties:
data:
$ref: '#/components/schemas/ConventionsData'
'400':
$ref: '#/components/responses/Error'
'401':
$ref: '#/components/responses/Error'
'402':
$ref: '#/components/responses/Error'
'404':
$ref: '#/components/responses/Error'
'409':
$ref: '#/components/responses/Error'
'429':
$ref: '#/components/responses/Error'
'500':
$ref: '#/components/responses/Error'
'503':
$ref: '#/components/responses/Error'
x-stability: beta
servers:
- url: https://api.insightsocial.app
/v1/tiktokshop/product/reviews:
get:
operationId: tiktokshop_product_reviews
summary: Product › Reviews
description: 'Returns reviews on a TikTok Shop product: rating, text, author, buyer country, verified-purchase and incentivized-review flags, the purchased SKU, and a timestamp.
Use it when you have a product URL or ID and want what buyers say; use product for the listing itself.
**10 credits** per call.
Paginates by `cursor`: see Pagination.'
tags:
- tiktok shop
parameters:
- name: url
in: query
required: false
description: 'Full URL of the TikTok Shop product page. Provide this or `product_id`. Provide at least one of: `url`, `product_id`.'
schema:
type: string
example: https://www.tiktok.com/shop/pdp/cat-nail-clipper-by-potaroma-adjustable-sizes-built-in-file-safe-for-kittens-cats/1731578642912612516
- name: product_id
in: query
required: false
description: 'The ID of the product (required if url is not provided). Provide at least one of: `url`, `product_id`.'
schema:
type: string
- name: region
in: query
required: false
description: ISO 3166-1 alpha-2 region for the product (e.g. `US`). Important when the product is regionally scoped.
schema:
type: string
enum:
- US
- GB
- DE
- FR
- IT
- ID
- MY
- MX
- PH
- SG
- ES
- TH
- VN
- BR
- JP
- IE
- name: page
in: query
required: false
description: Page number to retrieve, 10 reviews per page. Prefer passing back `pagination.next_cursor`, which carries the same position and stays correct if the underlying paging mechanism changes.
schema:
type: integer
minimum: 1
- name: dry_run
in: query
required: false
description: 'Set to 1 to get the price of this call without making it: data.dry_run carries credits_min and credits_max. Nothing is charged.'
schema:
type: string
enum:
- '1'
- name: since
in: query
required: false
description: 'Only rows published on or after this date: YYYY-MM-DD (midnight UTC) or an ISO 8601 timestamp. Rows older than it are left off each page. This list is not in date order, so the walk does not stop at the date: keep following `next_cursor`, and each page costs what a page costs even when every row on it is filtered out. A row with no date is kept.'
schema:
type: string
- name: until
in: query
required: false
description: 'Only rows published on or before this date: YYYY-MM-DD (that whole UTC day is included) or an ISO 8601 timestamp. Newer rows are left off each page and the walk does not stop, so older pages follow. A row with no date is kept.'
schema:
type: string
- name: max_pages
in: query
required: false
description: 1 to 50 (default 1). Walk up to this many pages in one call and return the rows from all of them.
schema:
type: integer
minimum: 1
maximum: 50
- name: max_age_s
in: query
required: false
description: 'The oldest cached copy you accept, in seconds. A copy that old or younger is served, with its age in `age_s` and the `X-Cache-Age` header. Without it a copy up to 300 seconds old is served. A lower value fetches fresh (billed) when the copy is older, and 0 always fetches live, like `Cache-Control: no-cache`.'
schema:
type: integer
minimum: 0
maximum: 300
- name: cursor
in: query
required: false
description: The `pagination.next_cursor` from the previous page, sent back unchanged. Omit it for the first page.
schema:
type: string
x-credits: 10
x-group: Product
responses:
'200':
description: Success.
content:
application/json:
schema:
allOf:
- $ref: '#/components/schemas/Envelope2'
- type: object
properties:
data:
$ref: '#/components/schemas/ConventionsData'
'400':
$ref: '#/components/responses/Error'
'401':
$ref: '#/components/responses/Error'
'402':
$ref: '#/components/responses/Error'
'404':
$ref: '#/components/responses/Error'
'409':
$ref: '#/components/responses/Error'
'429':
$ref: '#/components/responses/Error'
'500':
$ref: '#/components/responses/Error'
'503':
$ref: '#/components/responses/Error'
x-stability: beta
servers:
- url: https://api.insightsocial.app
/v1/tiktokshop/products:
get:
operationId: tiktokshop_products
summary: Products
description: 'Returns the products listed on a TikTok Shop storefront: title, images, canonical URL, price and discount, sold count, review count, rating, SKU ID, and the shop''s own profile.
Use it when you have a storefront URL and want everything it sells; use search to find products across storefronts by keyword.
**10 credits** per call.
Paginates by `cursor`: see Pagination.'
tags:
- tiktok shop
parameters:
- name: url
in: query
required: true
description: Full URL of the TikTok Shop page
schema:
type: string
example: https://www.tiktok.com/shop/store/goli-nutrition/7495794203056835079
- name: sort_by
in: query
required: false
description: Sort products by best-selling (`top`) or newest (`new_releases`). Defaults to `top`.
schema:
type: string
enum:
- top
- new_releases
- name: region
in: query
required: false
description: Region to get shop products from. A storefront is only reachable from its own market, so a GB shop needs `region=GB`; the default is US. Prices are decimal amounts in the major unit of `price.currency`, and each row's price belongs to the SKU in `product.ext.sku_id`.
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
description: Pagination cursor. Pass back `pagination.next_cursor` from the previous response.
schema:
type: string
- name: max_pages
in: query
required: false
description: 1 to 50 (default 1). Walk up to this many pages in one call and return the rows from all of them.
schema:
type: integer
minimum: 1
maximum: 50
- name: max_age_s
in: query
required: false
description: 'The oldest cached copy you accept, in seconds. A copy that old or younger is served, with its age in `age_s` and the `X-Cache-Age` header. Without it a copy up to 600 seconds old is served; this endpoint keeps copies for 3600 seconds, so a value up to 3600 can save a call. A lower value fetches fresh (billed) when the copy is older, and 0 always fetches live, like `Cache-Control: no-cache`.'
schema:
type: integer
minimum: 0
maximum: 3600
- name: dry_run
in: query
required: false
description: 'Set to 1 to get the price of this call without making it: data.dry_run carries credits_min and credits_max. Nothing is charged.'
schema:
type: string
enum:
- '1'
x-credits: 10
x-group: Products
responses:
'200':
description: Success.
content:
application/json:
schema:
allOf:
- $ref: '#/components/schemas/Envelope2'
- type: object
properties:
data:
$ref: '#/components/schemas/ConventionsData'
'400':
$ref: '#/components/responses/Error'
'401':
$ref: '#/components/responses/Error'
'402':
$ref: '#/components/responses/Error'
'404':
$ref: '#/components/responses/Error'
'409':
$ref: '#/components/responses/Error'
'429':
$ref: '#/components/responses/Error'
'500':
$ref: '#/components/responses/Error'
'503':
$ref: '#/components/responses/Error'
x-stability: beta
servers:
- url: https://api.insightsocial.app
/v1/tiktokshop/search:
get:
operationId: tiktokshop_search
summary: Search
description: 'Returns TikTok Shop products matching a keyword across every storefront, each with price, rating, sold count, seller trust label, ship-from location, and promotion badges.
Use it to find products by keyword across every storefront; use products when you already know the storefront.
**10 credits** per call.
Paginates by `cursor`: see Pagination.'
tags:
- tiktok shop
parameters:
- name: query
in: query
required: true
description: Search keyword or phrase to find TikTok Shop products
schema:
type: string
example: phone case
- name: page
in: query
required: false
description: Page number to retrieve. Prefer passing back `pagination.next_cursor`, which carries the same position.
schema:
type: integer
minimum: 1
- name: region
in: query
required: false
description: Region to search shop products in. Results, prices and currency follow the market; defaults to US. `price.current` and `price.original` are always decimal amounts in the major unit of `price.currency` in every region (10.90 means 10.90 EUR). Search rows do not name the SKU a price belongs to (`product.ext.sku_id` is null); `tiktokshop/products` on the seller's storefront names it.
schema:
type: string
enum:
- US
- GB
- DE
- FR
- IT
- ID
- MY
- MX
- PH
- SG
- ES
- TH
- VN
- BR
- JP
- IE
- name: max_pages
in: query
required: false
description: 1 to 50 (default 1). Walk up to this many pages in one call and return the rows from all of them.
schema:
type: integer
minimum: 1
maximum: 50
- name: max_age_s
in: query
required: false
description: 'The oldest cached copy you accept, in seconds. A copy that old or younger is served, with its age in `age_s` and the `X-Cache-Age` header. Without it a copy up to 120 seconds old is served. A lower value fetches fresh (billed) when the copy is older, and 0 always fetches live, like `Cache-Control: no-cache`.'
schema:
type: integer
minimum: 0
maximum: 120
- name: cursor
in: query
required: false
description: The `pagination.next_cursor` from the previous page, sent back unchanged. Omit it for the first page.
schema:
type: string
- name: dry_run
in: query
required: false
description: 'Set to 1 to get the price of this call without making it: data.dry_run carries credits_min and credits_max. Nothing is charged.'
schema:
type: string
enum:
- '1'
x-credits: 10
x-group: Search
responses:
'200':
description: Success.
content:
application/json:
schema:
allOf:
- $ref: '#/components/schemas/Envelope2'
- type: object
properties:
data:
$ref: '#/components/schemas/ConventionsData'
'400':
$ref: '#/components/responses/Error'
'401':
$ref: '#/components/responses/Error'
'402':
$ref: '#/components/responses/Error'
'404':
$ref: '#/components/responses/Error'
'409':
$ref: '#/components/responses/Error'
'429':
$ref: '#/components/responses/Error'
'500':
$ref: '#/components/responses/Error'
'503':
$ref: '#/components/responses/Error'
x-stability: beta
servers:
- url: https://api.insightsocial.app
/v1/tiktokshop/user/showcase:
get:
operationId: tiktokshop_user_showcase
summary: User › Showcase
description: 'Returns the products featured in a TikTok user''s public showcase: title, price and discount, rating, sold count, images, and SKU ID.
Use it when you have a creator''s handle and want the products they promote; use product for one of those listings in full.
**10 credits** per call.
Paginates by `cursor`: see Pagination.'
tags:
- tiktok shop
parameters:
- name: handle
in: query
required: true
description: The handle of the user
schema:
type: string
example: mrtiktokreviews
- name: region
in: query
required: false
description: Region the lookup is served from. US only for now; other regions are rejected before billing.
schema:
type: string
enum:
- US
- name: cursor
in: query
required: false
description: The `next_cursor` from the previous page. A cursor from deep in a large showcase stays valid for 7 days; an expired one is a free 400, and the walk restarts from the first page.
schema:
type: string
- name: max_pages
in: query
required: false
description: 1 to 50 (default 1). Walk up to this many pages in one call and return the rows from all of them.
schema:
type: integer
minimum: 1
maximum: 50
- name: max_age_s
in: query
required: false
description: 'The oldest cached copy you accept, in seconds. A copy that old or younger is served, with its age in `age_s` and the `X-Cache-Age` header. Without it a copy up to 600 seconds old is served; this endpoint keeps copies for 3600 seconds, so a value up to 3600 can save a call. A lower value fetches fresh (billed) when the copy is older, and 0 always fetches live, like `Cache-Control: no-cache`.'
schema:
type: integer
minimum: 0
maximum: 3600
- name: dry_run
in: query
required: false
description: 'Set to 1 to get the price of this call without making it: data.dry_run carries credits_min and credits_max. Nothing is charged.'
schema:
type: string
enum:
- '1'
x-credits: 10
x-group: User
responses:
'200':
description: Success.
content:
application/json:
schema:
allOf:
- $ref: '#/components/schemas/Envelope2'
- type: object
properties:
data:
$ref: '#/components/schemas/ConventionsData'
'400':
$ref: '#/components/responses/Error'
'401':
$ref: '#/components/responses/Error'
'402':
$ref: '#/components/responses/Error'
'404':
$ref: '#/components/responses/Error'
'409':
$ref: '#/components/responses/Error'
'429':
$ref: '#/components/responses/Error'
'500':
$ref: '#/components/responses/Error'
'503':
$ref: '#/components/responses/Error'
x-stability: beta
servers:
- url: https://api.insightsocial.app
/v1/tiktokshop/sales:
get:
operationId: tiktokshop_sales
summary: Sales
description: 'Returns, per market, listings found, their units sold added up, an estimated sales figure in local currency, and the top listings by units for a keyword.
Use it to compare a keyword''s unit sales across several markets in one call; use search directly when you only need one market''s listings.
**Metered: 0–80 credits.** We reserve the ceiling when the call starts and charge what it actually used when it finishes.'
tags:
- tiktok shop
parameters:
- name: query
in: query
required: true
description: Product keyword, sent unchanged to each market's search (1-200 characters).
schema:
type: string
example: lip gloss
- name: regions
in: query
required: false
description: 'Comma-separated markets, up to 8: US, GB, DE, FR, IT, ES, IE, ID, MY, MX, PH, SG, TH, VN, BR, JP. Default US.'
schema:
type: string
example: US,GB,MY
- name: top
in: query
required: false
description: How many top listings by units to return per market, 1 to 20. Default 5.
schema:
type: integer
minimum: 1
maximum: 20
- name: max_age_s
in: query
required: false
description: 'The oldest cached copy you accept, in seconds. A copy that old or younger is served, with its age in `age_s` and the `X-Cache-Age` header. Without it a copy up to 900 seconds old is served. A lower value fetches fresh (billed) when the copy is older, and 0 always fetches live, like `Cache-Control: no-cache`.'
schema:
type: integer
minimum: 0
maximum: 900
- name: dry_run
in: query
required: false
description: 'Set to 1 to get the price of this call without making it: data.dry_run carries credits_min and credits_max. Nothing is charged.'
schema:
type: string
enum:
- '1'
x-credits:
min: 0
max: 80
x-group: Sales
responses:
'200':
description: Success.
content:
application/json:
schema:
allOf:
- $ref: '#/components/schemas/Envelope2'
- type: object
properties:
data:
$ref: '#/components/schemas/ConventionsData'
'400':
$ref: '#/components/responses/Error'
'401':
$ref: '#/components/responses/Error'
'402':
$ref: '#/components/responses/Error'
'404':
$ref: '#/components/responses/Error'
'409':
$ref: '#/components/responses/Error'
'429':
$ref: '#/components/responses/Error'
'500':
$ref: '#/components/responses/Error'
'503':
$ref: '#/components/responses/Error'
x-stability: beta
servers:
- url: https://api.insightsocial.app
components:
schemas:
Pagination:
type: object
properties:
next_cursor:
type:
- string
- 'null'
has_more:
type: boolean
page_size:
type: integer
minimum: 0
maximum: 9007199254740991
stopped_at:
anyOf:
- type: string
enum:
- since
- known_id
- end
- type: 'null'
required:
- next_cursor
- has_more
- page_size
additionalProperties: false
Envelope2:
type: object
properties:
success:
type: boolean
const: true
platform:
type: string
endpoint:
type: string
schema_version:
type: string
const: '2'
data: {}
pagination:
$ref: '#/components/schemas/Pagination'
unavailable:
type: array
items:
type: string
credits_used:
type: integer
minimum: 0
maximum: 9007199254740991
credits_remaining:
type: integer
minimum: 0
maximum: 9007199254740991
request_id:
type: string
cached:
type: boolean
idempotent_replay:
type: boolean
charge_reason:
type: string
free_call:
type: boolean
required:
- success
- platform
- endpoint
- schema_version
- data
- unavailable
- credits_used
- credits_remaining
- request_id
- cached
- idempotent_replay
- charge_reason
- free_call
additionalProperties: false
ConventionsData:
type: object
propertyNames:
type: string
pattern: ^[a-z0-9]+(?:_[a-z0-9]+)*$
additionalProperties:
$ref: '#/components/schemas/JsonValue'
x-stability: beta
JsonValue:
description: Any JSON value.
Error:
type: object
properties:
success:
type: boolean
const: false
error:
type: object
properties:
type:
type: string
message:
type: string
param:
type: string
top_up_url:
type: string
required:
- type
- message
additionalProperties: false
request_id:
type: string
credits_used:
type: integer
minimum: 0
maximum: 9007199254740991
credits_remaining:
anyOf:
- type: integer
minimum: 0
maximum: 9007199254740991
- type: 'null'
required:
- success
- error
- request_id
- credits_used
- credits_remaining
additionalProperties: false
responses:
Error:
description: See [Error handling](https://www.insightsocial.app/docs/errors).
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
example:
success: false
error:
type: INSUFFICIENT_CREDITS
message: 'This call needs up to 340 credits and 120 remain. Add credits: https://www.insightsocial.app/api/top-up?need=220&u=6f1c2b7e-0d4a-4c8e-9b21-3a5f7d9e1c40&via=api_402'
top_up_url: https://www.insightsocial.app/api/top-up?need=220&u=6f1c2b7e-0d4a-4c8e-9b21-3a5f7d9e1c40&via=api_402
request_id: req_1a2b3c4d5e6f
credits_used: 0
credits_remaining: 120
securitySchemes:
apiKey:
type: apiKey
in: header
name: x-api-key
description: Your key from the dashboard. It starts with `isk_`.
x-refined-from:
- openapi.json
- insightsocial-app-openapi.json
x-provenance:
method: harvested
publisher: InsightSocial
source: https://api.insightsocial.app/v1/openapi.json
note: split by refine-openapis from the provider's own published document, verified by fetch (openapi/_original/*.fetch.json);
stamped by stamp-openapi-provenance.py (roadmap#793)