openapi: 3.2.0 info: title: Monocrawl Tik Tok API version: 0.1.0 description: One key, one envelope, one credit meter across social, search, commerce and web data. contact: name: Monocrawl support url: https://www.monocrawl.com/contact termsOfService: https://www.monocrawl.com/legal/terms-and-conditions servers: - url: https://www.monocrawl.com security: - ApiKeyHeader: [] tags: - name: tiktok paths: /v1/tiktok/ads-top: get: operationId: tiktok_ads_top tags: - tiktok summary: Popular TikTok ads description: Creative Center popular ad selection. Includes public creative assets and source metrics. Cost bucket is not currency or spend; CTR is returned as supplied. Costs 1 credit per successful live response. parameters: - name: country in: query required: false schema: type: string example: US description: Two-letter uppercase country. - name: period in: query required: false schema: type: string enum: - '7' - '30' - '180' example: '7' description: 'Source window: 7, 30 or 180 days. Accepted values: 7, 30, 180. Case, spaces, hyphens and underscores are interchangeable.' - name: page in: query required: false schema: type: string example: '1' description: Page number, 1-100. - name: limit in: query required: false schema: type: string example: '20' description: Requested page size, 1–20 (default 20); the source may return fewer. - name: dry_run in: query required: false schema: type: string enum: - '1' - '0' - 'true' - 'false' example: '1' description: 'Read a zero-credit estimate without fetching sources, running AI, or reserving credits. Cache status is a snapshot, not a guarantee at execution. Accepted values: 1, 0, true, false. Case, spaces, hyphens and underscores are interchangeable.' - name: X-Max-Credits in: header required: false schema: type: integer minimum: 0 maximum: 9007199254740991 example: 5 description: Optional credit reservation ceiling for this individual request. Send a non-negative integer in decimal digits. Live execution checks the required reservation after resolving free cache hits or buffered continuation, before charging or calling a supplier. A higher reservation returns HTTP 422 INVALID_PARAMETERS with reason max_credits_exceeded and charges nothing. Invalid header values also return 422. Zero permits only a zero-credit reservation; omitting the header uses normal pricing. dry_run remains a free preview. This does not cap later requests, batches or scheduled runs. security: - ApiKeyHeader: [] - BearerKey: [] responses: '200': description: 'The common success envelope; `data` is endpoint-specific. Many lists use items/count/cursor; bundles use named collections and their documented continuation metadata. HTTP 200 can contain a partial bundle: inspect complete, partial and legs where supplied.' content: application/json: schema: allOf: - $ref: '#/components/schemas/Success' - type: object properties: data: $schema: https://json-schema.org/draft/2020-12/schema $id: https://www.monocrawl.com/schemas/tiktok/ads-top.json title: tiktok/ads-top data fields description: Optional data supplied by this operation. Null means unknown. type: object properties: _warnings: description: Optional warnings supplied by this operation. Null means unknown. type: - array - 'null' items: description: Optional record supplied by this operation. Null means unknown. type: - string - 'null' count: description: Number of records in this response, not lifetime or total matches. type: - number - 'null' country: description: Optional country supplied by this operation. Null means unknown. type: - string - 'null' has_more: description: Source continuation indicator; null means unknown. type: - boolean - 'null' items: description: Returned records. Source coverage and completeness vary. type: - array items: description: Optional record supplied by this operation. Null means unknown. type: object properties: brand_name: description: Optional brand name supplied by this operation. Null means unknown. type: - string - 'null' cost_bucket: description: Optional cost bucket supplied by this operation. Null means unknown. type: - number - 'null' ctr: description: Optional ctr supplied by this operation. Null means unknown. type: - number - 'null' duration_seconds: description: Optional duration seconds supplied by this operation. Null means unknown. type: - number - 'null' id: description: Source identifier. Preserve the supplied type and exact value. type: - string - 'null' industry_key: description: Optional industry key supplied by this operation. Null means unknown. type: - string - 'null' likes: description: Optional likes supplied by this operation. Null means unknown. type: - number - 'null' objective_key: description: Optional objective key supplied by this operation. Null means unknown. type: - string - 'null' platform: description: Optional platform supplied by this operation. Null means unknown. type: - string - 'null' text: description: Source text when supplied. type: - string - 'null' thumbnail_url: description: Optional thumbnail url supplied by this operation. Null means unknown. type: - string - 'null' video_urls: description: Optional video urls supplied by this operation. Null means unknown. type: - object - 'null' properties: {} additionalProperties: true additionalProperties: true allOf: - anyOf: - required: - brand_name properties: brand_name: description: Optional brand name supplied by this operation. Null means unknown. type: - string minLength: 1 - required: - cost_bucket properties: cost_bucket: description: Optional cost bucket supplied by this operation. Null means unknown. type: - number - required: - ctr properties: ctr: description: Optional ctr supplied by this operation. Null means unknown. type: - number - required: - duration_seconds properties: duration_seconds: description: Optional duration seconds supplied by this operation. Null means unknown. type: - number - required: - id properties: id: description: Source identifier. Preserve the supplied type and exact value. type: - string minLength: 1 - required: - industry_key properties: industry_key: description: Optional industry key supplied by this operation. Null means unknown. type: - string minLength: 1 - required: - likes properties: likes: description: Optional likes supplied by this operation. Null means unknown. type: - number - required: - objective_key properties: objective_key: description: Optional objective key supplied by this operation. Null means unknown. type: - string minLength: 1 - required: - text properties: text: description: Source text when supplied. type: - string minLength: 1 - required: - thumbnail_url properties: thumbnail_url: description: Optional thumbnail url supplied by this operation. Null means unknown. type: - string minLength: 1 - required: - video_urls properties: video_urls: description: Optional video urls supplied by this operation. Null means unknown. type: - object properties: {} additionalProperties: true next_page: description: Optional next page supplied by this operation. Null means unknown. type: - number - 'null' page: description: Optional page supplied by this operation. Null means unknown. type: - number - 'null' period: description: Optional period supplied by this operation. Null means unknown. type: - number - 'null' additionalProperties: true required: - items x-contract-version: '2026-09-22' x-validation-scope: Required success payload structure; optional fields and source completeness remain separate. examples: - _warnings: - example count: 0 country: example has_more: false items: - brand_name: example cost_bucket: 0 ctr: 0 duration_seconds: 0 id: example industry_key: example likes: 0 objective_key: example platform: example text: example thumbnail_url: https://example.com/example video_urls: {} next_page: 0 page: 0 period: 0 default: description: The error envelope — the same shape for every non-2xx status. content: application/json: schema: $ref: '#/components/schemas/Error' x-credits: 1 x-production-available: true x-capacity: status: not_assessed message: Capacity is workload-dependent; configured routes do not establish sustained throughput or an availability guarantee. x-availability-scope: Structural check of the effective registered chain, production permission, adapter, configured cost and quality floor without request parameters. True is not a live-health, credential, quota, subscription-entitlement, complete-data or deployment-exposure guarantee. False means no structurally eligible candidate; null means metadata could not establish availability. Composite child capability still depends on its component routes. x-live-proven: true /v1/tiktok/collection-videos: get: operationId: tiktok_collection_videos tags: - tiktok summary: TikTok collection videos description: The videos saved to a public collection, one page at a time, with the same video shape as the rest of the TikTok routes. Costs 1 credit per successful live response. parameters: - name: url in: query required: true schema: type: string example: https://www.tiktok.com/@tiktok/collection/favorites-7442134949027351314 description: Collection URL - name: cursor in: query required: false schema: type: string example: '' description: Opaque cursor from the previous page - name: dry_run in: query required: false schema: type: string enum: - '1' - '0' - 'true' - 'false' example: '1' description: 'Read a zero-credit estimate without fetching sources, running AI, or reserving credits. Cache status is a snapshot, not a guarantee at execution. Accepted values: 1, 0, true, false. Case, spaces, hyphens and underscores are interchangeable.' - name: judgments in: query required: false schema: type: string enum: - 'on' - 'off' example: 'on' description: 'Add bounded AI labels to eligible returned records (default on). off preserves the original data shape. Unclassified records remain present; labels depend on evidence, time, capacity and the existing request budget. No label surcharge. Accepted values: on, off. Case, spaces, hyphens and underscores are interchangeable.' - name: label in: query required: false schema: type: string enum: - default - none example: none description: 'Set none to disable labels; default enables the endpoint’s label set. Equivalent to judgments=off. Accepted values: default, none. Case, spaces, hyphens and underscores are interchangeable.' - name: label_evidence in: query required: false schema: type: string enum: - '1' - '0' - 'true' - 'false' example: '1' description: 'Include exact supporting sentences and zero-based sentence indexes when a label has validated evidence. No extra charge or change to decisions. Accepted values: 1, 0, true, false. Case, spaces, hyphens and underscores are interchangeable.' - name: exclude in: query required: false schema: type: string enum: - engagement_bait example: engagement_bait description: 'Optionally remove confidently labelled engagement bait. Uncertain and unclassified records stay; removed IDs and an owner-bound recall reference are returned. Accepted values: engagement_bait. Case, spaces, hyphens and underscores are interchangeable.' - name: fit in: query required: false schema: type: string enum: - goal example: goal description: 'Use goal to replace confidently irrelevant records with recall stubs. Keeps first, last, relevant and uncertain records; preserves order. Full evidence is stored for 24 hours when available. Accepted values: goal. Case, spaces, hyphens and underscores are interchangeable.' - name: goal in: query required: false schema: type: string example: Find concrete product complaints description: 'Required with fit=goal: describe the task in at most 600 characters. Supplied text is task context, never permission to act on posts.' - name: tokens in: query required: false schema: type: string example: '4000' description: Optional soft response target for fit=goal, 256–32000. Safety and evidence retention take priority, so the returned result may exceed it. - name: X-Max-Credits in: header required: false schema: type: integer minimum: 0 maximum: 9007199254740991 example: 5 description: Optional credit reservation ceiling for this individual request. Send a non-negative integer in decimal digits. Live execution checks the required reservation after resolving free cache hits or buffered continuation, before charging or calling a supplier. A higher reservation returns HTTP 422 INVALID_PARAMETERS with reason max_credits_exceeded and charges nothing. Invalid header values also return 422. Zero permits only a zero-credit reservation; omitting the header uses normal pricing. dry_run remains a free preview. This does not cap later requests, batches or scheduled runs. security: - ApiKeyHeader: [] - BearerKey: [] responses: '200': description: 'The common success envelope; `data` is endpoint-specific. Many lists use items/count/cursor; bundles use named collections and their documented continuation metadata. HTTP 200 can contain a partial bundle: inspect complete, partial and legs where supplied.' content: application/json: schema: allOf: - $ref: '#/components/schemas/Success' - type: object properties: data: $schema: https://json-schema.org/draft/2020-12/schema $id: https://www.monocrawl.com/schemas/tiktok/collection-videos.json title: tiktok/collection-videos data fields description: Optional data supplied by this operation. Null means unknown. type: object properties: collection_id: description: Optional collection id supplied by this operation. Null means unknown. type: - string - 'null' count: description: Number of records in this response, not lifetime or total matches. type: - number - 'null' dropped: description: Optional dropped supplied by this operation. Null means unknown. type: - number - 'null' has_more: description: Source continuation indicator; null means unknown. type: - boolean - 'null' items: description: Returned records. Source coverage and completeness vary. type: - array items: description: Optional record supplied by this operation. Null means unknown. type: object properties: author: description: Public author information supplied with this record. type: - object - 'null' properties: avatar_url: description: Optional avatar url supplied by this operation. Null means unknown. type: - string - 'null' followers: description: Optional followers supplied by this operation. Null means unknown. type: - number - 'null' handle: description: Optional handle supplied by this operation. Null means unknown. type: - string - 'null' id: description: Source identifier. Preserve the supplied type and exact value. type: - string - 'null' name: description: Optional name supplied by this operation. Null means unknown. type: - string - 'null' private: description: Optional private supplied by this operation. Null means unknown. type: - boolean - 'null' verified: description: Optional verified supplied by this operation. Null means unknown. type: - boolean - 'null' additionalProperties: true caption: description: Optional caption supplied by this operation. Null means unknown. type: - string - 'null' created_at: description: Source creation time, not the API retrieval time. type: - string - 'null' duration_s: description: Optional duration s supplied by this operation. Null means unknown. type: - number - 'null' hashtags: description: Optional hashtags supplied by this operation. Null means unknown. type: - array - 'null' items: description: Optional record supplied by this operation. Null means unknown. type: - object - 'null' properties: {} additionalProperties: true id: description: Source identifier. Preserve the supplied type and exact value. type: - string - 'null' images: description: Source array was empty in the reviewed captures; item fields remain unspecified. type: - array - 'null' items: {} is_ad: description: Optional is ad supplied by this operation. Null means unknown. type: - boolean - 'null' media_urls: description: Optional media urls supplied by this operation. Null means unknown. type: - array - 'null' items: description: Optional record supplied by this operation. Null means unknown. type: - string - 'null' music: description: Optional music supplied by this operation. Null means unknown. type: - object - 'null' properties: author: description: Public author information supplied with this record. type: - string - 'null' cover_url: description: Optional cover url supplied by this operation. Null means unknown. type: - string - 'null' duration_s: description: Optional duration s supplied by this operation. Null means unknown. type: - number - 'null' id: description: Source identifier. Preserve the supplied type and exact value. type: - string - 'null' is_original: description: Optional is original supplied by this operation. Null means unknown. type: - boolean - 'null' play_url: description: Optional play url supplied by this operation. Null means unknown. type: - string - 'null' title: description: Source title when supplied. type: - string - 'null' additionalProperties: true platform: description: Optional platform supplied by this operation. Null means unknown. type: - string - 'null' stats: description: Optional stats supplied by this operation. Null means unknown. type: - object - 'null' properties: comments: description: Optional comments supplied by this operation. Null means unknown. type: - number - 'null' likes: description: Optional likes supplied by this operation. Null means unknown. type: - number - 'null' plays: description: Optional plays supplied by this operation. Null means unknown. type: - number - 'null' saves: description: Optional saves supplied by this operation. Null means unknown. type: - number - 'null' shares: description: Optional shares supplied by this operation. Null means unknown. type: - number - 'null' additionalProperties: true thumbnail_url: description: Optional thumbnail url supplied by this operation. Null means unknown. type: - string - 'null' url: description: Original source URL when supplied. type: - string - 'null' video_url: description: Optional video url supplied by this operation. Null means unknown. type: - string - 'null' additionalProperties: true allOf: - anyOf: - required: - author properties: author: description: Public author information supplied with this record. type: - object properties: avatar_url: description: Optional avatar url supplied by this operation. Null means unknown. type: - string - 'null' followers: description: Optional followers supplied by this operation. Null means unknown. type: - number - 'null' handle: description: Optional handle supplied by this operation. Null means unknown. type: - string - 'null' id: description: Source identifier. Preserve the supplied type and exact value. type: - string - 'null' name: description: Optional name supplied by this operation. Null means unknown. type: - string - 'null' private: description: Optional private supplied by this operation. Null means unknown. type: - boolean - 'null' verified: description: Optional verified supplied by this operation. Null means unknown. type: - boolean - 'null' additionalProperties: true - required: - caption properties: caption: description: Optional caption supplied by this operation. Null means unknown. type: - string minLength: 1 - required: - created_at properties: created_at: description: Source creation time, not the API retrieval time. type: - string minLength: 1 - required: - duration_s properties: duration_s: description: Optional duration s supplied by this operation. Null means unknown. type: - number - required: - hashtags properties: hashtags: description: Optional hashtags supplied by this operation. Null means unknown. type: - array items: description: Optional record supplied by this operation. Null means unknown. type: - object - 'null' properties: {} additionalProperties: true - required: - id properties: id: description: Source identifier. Preserve the supplied type and exact value. type: - string minLength: 1 - required: - images properties: images: description: Source array was empty in the reviewed captures; item fields remain unspecified. type: - array items: {} - required: - is_ad properties: is_ad: description: Optional is ad supplied by this operation. Null means unknown. type: - boolean - required: - media_urls properties: media_urls: description: Optional media urls supplied by this operation. Null means unknown. type: - array items: description: Optional record supplied by this operation. Null means unknown. type: - string - 'null' - required: - music properties: music: description: Optional music supplied by this operation. Null means unknown. type: - object properties: author: description: Public author information supplied with this record. type: - string - 'null' cover_url: description: Optional cover url supplied by this operation. Null means unknown. type: - string - 'null' duration_s: description: Optional duration s supplied by this operation. Null means unknown. type: - number - 'null' id: description: Source identifier. Preserve the supplied type and exact value. type: - string - 'null' is_original: description: Optional is original supplied by this operation. Null means unknown. type: - boolean - 'null' play_url: description: Optional play url supplied by this operation. Null means unknown. type: - string - 'null' title: description: Source title when supplied. type: - string - 'null' additionalProperties: true - required: - stats properties: stats: description: Optional stats supplied by this operation. Null means unknown. type: - object properties: comments: description: Optional comments supplied by this operation. Null means unknown. type: - number - 'null' likes: description: Optional likes supplied by this operation. Null means unknown. type: - number - 'null' plays: description: Optional plays supplied by this operation. Null means unknown. type: - number - 'null' saves: description: Optional saves supplied by this operation. Null means unknown. type: - number - 'null' shares: description: Optional shares supplied by this operation. Null means unknown. type: - number - 'null' additionalProperties: true - required: - thumbnail_url properties: thumbnail_url: description: Optional thumbnail url supplied by this operation. Null means unknown. type: - string minLength: 1 - required: - url properties: url: description: Original source URL when supplied. type: - string minLength: 1 - required: - video_url properties: video_url: description: Optional video url supplied by this operation. Null means unknown. type: - string minLength: 1 additionalProperties: true required: - items x-contract-version: '2026-09-22' x-validation-scope: Required success payload structure; optional fields and source completeness remain separate. examples: - collection_id: example count: 0 dropped: 0 has_more: false items: - author: avatar_url: https://example.com/example followers: 0 handle: example id: example name: example private: false verified: false caption: example created_at: '2026-09-01T12:00:00Z' duration_s: 0 hashtags: - {} id: example images: [] is_ad: false media_urls: - example music: author: example cover_url: https://example.com/example duration_s: 0 id: example is_original: false play_url: https://example.com/example title: example platform: example stats: comments: 0 likes: 0 plays: 0 saves: 0 shares: 0 thumbnail_url: https://example.com/example url: https://example.com/example video_url: https://example.com/example default: description: The error envelope — the same shape for every non-2xx status. content: application/json: schema: $ref: '#/components/schemas/Error' x-credits: 1 x-production-available: true x-capacity: status: not_assessed message: Capacity is workload-dependent; configured routes do not establish sustained throughput or an availability guarantee. x-availability-scope: Structural check of the effective registered chain, production permission, adapter, configured cost and quality floor without request parameters. True is not a live-health, credential, quota, subscription-entitlement, complete-data or deployment-exposure guarantee. False means no structurally eligible candidate; null means metadata could not establish availability. Composite child capability still depends on its component routes. x-live-proven: true /v1/tiktok/comment: get: operationId: tiktok_comment tags: - tiktok summary: Find a tiktok comment description: Bounded comment lookup within a specified post or parent thread. Returns found, comment, comments_scanned, search_complete and next_params. A completed paid scan may return found=false; this does not establish deletion. Each successful fresh scanned page costs at least 5 credits (or the underlying price if higher); failed pages are free and cache hits use their normal lower charge. Costs 25 credits per successful live response. parameters: - name: url in: query required: true schema: type: string example: https://www.tiktok.com/@mrbeast/video/7654638524729216287 description: Public post or video URL. - name: comment_id in: query required: true schema: type: string example: '7654640784985211670' description: Exact target comment ID as a string. - name: parent_id in: query required: false schema: type: string description: For a reply lookup, the parent comment ID. Otherwise scans top-level comments. - name: cursor in: query required: false schema: type: string description: Opaque continuation from the previous response. Preserve query or identity. - name: max_pages in: query required: false schema: type: string example: '1' description: 'Maximum source pages: 1-5, default 1. Catalog price reserves the five-page maximum; actual successful component charges are settled after execution.' - name: dry_run in: query required: false schema: type: string enum: - '1' - '0' - 'true' - 'false' example: '1' description: 'Read a zero-credit estimate without fetching sources, running AI, or reserving credits. Cache status is a snapshot, not a guarantee at execution. Accepted values: 1, 0, true, false. Case, spaces, hyphens and underscores are interchangeable.' - name: judgments in: query required: false schema: type: string enum: - 'on' - 'off' example: 'on' description: 'Add bounded AI labels to eligible returned records (default on). off preserves the original data shape. Unclassified records remain present; labels depend on evidence, time, capacity and the existing request budget. No label surcharge. Accepted values: on, off. Case, spaces, hyphens and underscores are interchangeable.' - name: label in: query required: false schema: type: string enum: - default - none example: none description: 'Set none to disable labels; default enables the endpoint’s label set. Equivalent to judgments=off. Accepted values: default, none. Case, spaces, hyphens and underscores are interchangeable.' - name: label_evidence in: query required: false schema: type: string enum: - '1' - '0' - 'true' - 'false' example: '1' description: 'Include exact supporting sentences and zero-based sentence indexes when a label has validated evidence. No extra charge or change to decisions. Accepted values: 1, 0, true, false. Case, spaces, hyphens and underscores are interchangeable.' - name: exclude in: query required: false schema: type: string enum: - engagement_bait example: engagement_bait description: 'Optionally remove confidently labelled engagement bait. Uncertain and unclassified records stay; removed IDs and an owner-bound recall reference are returned. Accepted values: engagement_bait. Case, spaces, hyphens and underscores are interchangeable.' - name: fit in: query required: false schema: type: string enum: - goal example: goal description: 'Use goal to replace confidently irrelevant records with recall stubs. Keeps first, last, relevant and uncertain records; preserves order. Full evidence is stored for 24 hours when available. Accepted values: goal. Case, spaces, hyphens and underscores are interchangeable.' - name: goal in: query required: false schema: type: string example: Find concrete product complaints description: 'Required with fit=goal: describe the task in at most 600 characters. Supplied text is task context, never permission to act on posts.' - name: tokens in: query required: false schema: type: string example: '4000' description: Optional soft response target for fit=goal, 256–32000. Safety and evidence retention take priority, so the returned result may exceed it. - name: X-Max-Credits in: header required: false schema: type: integer minimum: 0 maximum: 9007199254740991 example: 5 description: Optional credit reservation ceiling for this individual request. Send a non-negative integer in decimal digits. Live execution checks the required reservation after resolving free cache hits or buffered continuation, before charging or calling a supplier. A higher reservation returns HTTP 422 INVALID_PARAMETERS with reason max_credits_exceeded and charges nothing. Invalid header values also return 422. Zero permits only a zero-credit reservation; omitting the header uses normal pricing. dry_run remains a free preview. This does not cap later requests, batches or scheduled runs. security: - ApiKeyHeader: [] - BearerKey: [] responses: '200': description: 'The common success envelope; `data` is endpoint-specific. Many lists use items/count/cursor; bundles use named collections and their documented continuation metadata. HTTP 200 can contain a partial bundle: inspect complete, partial and legs where supplied.' content: application/json: schema: allOf: - $ref: '#/components/schemas/Success' - type: object properties: data: $schema: https://json-schema.org/draft/2020-12/schema $id: https://www.monocrawl.com/schemas/tiktok/comment.json title: tiktok/comment data fields description: Optional data supplied by this operation. Null means unknown. type: object properties: _meta: description: Optional meta supplied by this operation. Null means unknown. type: - object - 'null' properties: billing: description: Optional billing supplied by this operation. Null means unknown. type: - object - 'null' properties: charged: description: Optional charged supplied by this operation. Null means unknown. type: - number - 'null' list_price: description: Optional list price supplied by this operation. Null means unknown. type: - number - 'null' maximum_component_credits: description: Optional maximum component credits supplied by this operation. Null means unknown. type: - number - 'null' additionalProperties: true additionalProperties: true _warnings: description: Optional warnings supplied by this operation. Null means unknown. type: - array - 'null' items: description: Optional record supplied by this operation. Null means unknown. type: - string - 'null' comment: description: Optional comment supplied by this operation. Null means unknown. type: - object - 'null' properties: author: description: Public author information supplied with this record. type: - object - 'null' properties: handle: description: Optional handle supplied by this operation. Null means unknown. type: - string - 'null' id: description: Source identifier. Preserve the supplied type and exact value. type: - string - 'null' name: description: Optional name supplied by this operation. Null means unknown. type: - string - 'null' additionalProperties: true created_at: description: Source creation time, not the API retrieval time. type: - string - 'null' id: description: Source identifier. Preserve the supplied type and exact value. type: - string - 'null' likes: description: Optional likes supplied by this operation. Null means unknown. type: - number - 'null' reply_count: description: Optional reply count supplied by this operation. Null means unknown. type: - number - 'null' text: description: Source text when supplied. type: - string - 'null' additionalProperties: true comments_scanned: description: Optional comments scanned supplied by this operation. Null means unknown. type: - number - 'null' complete: description: Optional complete supplied by this operation. Null means unknown. type: - boolean - 'null' found: description: Optional found supplied by this operation. Null means unknown. type: - boolean - 'null' legs: description: Optional legs supplied by this operation. Null means unknown. type: - array - 'null' items: description: Optional record supplied by this operation. Null means unknown. type: - object - 'null' properties: attempts: description: Optional attempts supplied by this operation. Null means unknown. type: - number - 'null' credits: description: Optional credits supplied by this operation. Null means unknown. type: - number - 'null' endpoint: description: Optional endpoint supplied by this operation. Null means unknown. type: - string - 'null' ok: description: Optional ok supplied by this operation. Null means unknown. type: - boolean - 'null' served_by: description: Optional served by supplied by this operation. Null means unknown. type: - string - 'null' status: description: Optional status supplied by this operation. Null means unknown. type: - number - 'null' additionalProperties: true pages_fetched: description: Optional pages fetched supplied by this operation. Null means unknown. type: - number - 'null' partial: description: Optional partial supplied by this operation. Null means unknown. type: - boolean - 'null' platform: description: Optional platform supplied by this operation. Null means unknown. type: - string - 'null' search_complete: description: Optional search complete supplied by this operation. Null means unknown. type: - boolean - 'null' source_metadata: description: Optional source metadata supplied by this operation. Null means unknown. type: - object - 'null' properties: count: description: Number of records in this response, not lifetime or total matches. type: - number - 'null' cursor: description: Opaque next-page token; pass it back unchanged. Null does not prove complete history. type: - string - 'null' has_more: description: Source continuation indicator; null means unknown. type: - boolean - 'null' selection: description: Optional selection supplied by this operation. Null means unknown. type: - object - 'null' properties: order: description: Optional order supplied by this operation. Null means unknown. type: - string - 'null' scope: description: Optional scope supplied by this operation. Null means unknown. type: - string - 'null' stable: description: Optional stable supplied by this operation. Null means unknown. type: - boolean - 'null' additionalProperties: true total: description: Source-reported total; null is unknown. type: - number - 'null' additionalProperties: true stop_reason: description: Optional stop reason supplied by this operation. Null means unknown. type: - string - 'null' additionalProperties: true allOf: - anyOf: - required: - comment properties: comment: description: Optional comment supplied by this operation. Null means unknown. type: - object properties: author: description: Public author information supplied with this record. type: - object - 'null' properties: handle: description: Optional handle supplied by this operation. Null means unknown. type: - string - 'null' id: description: Source identifier. Preserve the supplied type and exact value. type: - string - 'null' name: description: Optional name supplied by this operation. Null means unknown. type: - string - 'null' additionalProperties: true created_at: description: Source creation time, not the API retrieval time. type: - string - 'null' id: description: Source identifier. Preserve the supplied type and exact value. type: - string - 'null' likes: description: Optional likes supplied by this operation. Null means unknown. type: - number - 'null' reply_count: description: Optional reply count supplied by this operation. Null means unknown. type: - number - 'null' text: description: Source text when supplied. type: - string - 'null' additionalProperties: true - required: - comments_scanned properties: comments_scanned: description: Optional comments scanned supplied by this operation. Null means unknown. type: - number - required: - found properties: found: description: Optional found supplied by this operation. Null means unknown. type: - boolean - required: - legs properties: legs: description: Optional legs supplied by this operation. Null means unknown. type: - array items: description: Optional record supplied by this operation. Null means unknown. type: - object - 'null' properties: attempts: description: Optional attempts supplied by this operation. Null means unknown. type: - number - 'null' credits: description: Optional credits supplied by this operation. Null means unknown. type: - number - 'null' endpoint: description: Optional endpoint supplied by this operation. Null means unknown. type: - string - 'null' ok: description: Optional ok supplied by this operation. Null means unknown. type: - boolean - 'null' served_by: description: Optional served by supplied by this operation. Null means unknown. type: - string - 'null' status: description: Optional status supplied by this operation. Null means unknown. type: - number - 'null' additionalProperties: true - required: - pages_fetched properties: pages_fetched: description: Optional pages fetched supplied by this operation. Null means unknown. type: - number - required: - search_complete properties: search_complete: description: Optional search complete supplied by this operation. Null means unknown. type: - boolean - required: - source_metadata properties: source_metadata: description: Optional source metadata supplied by this operation. Null means unknown. type: - object properties: count: description: Number of records in this response, not lifetime or total matches. type: - number - 'null' cursor: description: Opaque next-page token; pass it back unchanged. Null does not prove complete history. type: - string - 'null' has_more: description: Source continuation indicator; null means unknown. type: - boolean - 'null' selection: description: Optional selection supplied by this operation. Null means unknown. type: - object - 'null' properties: order: description: Optional order supplied by this operation. Null means unknown. type: - string - 'null' scope: description: Optional scope supplied by this operation. Null means unknown. type: - string - 'null' stable: description: Optional stable supplied by this operation. Null means unknown. type: - boolean - 'null' additionalProperties: true total: description: Source-reported total; null is unknown. type: - number - 'null' additionalProperties: true - required: - stop_reason properties: stop_reason: description: Optional stop reason supplied by this operation. Null means unknown. type: - string minLength: 1 x-contract-version: '2026-09-22' x-validation-scope: Required success payload structure; optional fields and source completeness remain separate. examples: - _meta: billing: charged: 0 list_price: 0 maximum_component_credits: 0 _warnings: - example comment: author: handle: example id: example name: example created_at: '2026-09-01T12:00:00Z' id: example likes: 0 reply_count: 0 text: example comments_scanned: 0 complete: false found: false legs: - attempts: 0 credits: 0 endpoint: example ok: false served_by: example status: 0 pages_fetched: 0 partial: false platform: example search_complete: false source_metadata: count: 0 cursor: null has_more: false selection: order: example scope: example stable: false total: 0 stop_reason: example default: description: The error envelope — the same shape for every non-2xx status. content: application/json: schema: $ref: '#/components/schemas/Error' x-credits: 25 x-production-available: true x-capacity: status: not_assessed message: Capacity is workload-dependent; configured routes do not establish sustained throughput or an availability guarantee. x-availability-scope: Structural check of the effective registered chain, production permission, adapter, configured cost and quality floor without request parameters. True is not a live-health, credential, quota, subscription-entitlement, complete-data or deployment-exposure guarantee. False means no structurally eligible candidate; null means metadata could not establish availability. Composite child capability still depends on its component routes. x-live-proven: true /v1/tiktok/comment-replies: get: operationId: tiktok_comment_replies tags: - tiktok summary: Comment replies description: The reply thread under one TikTok comment. Paged by cursor. Costs 1 credit per successful live response. parameters: - name: comment_id in: query required: true schema: type: string example: '7623828115408274207' description: Comment id from tiktok/post-comments. - name: url in: query required: true schema: type: string example: https://www.tiktok.com/@stoolpresidente/video/7623818255903329566 description: Full TikTok video URL. - name: cursor in: query required: false schema: type: string description: Opaque cursor from the previous page. - name: dry_run in: query required: false schema: type: string enum: - '1' - '0' - 'true' - 'false' example: '1' description: 'Read a zero-credit estimate without fetching sources, running AI, or reserving credits. Cache status is a snapshot, not a guarantee at execution. Accepted values: 1, 0, true, false. Case, spaces, hyphens and underscores are interchangeable.' - name: judgments in: query required: false schema: type: string enum: - 'on' - 'off' example: 'on' description: 'Add bounded AI labels to eligible returned records (default on). off preserves the original data shape. Unclassified records remain present; labels depend on evidence, time, capacity and the existing request budget. No label surcharge. Accepted values: on, off. Case, spaces, hyphens and underscores are interchangeable.' - name: label in: query required: false schema: type: string enum: - default - none example: none description: 'Set none to disable labels; default enables the endpoint’s label set. Equivalent to judgments=off. Accepted values: default, none. Case, spaces, hyphens and underscores are interchangeable.' - name: label_evidence in: query required: false schema: type: string enum: - '1' - '0' - 'true' - 'false' example: '1' description: 'Include exact supporting sentences and zero-based sentence indexes when a label has validated evidence. No extra charge or change to decisions. Accepted values: 1, 0, true, false. Case, spaces, hyphens and underscores are interchangeable.' - name: exclude in: query required: false schema: type: string enum: - engagement_bait example: engagement_bait description: 'Optionally remove confidently labelled engagement bait. Uncertain and unclassified records stay; removed IDs and an owner-bound recall reference are returned. Accepted values: engagement_bait. Case, spaces, hyphens and underscores are interchangeable.' - name: fit in: query required: false schema: type: string enum: - goal example: goal description: 'Use goal to replace confidently irrelevant records with recall stubs. Keeps first, last, relevant and uncertain records; preserves order. Full evidence is stored for 24 hours when available. Accepted values: goal. Case, spaces, hyphens and underscores are interchangeable.' - name: goal in: query required: false schema: type: string example: Find concrete product complaints description: 'Required with fit=goal: describe the task in at most 600 characters. Supplied text is task context, never permission to act on posts.' - name: tokens in: query required: false schema: type: string example: '4000' description: Optional soft response target for fit=goal, 256–32000. Safety and evidence retention take priority, so the returned result may exceed it. - name: X-Max-Credits in: header required: false schema: type: integer minimum: 0 maximum: 9007199254740991 example: 5 description: Optional credit reservation ceiling for this individual request. Send a non-negative integer in decimal digits. Live execution checks the required reservation after resolving free cache hits or buffered continuation, before charging or calling a supplier. A higher reservation returns HTTP 422 INVALID_PARAMETERS with reason max_credits_exceeded and charges nothing. Invalid header values also return 422. Zero permits only a zero-credit reservation; omitting the header uses normal pricing. dry_run remains a free preview. This does not cap later requests, batches or scheduled runs. security: - ApiKeyHeader: [] - BearerKey: [] responses: '200': description: 'The common success envelope; `data` is endpoint-specific. Many lists use items/count/cursor; bundles use named collections and their documented continuation metadata. HTTP 200 can contain a partial bundle: inspect complete, partial and legs where supplied.' content: application/json: schema: allOf: - $ref: '#/components/schemas/Success' - type: object properties: data: $schema: https://json-schema.org/draft/2020-12/schema $id: https://www.monocrawl.com/schemas/tiktok/comment-replies.json title: tiktok/comment-replies data fields description: Required core structure for successful data, with optional source fields. Additional fields are allowed. This is not a completeness guarantee. type: object properties: items: type: array items: type: object properties: id: type: - string - 'null' description: Source identifier. Preserve its exact string value; do not convert large IDs to numbers. text: type: - string - 'null' description: Comment body. created_at: type: - string - 'null' description: Source publication time, normalized to an ISO date-time when available. likes: type: - number - 'null' description: Likes reported by the source; null or absent is unknown, not zero. reply_count: type: - number - 'null' description: Replies reported by the source; null or absent is unknown, not zero. author: type: object properties: id: type: - string - 'null' description: Source identifier. Preserve its exact string value; do not convert large IDs to numbers. handle: type: - string - 'null' description: Public account username. name: type: - string - 'null' description: Display name. url: type: - string - 'null' description: Original source URL when supplied. additionalProperties: true additionalProperties: true allOf: - anyOf: - required: - id properties: id: type: - string description: Source identifier. Preserve its exact string value; do not convert large IDs to numbers. minLength: 1 - required: - text properties: text: type: - string description: Comment body. minLength: 1 - required: - created_at properties: created_at: type: - string description: Source publication time, normalized to an ISO date-time when available. minLength: 1 - required: - likes properties: likes: type: - number description: Likes reported by the source; null or absent is unknown, not zero. - required: - reply_count properties: reply_count: type: - number description: Replies reported by the source; null or absent is unknown, not zero. - required: - author properties: author: type: object properties: id: type: - string - 'null' description: Source identifier. Preserve its exact string value; do not convert large IDs to numbers. handle: type: - string - 'null' description: Public account username. name: type: - string - 'null' description: Display name. url: type: - string - 'null' description: Original source URL when supplied. additionalProperties: true description: Records in this response page. count: type: - number - 'null' description: Returned row count when supplied; not the full source total. cursor: type: - string - 'null' description: Opaque next-page token. A missing token does not prove full history was retrieved. has_more: type: - boolean - 'null' description: Source continuation indicator; null means unknown. _warnings: type: array items: type: string description: Collection limitations or component warnings. Read before interpreting coverage. additionalProperties: true required: - items x-contract-version: '2026-09-22' x-validation-scope: Required success payload structure; optional fields and source completeness remain separate. examples: - items: - id: '7350000000000000003' text: Useful setup likes: 3 reply_count: 0 author: handle: example_reader cursor: null has_more: null default: description: The error envelope — the same shape for every non-2xx status. content: application/json: schema: $ref: '#/components/schemas/Error' x-credits: 1 x-production-available: true x-capacity: status: not_assessed message: Capacity is workload-dependent; configured routes do not establish sustained throughput or an availability guarantee. x-availability-scope: Structural check of the effective registered chain, production permission, adapter, configured cost and quality floor without request parameters. True is not a live-health, credential, quota, subscription-entitlement, complete-data or deployment-exposure guarantee. False means no structurally eligible candidate; null means metadata could not establish availability. Composite child capability still depends on its component routes. x-live-proven: true /v1/tiktok/effect-videos: get: operationId: tiktok_effect_videos tags: - tiktok summary: TikTok effect videos description: Public videos made with a TikTok effect, with engagement counts and the author on every row. Costs 1 credit per successful live response. parameters: - name: effect_id in: query required: true schema: type: string example: '321535' description: The effect id - name: limit in: query required: false schema: type: string example: '5' description: Requested rows per response, 1–1000. The source may return fewer. Remaining rows from an already purchased page use a saved cursor and cost zero to retrieve for up to one hour; further native source pages use this endpoint’s normal price. - name: cursor in: query required: false schema: type: string example: '' description: Use the returned cursor unchanged, retaining the original query, filters and limit. Saved mlo1. cursors retrieve already purchased rows at zero credits for up to one hour. A native source cursor, when supplied, starts a normally priced source page. Quote with dry_run before continuing. - name: dry_run in: query required: false schema: type: string enum: - '1' - '0' - 'true' - 'false' example: '1' description: 'Read a zero-credit estimate without fetching sources, running AI, or reserving credits. Cache status is a snapshot, not a guarantee at execution. Accepted values: 1, 0, true, false. Case, spaces, hyphens and underscores are interchangeable.' - name: judgments in: query required: false schema: type: string enum: - 'on' - 'off' example: 'on' description: 'Add bounded AI labels to eligible returned records (default on). off preserves the original data shape. Unclassified records remain present; labels depend on evidence, time, capacity and the existing request budget. No label surcharge. Accepted values: on, off. Case, spaces, hyphens and underscores are interchangeable.' - name: label in: query required: false schema: type: string enum: - default - none example: none description: 'Set none to disable labels; default enables the endpoint’s label set. Equivalent to judgments=off. Accepted values: default, none. Case, spaces, hyphens and underscores are interchangeable.' - name: label_evidence in: query required: false schema: type: string enum: - '1' - '0' - 'true' - 'false' example: '1' description: 'Include exact supporting sentences and zero-based sentence indexes when a label has validated evidence. No extra charge or change to decisions. Accepted values: 1, 0, true, false. Case, spaces, hyphens and underscores are interchangeable.' - name: exclude in: query required: false schema: type: string enum: - engagement_bait example: engagement_bait description: 'Optionally remove confidently labelled engagement bait. Uncertain and unclassified records stay; removed IDs and an owner-bound recall reference are returned. Accepted values: engagement_bait. Case, spaces, hyphens and underscores are interchangeable.' - name: fit in: query required: false schema: type: string enum: - goal example: goal description: 'Use goal to replace confidently irrelevant records with recall stubs. Keeps first, last, relevant and uncertain records; preserves order. Full evidence is stored for 24 hours when available. Accepted values: goal. Case, spaces, hyphens and underscores are interchangeable.' - name: goal in: query required: false schema: type: string example: Find concrete product complaints description: 'Required with fit=goal: describe the task in at most 600 characters. Supplied text is task context, never permission to act on posts.' - name: tokens in: query required: false schema: type: string example: '4000' description: Optional soft response target for fit=goal, 256–32000. Safety and evidence retention take priority, so the returned result may exceed it. - name: X-Max-Credits in: header required: false schema: type: integer minimum: 0 maximum: 9007199254740991 example: 5 description: Optional credit reservation ceiling for this individual request. Send a non-negative integer in decimal digits. Live execution checks the required reservation after resolving free cache hits or buffered continuation, before charging or calling a supplier. A higher reservation returns HTTP 422 INVALID_PARAMETERS with reason max_credits_exceeded and charges nothing. Invalid header values also return 422. Zero permits only a zero-credit reservation; omitting the header uses normal pricing. dry_run remains a free preview. This does not cap later requests, batches or scheduled runs. security: - ApiKeyHeader: [] - BearerKey: [] responses: '200': description: 'The common success envelope; `data` is endpoint-specific. Many lists use items/count/cursor; bundles use named collections and their documented continuation metadata. HTTP 200 can contain a partial bundle: inspect complete, partial and legs where supplied.' content: application/json: schema: allOf: - $ref: '#/components/schemas/Success' - type: object properties: data: $schema: https://json-schema.org/draft/2020-12/schema $id: https://www.monocrawl.com/schemas/tiktok/effect-videos.json title: tiktok/effect-videos data fields description: Optional data supplied by this operation. Null means unknown. type: object properties: count: description: Number of records in this response, not lifetime or total matches. type: - number - 'null' cursor: description: Opaque next-page token; pass it back unchanged. Null does not prove complete history. type: - string - 'null' dropped: description: Optional dropped supplied by this operation. Null means unknown. type: - number - 'null' effect_id: description: Optional effect id supplied by this operation. Null means unknown. type: - string - 'null' has_more: description: Source continuation indicator; null means unknown. type: - boolean - 'null' items: description: Returned records. Source coverage and completeness vary. type: - array items: description: Optional record supplied by this operation. Null means unknown. type: object properties: author: description: Public author information supplied with this record. type: - object - 'null' properties: avatar_url: description: Optional avatar url supplied by this operation. Null means unknown. type: - string - 'null' followers: description: Optional followers supplied by this operation. Null means unknown. type: - number - 'null' following: description: Optional following supplied by this operation. Null means unknown. type: - number - 'null' handle: description: Optional handle supplied by this operation. Null means unknown. type: - string - 'null' id: description: Source identifier. Preserve the supplied type and exact value. type: - string - 'null' language: description: Optional language supplied by this operation. Null means unknown. type: - string - 'null' likes_count: description: Optional likes count supplied by this operation. Null means unknown. type: - number - 'null' name: description: Optional name supplied by this operation. Null means unknown. type: - string - 'null' region: description: Optional region supplied by this operation. Null means unknown. type: - string - 'null' videos_count: description: Optional videos count supplied by this operation. Null means unknown. type: - number - 'null' additionalProperties: true caption: description: Optional caption supplied by this operation. Null means unknown. type: - string - 'null' created_at: description: Source creation time, not the API retrieval time. type: - string - 'null' duration_s: description: Optional duration s supplied by this operation. Null means unknown. type: - number - 'null' id: description: Source identifier. Preserve the supplied type and exact value. type: - string - 'null' images: description: Source array was empty in the reviewed captures; item fields remain unspecified. type: - array - 'null' items: {} media_urls: description: Optional media urls supplied by this operation. Null means unknown. type: - array - 'null' items: description: Optional record supplied by this operation. Null means unknown. type: - string - 'null' music: description: Optional music supplied by this operation. Null means unknown. type: - object - 'null' properties: author: description: Public author information supplied with this record. type: - string - 'null' id: description: Source identifier. Preserve the supplied type and exact value. type: - string - 'null' title: description: Source title when supplied. type: - string - 'null' additionalProperties: true platform: description: Optional platform supplied by this operation. Null means unknown. type: - string - 'null' stats: description: Optional stats supplied by this operation. Null means unknown. type: - object - 'null' properties: comments: description: Optional comments supplied by this operation. Null means unknown. type: - number - 'null' likes: description: Optional likes supplied by this operation. Null means unknown. type: - number - 'null' plays: description: Optional plays supplied by this operation. Null means unknown. type: - number - 'null' saves: description: Optional saves supplied by this operation. Null means unknown. type: - number - 'null' shares: description: Optional shares supplied by this operation. Null means unknown. type: - number - 'null' additionalProperties: true thumbnail_url: description: Optional thumbnail url supplied by this operation. Null means unknown. type: - string - 'null' url: description: Original source URL when supplied. type: - string - 'null' video_url: description: Optional video url supplied by this operation. Null means unknown. type: - string - 'null' additionalProperties: true allOf: - anyOf: - required: - author properties: author: description: Public author information supplied with this record. type: - object properties: avatar_url: description: Optional avatar url supplied by this operation. Null means unknown. type: - string - 'null' followers: description: Optional followers supplied by this operation. Null means unknown. type: - number - 'null' following: description: Optional following supplied by this operation. Null means unknown. type: - number - 'null' handle: description: Optional handle supplied by this operation. Null means unknown. type: - string - 'null' id: description: Source identifier. Preserve the supplied type and exact value. type: - string - 'null' language: description: Optional language supplied by this operation. Null means unknown. type: - string - 'null' likes_count: description: Optional likes count supplied by this operation. Null means unknown. type: - number - 'null' name: description: Optional name supplied by this operation. Null means unknown. type: - string - 'null' region: description: Optional region supplied by this operation. Null means unknown. type: - string - 'null' videos_count: description: Optional videos count supplied by this operation. Null means unknown. type: - number - 'null' additionalProperties: true - required: - caption properties: caption: description: Optional caption supplied by this operation. Null means unknown. type: - string minLength: 1 - required: - created_at properties: created_at: description: Source creation time, not the API retrieval time. type: - string minLength: 1 - required: - duration_s properties: duration_s: description: Optional duration s supplied by this operation. Null means unknown. type: - number - required: - id properties: id: description: Source identifier. Preserve the supplied type and exact value. type: - string minLength: 1 - required: - images properties: images: description: Source array was empty in the reviewed captures; item fields remain unspecified. type: - array items: {} - required: - media_urls properties: media_urls: description: Optional media urls supplied by this operation. Null means unknown. type: - array items: description: Optional record supplied by this operation. Null means unknown. type: - string - 'null' - required: - music properties: music: description: Optional music supplied by this operation. Null means unknown. type: - object properties: author: description: Public author information supplied with this record. type: - string - 'null' id: description: Source identifier. Preserve the supplied type and exact value. type: - string - 'null' title: description: Source title when supplied. type: - string - 'null' additionalProperties: true - required: - stats properties: stats: description: Optional stats supplied by this operation. Null means unknown. type: - object properties: comments: description: Optional comments supplied by this operation. Null means unknown. type: - number - 'null' likes: description: Optional likes supplied by this operation. Null means unknown. type: - number - 'null' plays: description: Optional plays supplied by this operation. Null means unknown. type: - number - 'null' saves: description: Optional saves supplied by this operation. Null means unknown. type: - number - 'null' shares: description: Optional shares supplied by this operation. Null means unknown. type: - number - 'null' additionalProperties: true - required: - thumbnail_url properties: thumbnail_url: description: Optional thumbnail url supplied by this operation. Null means unknown. type: - string minLength: 1 - required: - url properties: url: description: Original source URL when supplied. type: - string minLength: 1 - required: - video_url properties: video_url: description: Optional video url supplied by this operation. Null means unknown. type: - string minLength: 1 additionalProperties: true required: - items x-contract-version: '2026-09-22' x-validation-scope: Required success payload structure; optional fields and source completeness remain separate. examples: - count: 0 cursor: null dropped: 0 effect_id: example has_more: false items: - author: avatar_url: https://example.com/example followers: 0 following: 0 handle: example id: example language: example likes_count: 0 name: example region: example videos_count: 0 caption: example created_at: '2026-09-01T12:00:00Z' duration_s: 0 id: example images: [] media_urls: - example music: author: example id: example title: example platform: example stats: comments: 0 likes: 0 plays: 0 saves: 0 shares: 0 thumbnail_url: https://example.com/example url: https://example.com/example video_url: https://example.com/example default: description: The error envelope — the same shape for every non-2xx status. content: application/json: schema: $ref: '#/components/schemas/Error' x-credits: 1 x-production-available: true x-capacity: status: not_assessed message: Capacity is workload-dependent; configured routes do not establish sustained throughput or an availability guarantee. x-availability-scope: Structural check of the effective registered chain, production permission, adapter, configured cost and quality floor without request parameters. True is not a live-health, credential, quota, subscription-entitlement, complete-data or deployment-exposure guarantee. False means no structurally eligible candidate; null means metadata could not establish availability. Composite child capability still depends on its component routes. x-live-proven: true /v1/tiktok/effects: get: operationId: tiktok_effects tags: - tiktok summary: TikTok effects description: 'TikTok effects (the camera filters creators apply) by id: name, designer, videos made with it, views and icon. Costs 1 credit per successful live response.' parameters: - name: ids in: query required: true schema: type: string example: '321535' description: One or more effect ids, comma separated, up to ten - name: dry_run in: query required: false schema: type: string enum: - '1' - '0' - 'true' - 'false' example: '1' description: 'Read a zero-credit estimate without fetching sources, running AI, or reserving credits. Cache status is a snapshot, not a guarantee at execution. Accepted values: 1, 0, true, false. Case, spaces, hyphens and underscores are interchangeable.' - name: X-Max-Credits in: header required: false schema: type: integer minimum: 0 maximum: 9007199254740991 example: 5 description: Optional credit reservation ceiling for this individual request. Send a non-negative integer in decimal digits. Live execution checks the required reservation after resolving free cache hits or buffered continuation, before charging or calling a supplier. A higher reservation returns HTTP 422 INVALID_PARAMETERS with reason max_credits_exceeded and charges nothing. Invalid header values also return 422. Zero permits only a zero-credit reservation; omitting the header uses normal pricing. dry_run remains a free preview. This does not cap later requests, batches or scheduled runs. security: - ApiKeyHeader: [] - BearerKey: [] responses: '200': description: 'The common success envelope; `data` is endpoint-specific. Many lists use items/count/cursor; bundles use named collections and their documented continuation metadata. HTTP 200 can contain a partial bundle: inspect complete, partial and legs where supplied.' content: application/json: schema: allOf: - $ref: '#/components/schemas/Success' - type: object properties: data: $schema: https://json-schema.org/draft/2020-12/schema $id: https://www.monocrawl.com/schemas/tiktok/effects.json title: tiktok/effects data fields description: Optional data supplied by this operation. Null means unknown. type: object properties: count: description: Number of records in this response, not lifetime or total matches. type: - number - 'null' has_more: description: Source continuation indicator; null means unknown. type: - boolean - 'null' items: description: Returned records. Source coverage and completeness vary. type: - array items: description: Optional record supplied by this operation. Null means unknown. type: object properties: designer: description: Optional designer supplied by this operation. Null means unknown. type: - string - 'null' icon_url: description: Optional icon url supplied by this operation. Null means unknown. type: - string - 'null' id: description: Source identifier. Preserve the supplied type and exact value. type: - string - 'null' name: description: Optional name supplied by this operation. Null means unknown. type: - string - 'null' platform: description: Optional platform supplied by this operation. Null means unknown. type: - string - 'null' url: description: Original source URL when supplied. type: - string - 'null' videos: description: Optional videos supplied by this operation. Null means unknown. type: - number - 'null' views: description: Optional views supplied by this operation. Null means unknown. type: - number - 'null' additionalProperties: true allOf: - anyOf: - required: - designer properties: designer: description: Optional designer supplied by this operation. Null means unknown. type: - string minLength: 1 - required: - icon_url properties: icon_url: description: Optional icon url supplied by this operation. Null means unknown. type: - string minLength: 1 - required: - id properties: id: description: Source identifier. Preserve the supplied type and exact value. type: - string minLength: 1 - required: - name properties: name: description: Optional name supplied by this operation. Null means unknown. type: - string minLength: 1 - required: - url properties: url: description: Original source URL when supplied. type: - string minLength: 1 - required: - videos properties: videos: description: Optional videos supplied by this operation. Null means unknown. type: - number - required: - views properties: views: description: Optional views supplied by this operation. Null means unknown. type: - number requested: description: Optional requested supplied by this operation. Null means unknown. type: - number - 'null' additionalProperties: true required: - items x-contract-version: '2026-09-22' x-validation-scope: Required success payload structure; optional fields and source completeness remain separate. examples: - count: 0 has_more: false items: - designer: example icon_url: https://example.com/example id: example name: example platform: example url: https://example.com/example videos: 0 views: 0 requested: 0 default: description: The error envelope — the same shape for every non-2xx status. content: application/json: schema: $ref: '#/components/schemas/Error' x-credits: 1 x-production-available: true x-capacity: status: not_assessed message: Capacity is workload-dependent; configured routes do not establish sustained throughput or an availability guarantee. x-availability-scope: Structural check of the effective registered chain, production permission, adapter, configured cost and quality floor without request parameters. True is not a live-health, credential, quota, subscription-entitlement, complete-data or deployment-exposure guarantee. False means no structurally eligible candidate; null means metadata could not establish availability. Composite child capability still depends on its component routes. x-live-proven: true /v1/tiktok/hashtag: get: operationId: tiktok_hashtag tags: - tiktok summary: TikTok hashtag metadata description: Public hashtag description and counts resolved by exact name on the first search page. A missing exact match does not establish that the tag does not exist. ID-only lookup is not supported. Costs 1 credit per successful live response. parameters: - name: hashtag in: query required: true schema: type: string example: fitness description: 'Exact hashtag name, optionally prefixed with #.' - name: dry_run in: query required: false schema: type: string enum: - '1' - '0' - 'true' - 'false' example: '1' description: 'Read a zero-credit estimate without fetching sources, running AI, or reserving credits. Cache status is a snapshot, not a guarantee at execution. Accepted values: 1, 0, true, false. Case, spaces, hyphens and underscores are interchangeable.' - name: X-Max-Credits in: header required: false schema: type: integer minimum: 0 maximum: 9007199254740991 example: 5 description: Optional credit reservation ceiling for this individual request. Send a non-negative integer in decimal digits. Live execution checks the required reservation after resolving free cache hits or buffered continuation, before charging or calling a supplier. A higher reservation returns HTTP 422 INVALID_PARAMETERS with reason max_credits_exceeded and charges nothing. Invalid header values also return 422. Zero permits only a zero-credit reservation; omitting the header uses normal pricing. dry_run remains a free preview. This does not cap later requests, batches or scheduled runs. security: - ApiKeyHeader: [] - BearerKey: [] responses: '200': description: 'The common success envelope; `data` is endpoint-specific. Many lists use items/count/cursor; bundles use named collections and their documented continuation metadata. HTTP 200 can contain a partial bundle: inspect complete, partial and legs where supplied.' content: application/json: schema: allOf: - $ref: '#/components/schemas/Success' - type: object properties: data: $schema: https://json-schema.org/draft/2020-12/schema $id: https://www.monocrawl.com/schemas/tiktok/hashtag.json title: tiktok/hashtag data fields description: Optional data supplied by this operation. Null means unknown. type: object properties: _warnings: description: Optional warnings supplied by this operation. Null means unknown. type: - array - 'null' items: description: Optional record supplied by this operation. Null means unknown. type: - string - 'null' description: description: Source description; null or absent means not supplied. type: - string - 'null' id: description: Source identifier. Preserve the supplied type and exact value. type: - string - 'null' lookup_scope: description: Optional lookup scope supplied by this operation. Null means unknown. type: - string - 'null' name: description: Optional name supplied by this operation. Null means unknown. type: - string - 'null' platform: description: Optional platform supplied by this operation. Null means unknown. type: - string - 'null' url: description: Original source URL when supplied. type: - string - 'null' video_count: description: Optional video count supplied by this operation. Null means unknown. type: - number - 'null' view_count: description: Optional view count supplied by this operation. Null means unknown. type: - number - 'null' additionalProperties: true allOf: - anyOf: - required: - description properties: description: description: Source description; null or absent means not supplied. type: - string minLength: 1 - required: - id properties: id: description: Source identifier. Preserve the supplied type and exact value. type: - string minLength: 1 - required: - lookup_scope properties: lookup_scope: description: Optional lookup scope supplied by this operation. Null means unknown. type: - string minLength: 1 - required: - name properties: name: description: Optional name supplied by this operation. Null means unknown. type: - string minLength: 1 - required: - url properties: url: description: Original source URL when supplied. type: - string minLength: 1 - required: - video_count properties: video_count: description: Optional video count supplied by this operation. Null means unknown. type: - number - required: - view_count properties: view_count: description: Optional view count supplied by this operation. Null means unknown. type: - number x-contract-version: '2026-09-22' x-validation-scope: Required success payload structure; optional fields and source completeness remain separate. examples: - _warnings: - example description: example id: example lookup_scope: example name: example platform: example url: https://example.com/example video_count: 0 view_count: 0 default: description: The error envelope — the same shape for every non-2xx status. content: application/json: schema: $ref: '#/components/schemas/Error' x-credits: 1 x-production-available: true x-capacity: status: not_assessed message: Capacity is workload-dependent; configured routes do not establish sustained throughput or an availability guarantee. x-availability-scope: Structural check of the effective registered chain, production permission, adapter, configured cost and quality floor without request parameters. True is not a live-health, credential, quota, subscription-entitlement, complete-data or deployment-exposure guarantee. False means no structurally eligible candidate; null means metadata could not establish availability. Composite child capability still depends on its component routes. x-live-proven: true /v1/tiktok/hashtags-popular: get: operationId: tiktok_hashtags_popular tags: - tiktok summary: Popular TikTok hashtags description: Anonymous public top-three board by country, window and optional industry. Ranked tags, source posts/views and relative popularity curves. Not the full ranking or live activity; no pagination. Costs 1 credit per successful live response. parameters: - name: country in: query required: false schema: type: string enum: - US - FR - DE - IT - ES - GB - AR - AU - BR - CA - CO - EG - ID - IL - JP - KR - MY - MX - PH - SA - SG - ZA - TW - TH - TR - AE - VN x-value-aliases: uk: GB example: US description: 'Country: US, FR, DE, IT, ES, GB, AR, AU, BR, CA, CO, EG, ID, IL, JP, KR, MY, MX, PH, SA, SG, ZA, TW, TH, TR, AE or VN. Accepted values: US, FR, DE, IT, ES, GB, AR, AU, BR, CA, CO, EG, ID, IL, JP, KR, MY, MX, PH, SA, SG, ZA, TW, TH, TR, AE, VN. Case, spaces, hyphens and underscores are interchangeable.' - name: period in: query required: false schema: type: string enum: - '7' - '30' - '90' example: '7' description: '7, 30 or 90 days; default 7. Accepted values: 7, 30, 90. Case, spaces, hyphens and underscores are interchangeable.' - name: industry in: query required: false schema: type: string example: '14000000000' description: 'Optional Creative Center industry ID: 10000000000 education; 11000000000 vehicles; 12000000000 baby/kids; 14000000000 beauty; 15000000000 tech; 17000000000 travel; 18000000000 household; 19000000000 pets; 21000000000 home improvement; 22000000000 apparel; 23000000000 news/entertainment; 25000000000 games; 27000000000 food; 28000000000 sports; 29000000000 health.' - name: dry_run in: query required: false schema: type: string enum: - '1' - '0' - 'true' - 'false' example: '1' description: 'Read a zero-credit estimate without fetching sources, running AI, or reserving credits. Cache status is a snapshot, not a guarantee at execution. Accepted values: 1, 0, true, false. Case, spaces, hyphens and underscores are interchangeable.' - name: countryCode in: query required: false schema: type: string example: US description: Compatibility alias for country. The canonical parameter takes precedence if both are supplied. - name: X-Max-Credits in: header required: false schema: type: integer minimum: 0 maximum: 9007199254740991 example: 5 description: Optional credit reservation ceiling for this individual request. Send a non-negative integer in decimal digits. Live execution checks the required reservation after resolving free cache hits or buffered continuation, before charging or calling a supplier. A higher reservation returns HTTP 422 INVALID_PARAMETERS with reason max_credits_exceeded and charges nothing. Invalid header values also return 422. Zero permits only a zero-credit reservation; omitting the header uses normal pricing. dry_run remains a free preview. This does not cap later requests, batches or scheduled runs. security: - ApiKeyHeader: [] - BearerKey: [] responses: '200': description: 'The common success envelope; `data` is endpoint-specific. Many lists use items/count/cursor; bundles use named collections and their documented continuation metadata. HTTP 200 can contain a partial bundle: inspect complete, partial and legs where supplied.' content: application/json: schema: allOf: - $ref: '#/components/schemas/Success' - type: object properties: data: $schema: https://json-schema.org/draft/2020-12/schema $id: https://www.monocrawl.com/schemas/tiktok/hashtags-popular.json title: tiktok/hashtags-popular data fields description: Optional data supplied by this operation. Null means unknown. type: object properties: _warnings: description: Optional warnings supplied by this operation. Null means unknown. type: - array - 'null' items: description: Optional record supplied by this operation. Null means unknown. type: - string - 'null' count: description: Number of records in this response, not lifetime or total matches. type: - number - 'null' country: description: Optional country supplied by this operation. Null means unknown. type: - string - 'null' coverage: description: Optional coverage supplied by this operation. Null means unknown. type: - string - 'null' has_more: description: Source continuation indicator; null means unknown. type: - boolean - 'null' items: description: Returned records. Source coverage and completeness vary. type: - array items: description: Optional record supplied by this operation. Null means unknown. type: object properties: id: description: Source identifier. Preserve the supplied type and exact value. type: - string - 'null' industry_ids: description: Optional industry ids supplied by this operation. Null means unknown. type: - array - 'null' items: description: Optional record supplied by this operation. Null means unknown. type: - string - 'null' name: description: Optional name supplied by this operation. Null means unknown. type: - string - 'null' popularity_curve: description: Optional popularity curve supplied by this operation. Null means unknown. type: - array - 'null' items: description: Optional record supplied by this operation. Null means unknown. type: - object - 'null' properties: {} additionalProperties: true posts: description: Optional posts supplied by this operation. Null means unknown. type: - number - 'null' rank: description: Optional rank supplied by this operation. Null means unknown. type: - number - 'null' top_creators: description: Optional top creators supplied by this operation. Null means unknown. type: - array - 'null' items: description: Optional record supplied by this operation. Null means unknown. type: - object - 'null' properties: {} additionalProperties: true views: description: Optional views supplied by this operation. Null means unknown. type: - number - 'null' additionalProperties: true allOf: - anyOf: - required: - id properties: id: description: Source identifier. Preserve the supplied type and exact value. type: - string minLength: 1 - required: - industry_ids properties: industry_ids: description: Optional industry ids supplied by this operation. Null means unknown. type: - array items: description: Optional record supplied by this operation. Null means unknown. type: - string - 'null' - required: - name properties: name: description: Optional name supplied by this operation. Null means unknown. type: - string minLength: 1 - required: - popularity_curve properties: popularity_curve: description: Optional popularity curve supplied by this operation. Null means unknown. type: - array items: description: Optional record supplied by this operation. Null means unknown. type: - object - 'null' properties: {} additionalProperties: true - required: - posts properties: posts: description: Optional posts supplied by this operation. Null means unknown. type: - number - required: - rank properties: rank: description: Optional rank supplied by this operation. Null means unknown. type: - number - required: - top_creators properties: top_creators: description: Optional top creators supplied by this operation. Null means unknown. type: - array items: description: Optional record supplied by this operation. Null means unknown. type: - object - 'null' properties: {} additionalProperties: true - required: - views properties: views: description: Optional views supplied by this operation. Null means unknown. type: - number period: description: Optional period supplied by this operation. Null means unknown. type: - number - 'null' platform: description: Optional platform supplied by this operation. Null means unknown. type: - string - 'null' retrieved_at: description: Optional retrieved at supplied by this operation. Null means unknown. type: - string - 'null' additionalProperties: true required: - items x-contract-version: '2026-09-22' x-validation-scope: Required success payload structure; optional fields and source completeness remain separate. examples: - _warnings: - example count: 0 country: example coverage: example has_more: false items: - id: example industry_ids: - example name: example popularity_curve: - {} posts: 0 rank: 0 top_creators: - {} views: 0 period: 0 platform: example retrieved_at: '2026-09-01T12:00:00Z' default: description: The error envelope — the same shape for every non-2xx status. content: application/json: schema: $ref: '#/components/schemas/Error' x-credits: 1 x-production-available: true x-capacity: status: not_assessed message: Capacity is workload-dependent; configured routes do not establish sustained throughput or an availability guarantee. x-availability-scope: Structural check of the effective registered chain, production permission, adapter, configured cost and quality floor without request parameters. True is not a live-health, credential, quota, subscription-entitlement, complete-data or deployment-exposure guarantee. False means no structurally eligible candidate; null means metadata could not establish availability. Composite child capability still depends on its component routes. x-live-proven: true /v1/tiktok/location: get: operationId: tiktok_location tags: - tiktok summary: TikTok place description: 'One place: name, address, city, country, category and coordinates. Costs 1 credit per successful live response.' parameters: - name: id in: query required: true schema: type: string example: '22535865202704586' description: Place id from a video's location tag or place URL - name: dry_run in: query required: false schema: type: string enum: - '1' - '0' - 'true' - 'false' example: '1' description: 'Read a zero-credit estimate without fetching sources, running AI, or reserving credits. Cache status is a snapshot, not a guarantee at execution. Accepted values: 1, 0, true, false. Case, spaces, hyphens and underscores are interchangeable.' - name: X-Max-Credits in: header required: false schema: type: integer minimum: 0 maximum: 9007199254740991 example: 5 description: Optional credit reservation ceiling for this individual request. Send a non-negative integer in decimal digits. Live execution checks the required reservation after resolving free cache hits or buffered continuation, before charging or calling a supplier. A higher reservation returns HTTP 422 INVALID_PARAMETERS with reason max_credits_exceeded and charges nothing. Invalid header values also return 422. Zero permits only a zero-credit reservation; omitting the header uses normal pricing. dry_run remains a free preview. This does not cap later requests, batches or scheduled runs. security: - ApiKeyHeader: [] - BearerKey: [] responses: '200': description: 'The common success envelope; `data` is endpoint-specific. Many lists use items/count/cursor; bundles use named collections and their documented continuation metadata. HTTP 200 can contain a partial bundle: inspect complete, partial and legs where supplied.' content: application/json: schema: allOf: - $ref: '#/components/schemas/Success' - type: object properties: data: $schema: https://json-schema.org/draft/2020-12/schema $id: https://www.monocrawl.com/schemas/tiktok/location.json title: tiktok/location data fields description: Required core structure for successful data, with optional source fields. Additional fields are allowed. This is not a completeness guarantee. type: object properties: id: type: - string - 'null' description: Exact source identifier; preserve it as a string. name: type: - string - 'null' description: name title: type: - string - 'null' description: title address: type: - string - 'null' description: address city: type: - string - 'null' description: city country: type: - string - 'null' description: country url: type: - string - 'null' description: url latitude: type: - number - 'null' description: latitude; null is unknown. longitude: type: - number - 'null' description: longitude; null is unknown. video_count: type: - number - 'null' description: video count; null is unknown. additionalProperties: true allOf: - anyOf: - required: - id properties: id: type: - string description: Exact source identifier; preserve it as a string. minLength: 1 - required: - name properties: name: type: - string description: name minLength: 1 - required: - title properties: title: type: - string description: title minLength: 1 - required: - address properties: address: type: - string description: address minLength: 1 - required: - city properties: city: type: - string description: city minLength: 1 - required: - country properties: country: type: - string description: country minLength: 1 - required: - url properties: url: type: - string description: url minLength: 1 - required: - latitude properties: latitude: type: - number description: latitude; null is unknown. - required: - longitude properties: longitude: type: - number description: longitude; null is unknown. - required: - video_count properties: video_count: type: - number description: video count; null is unknown. x-contract-version: '2026-09-22' x-validation-scope: Required success payload structure; optional fields and source completeness remain separate. examples: - id: '123' name: Example location default: description: The error envelope — the same shape for every non-2xx status. content: application/json: schema: $ref: '#/components/schemas/Error' x-credits: 1 x-production-available: true x-capacity: status: not_assessed message: Capacity is workload-dependent; configured routes do not establish sustained throughput or an availability guarantee. x-availability-scope: Structural check of the effective registered chain, production permission, adapter, configured cost and quality floor without request parameters. True is not a live-health, credential, quota, subscription-entitlement, complete-data or deployment-exposure guarantee. False means no structurally eligible candidate; null means metadata could not establish availability. Composite child capability still depends on its component routes. x-live-proven: true /v1/tiktok/location-videos: get: operationId: tiktok_location_videos tags: - tiktok summary: TikTok place videos description: Videos tagged at a place, with captions, counts, authors and sounds; paged by cursor. Costs 1 credit per successful live response. parameters: - name: id in: query required: true schema: type: string example: '22535865202704586' description: Place id from a video's location tag or place URL - name: cursor in: query required: false schema: type: string example: '' description: Cursor from the previous page - name: limit in: query required: false schema: type: string example: '30' description: Videos per page, at most 30 - name: dry_run in: query required: false schema: type: string enum: - '1' - '0' - 'true' - 'false' example: '1' description: 'Read a zero-credit estimate without fetching sources, running AI, or reserving credits. Cache status is a snapshot, not a guarantee at execution. Accepted values: 1, 0, true, false. Case, spaces, hyphens and underscores are interchangeable.' - name: judgments in: query required: false schema: type: string enum: - 'on' - 'off' example: 'on' description: 'Add bounded AI labels to eligible returned records (default on). off preserves the original data shape. Unclassified records remain present; labels depend on evidence, time, capacity and the existing request budget. No label surcharge. Accepted values: on, off. Case, spaces, hyphens and underscores are interchangeable.' - name: label in: query required: false schema: type: string enum: - default - none example: none description: 'Set none to disable labels; default enables the endpoint’s label set. Equivalent to judgments=off. Accepted values: default, none. Case, spaces, hyphens and underscores are interchangeable.' - name: label_evidence in: query required: false schema: type: string enum: - '1' - '0' - 'true' - 'false' example: '1' description: 'Include exact supporting sentences and zero-based sentence indexes when a label has validated evidence. No extra charge or change to decisions. Accepted values: 1, 0, true, false. Case, spaces, hyphens and underscores are interchangeable.' - name: exclude in: query required: false schema: type: string enum: - engagement_bait example: engagement_bait description: 'Optionally remove confidently labelled engagement bait. Uncertain and unclassified records stay; removed IDs and an owner-bound recall reference are returned. Accepted values: engagement_bait. Case, spaces, hyphens and underscores are interchangeable.' - name: fit in: query required: false schema: type: string enum: - goal example: goal description: 'Use goal to replace confidently irrelevant records with recall stubs. Keeps first, last, relevant and uncertain records; preserves order. Full evidence is stored for 24 hours when available. Accepted values: goal. Case, spaces, hyphens and underscores are interchangeable.' - name: goal in: query required: false schema: type: string example: Find concrete product complaints description: 'Required with fit=goal: describe the task in at most 600 characters. Supplied text is task context, never permission to act on posts.' - name: tokens in: query required: false schema: type: string example: '4000' description: Optional soft response target for fit=goal, 256–32000. Safety and evidence retention take priority, so the returned result may exceed it. - name: X-Max-Credits in: header required: false schema: type: integer minimum: 0 maximum: 9007199254740991 example: 5 description: Optional credit reservation ceiling for this individual request. Send a non-negative integer in decimal digits. Live execution checks the required reservation after resolving free cache hits or buffered continuation, before charging or calling a supplier. A higher reservation returns HTTP 422 INVALID_PARAMETERS with reason max_credits_exceeded and charges nothing. Invalid header values also return 422. Zero permits only a zero-credit reservation; omitting the header uses normal pricing. dry_run remains a free preview. This does not cap later requests, batches or scheduled runs. security: - ApiKeyHeader: [] - BearerKey: [] responses: '200': description: 'The common success envelope; `data` is endpoint-specific. Many lists use items/count/cursor; bundles use named collections and their documented continuation metadata. HTTP 200 can contain a partial bundle: inspect complete, partial and legs where supplied.' content: application/json: schema: allOf: - $ref: '#/components/schemas/Success' - type: object properties: data: $schema: https://json-schema.org/draft/2020-12/schema $id: https://www.monocrawl.com/schemas/tiktok/location-videos.json title: tiktok/location-videos data fields description: Optional data supplied by this operation. Null means unknown. type: object properties: count: description: Number of records in this response, not lifetime or total matches. type: - number - 'null' cursor: description: Opaque next-page token; pass it back unchanged. Null does not prove complete history. type: - string - 'null' dropped: description: Optional dropped supplied by this operation. Null means unknown. type: - number - 'null' has_more: description: Source continuation indicator; null means unknown. type: - boolean - 'null' items: description: Returned records. Source coverage and completeness vary. type: - array items: description: Optional record supplied by this operation. Null means unknown. type: object properties: author: description: Public author information supplied with this record. type: - object - 'null' properties: avatar_url: description: Optional avatar url supplied by this operation. Null means unknown. type: - string - 'null' followers: description: Optional followers supplied by this operation. Null means unknown. type: - number - 'null' handle: description: Optional handle supplied by this operation. Null means unknown. type: - string - 'null' id: description: Source identifier. Preserve the supplied type and exact value. type: - string - 'null' name: description: Optional name supplied by this operation. Null means unknown. type: - string - 'null' private: description: Optional private supplied by this operation. Null means unknown. type: - boolean - 'null' verified: description: Optional verified supplied by this operation. Null means unknown. type: - boolean - 'null' additionalProperties: true caption: description: Optional caption supplied by this operation. Null means unknown. type: - string - 'null' created_at: description: Source creation time, not the API retrieval time. type: - string - 'null' duration_s: description: Optional duration s supplied by this operation. Null means unknown. type: - number - 'null' hashtags: description: Optional hashtags supplied by this operation. Null means unknown. type: - array - 'null' items: description: Optional record supplied by this operation. Null means unknown. type: - object - 'null' properties: {} additionalProperties: true id: description: Source identifier. Preserve the supplied type and exact value. type: - string - 'null' images: description: Source array was empty in the reviewed captures; item fields remain unspecified. type: - array - 'null' items: {} is_ad: description: Optional is ad supplied by this operation. Null means unknown. type: - boolean - 'null' media_urls: description: Optional media urls supplied by this operation. Null means unknown. type: - array - 'null' items: description: Optional record supplied by this operation. Null means unknown. type: - string - 'null' music: description: Optional music supplied by this operation. Null means unknown. type: - object - 'null' properties: album: description: Optional album supplied by this operation. Null means unknown. type: - string - 'null' author: description: Public author information supplied with this record. type: - string - 'null' cover_url: description: Optional cover url supplied by this operation. Null means unknown. type: - string - 'null' duration_s: description: Optional duration s supplied by this operation. Null means unknown. type: - number - 'null' id: description: Source identifier. Preserve the supplied type and exact value. type: - string - 'null' is_original: description: Optional is original supplied by this operation. Null means unknown. type: - boolean - 'null' play_url: description: Optional play url supplied by this operation. Null means unknown. type: - string - 'null' title: description: Source title when supplied. type: - string - 'null' additionalProperties: true platform: description: Optional platform supplied by this operation. Null means unknown. type: - string - 'null' stats: description: Optional stats supplied by this operation. Null means unknown. type: - object - 'null' properties: comments: description: Optional comments supplied by this operation. Null means unknown. type: - number - 'null' likes: description: Optional likes supplied by this operation. Null means unknown. type: - number - 'null' plays: description: Optional plays supplied by this operation. Null means unknown. type: - number - 'null' saves: description: Optional saves supplied by this operation. Null means unknown. type: - number - 'null' shares: description: Optional shares supplied by this operation. Null means unknown. type: - number - 'null' additionalProperties: true thumbnail_url: description: Optional thumbnail url supplied by this operation. Null means unknown. type: - string - 'null' url: description: Original source URL when supplied. type: - string - 'null' video_url: description: Optional video url supplied by this operation. Null means unknown. type: - string - 'null' additionalProperties: true allOf: - anyOf: - required: - author properties: author: description: Public author information supplied with this record. type: - object properties: avatar_url: description: Optional avatar url supplied by this operation. Null means unknown. type: - string - 'null' followers: description: Optional followers supplied by this operation. Null means unknown. type: - number - 'null' handle: description: Optional handle supplied by this operation. Null means unknown. type: - string - 'null' id: description: Source identifier. Preserve the supplied type and exact value. type: - string - 'null' name: description: Optional name supplied by this operation. Null means unknown. type: - string - 'null' private: description: Optional private supplied by this operation. Null means unknown. type: - boolean - 'null' verified: description: Optional verified supplied by this operation. Null means unknown. type: - boolean - 'null' additionalProperties: true - required: - caption properties: caption: description: Optional caption supplied by this operation. Null means unknown. type: - string minLength: 1 - required: - created_at properties: created_at: description: Source creation time, not the API retrieval time. type: - string minLength: 1 - required: - duration_s properties: duration_s: description: Optional duration s supplied by this operation. Null means unknown. type: - number - required: - hashtags properties: hashtags: description: Optional hashtags supplied by this operation. Null means unknown. type: - array items: description: Optional record supplied by this operation. Null means unknown. type: - object - 'null' properties: {} additionalProperties: true - required: - id properties: id: description: Source identifier. Preserve the supplied type and exact value. type: - string minLength: 1 - required: - images properties: images: description: Source array was empty in the reviewed captures; item fields remain unspecified. type: - array items: {} - required: - is_ad properties: is_ad: description: Optional is ad supplied by this operation. Null means unknown. type: - boolean - required: - media_urls properties: media_urls: description: Optional media urls supplied by this operation. Null means unknown. type: - array items: description: Optional record supplied by this operation. Null means unknown. type: - string - 'null' - required: - music properties: music: description: Optional music supplied by this operation. Null means unknown. type: - object properties: album: description: Optional album supplied by this operation. Null means unknown. type: - string - 'null' author: description: Public author information supplied with this record. type: - string - 'null' cover_url: description: Optional cover url supplied by this operation. Null means unknown. type: - string - 'null' duration_s: description: Optional duration s supplied by this operation. Null means unknown. type: - number - 'null' id: description: Source identifier. Preserve the supplied type and exact value. type: - string - 'null' is_original: description: Optional is original supplied by this operation. Null means unknown. type: - boolean - 'null' play_url: description: Optional play url supplied by this operation. Null means unknown. type: - string - 'null' title: description: Source title when supplied. type: - string - 'null' additionalProperties: true - required: - stats properties: stats: description: Optional stats supplied by this operation. Null means unknown. type: - object properties: comments: description: Optional comments supplied by this operation. Null means unknown. type: - number - 'null' likes: description: Optional likes supplied by this operation. Null means unknown. type: - number - 'null' plays: description: Optional plays supplied by this operation. Null means unknown. type: - number - 'null' saves: description: Optional saves supplied by this operation. Null means unknown. type: - number - 'null' shares: description: Optional shares supplied by this operation. Null means unknown. type: - number - 'null' additionalProperties: true - required: - thumbnail_url properties: thumbnail_url: description: Optional thumbnail url supplied by this operation. Null means unknown. type: - string minLength: 1 - required: - url properties: url: description: Original source URL when supplied. type: - string minLength: 1 - required: - video_url properties: video_url: description: Optional video url supplied by this operation. Null means unknown. type: - string minLength: 1 place_id: description: Optional place id supplied by this operation. Null means unknown. type: - string - 'null' additionalProperties: true required: - items x-contract-version: '2026-09-22' x-validation-scope: Required success payload structure; optional fields and source completeness remain separate. examples: - count: 0 cursor: null dropped: 0 has_more: false items: - author: avatar_url: https://example.com/example followers: 0 handle: example id: example name: example private: false verified: false caption: example created_at: '2026-09-01T12:00:00Z' duration_s: 0 hashtags: - {} id: example images: [] is_ad: false media_urls: - example music: album: example author: example cover_url: https://example.com/example duration_s: 0 id: example is_original: false play_url: https://example.com/example title: example platform: example stats: comments: 0 likes: 0 plays: 0 saves: 0 shares: 0 thumbnail_url: https://example.com/example url: https://example.com/example video_url: https://example.com/example place_id: example default: description: The error envelope — the same shape for every non-2xx status. content: application/json: schema: $ref: '#/components/schemas/Error' x-credits: 1 x-production-available: true x-capacity: status: not_assessed message: Capacity is workload-dependent; configured routes do not establish sustained throughput or an availability guarantee. x-availability-scope: Structural check of the effective registered chain, production permission, adapter, configured cost and quality floor without request parameters. True is not a live-health, credential, quota, subscription-entitlement, complete-data or deployment-exposure guarantee. False means no structurally eligible candidate; null means metadata could not establish availability. Composite child capability still depends on its component routes. x-live-proven: true /v1/tiktok/playlist-videos: get: operationId: tiktok_playlist_videos tags: - tiktok summary: TikTok playlist videos description: 'The videos in a TikTok playlist: description, cover, duration, play URL, counts and author, in playlist order. Costs 7 credits per successful live response.' parameters: - name: playlist_id in: query required: true schema: type: string example: '7681171537575824159' description: Playlist id from tiktok/user-playlists, or the playlist URL - name: limit in: query required: false schema: type: string example: '10' description: Videos per page, up to 30 - name: cursor in: query required: false schema: type: string example: '' description: Cursor from a previous page - name: dry_run in: query required: false schema: type: string enum: - '1' - '0' - 'true' - 'false' example: '1' description: 'Read a zero-credit estimate without fetching sources, running AI, or reserving credits. Cache status is a snapshot, not a guarantee at execution. Accepted values: 1, 0, true, false. Case, spaces, hyphens and underscores are interchangeable.' - name: judgments in: query required: false schema: type: string enum: - 'on' - 'off' example: 'on' description: 'Add bounded AI labels to eligible returned records (default on). off preserves the original data shape. Unclassified records remain present; labels depend on evidence, time, capacity and the existing request budget. No label surcharge. Accepted values: on, off. Case, spaces, hyphens and underscores are interchangeable.' - name: label in: query required: false schema: type: string enum: - default - none example: none description: 'Set none to disable labels; default enables the endpoint’s label set. Equivalent to judgments=off. Accepted values: default, none. Case, spaces, hyphens and underscores are interchangeable.' - name: label_evidence in: query required: false schema: type: string enum: - '1' - '0' - 'true' - 'false' example: '1' description: 'Include exact supporting sentences and zero-based sentence indexes when a label has validated evidence. No extra charge or change to decisions. Accepted values: 1, 0, true, false. Case, spaces, hyphens and underscores are interchangeable.' - name: exclude in: query required: false schema: type: string enum: - engagement_bait example: engagement_bait description: 'Optionally remove confidently labelled engagement bait. Uncertain and unclassified records stay; removed IDs and an owner-bound recall reference are returned. Accepted values: engagement_bait. Case, spaces, hyphens and underscores are interchangeable.' - name: fit in: query required: false schema: type: string enum: - goal example: goal description: 'Use goal to replace confidently irrelevant records with recall stubs. Keeps first, last, relevant and uncertain records; preserves order. Full evidence is stored for 24 hours when available. Accepted values: goal. Case, spaces, hyphens and underscores are interchangeable.' - name: goal in: query required: false schema: type: string example: Find concrete product complaints description: 'Required with fit=goal: describe the task in at most 600 characters. Supplied text is task context, never permission to act on posts.' - name: tokens in: query required: false schema: type: string example: '4000' description: Optional soft response target for fit=goal, 256–32000. Safety and evidence retention take priority, so the returned result may exceed it. - name: X-Max-Credits in: header required: false schema: type: integer minimum: 0 maximum: 9007199254740991 example: 5 description: Optional credit reservation ceiling for this individual request. Send a non-negative integer in decimal digits. Live execution checks the required reservation after resolving free cache hits or buffered continuation, before charging or calling a supplier. A higher reservation returns HTTP 422 INVALID_PARAMETERS with reason max_credits_exceeded and charges nothing. Invalid header values also return 422. Zero permits only a zero-credit reservation; omitting the header uses normal pricing. dry_run remains a free preview. This does not cap later requests, batches or scheduled runs. security: - ApiKeyHeader: [] - BearerKey: [] responses: '200': description: 'The common success envelope; `data` is endpoint-specific. Many lists use items/count/cursor; bundles use named collections and their documented continuation metadata. HTTP 200 can contain a partial bundle: inspect complete, partial and legs where supplied.' content: application/json: schema: allOf: - $ref: '#/components/schemas/Success' - type: object properties: data: $schema: https://json-schema.org/draft/2020-12/schema $id: https://www.monocrawl.com/schemas/tiktok/playlist-videos.json title: tiktok/playlist-videos data fields description: Optional data supplied by this operation. Null means unknown. type: object properties: count: description: Number of records in this response, not lifetime or total matches. type: - number - 'null' dropped: description: Optional dropped supplied by this operation. Null means unknown. type: - number - 'null' has_more: description: Source continuation indicator; null means unknown. type: - boolean - 'null' items: description: Returned records. Source coverage and completeness vary. type: - array items: description: Optional record supplied by this operation. Null means unknown. type: object properties: author: description: Public author information supplied with this record. type: - object - 'null' properties: avatar_url: description: Optional avatar url supplied by this operation. Null means unknown. type: - string - 'null' handle: description: Optional handle supplied by this operation. Null means unknown. type: - string - 'null' id: description: Source identifier. Preserve the supplied type and exact value. type: - string - 'null' name: description: Optional name supplied by this operation. Null means unknown. type: - string - 'null' additionalProperties: true caption: description: Optional caption supplied by this operation. Null means unknown. type: - string - 'null' cover: description: Optional cover supplied by this operation. Null means unknown. type: - string - 'null' created_at: description: Source creation time, not the API retrieval time. type: - string - 'null' duration_s: description: Optional duration s supplied by this operation. Null means unknown. type: - number - 'null' id: description: Source identifier. Preserve the supplied type and exact value. type: - string - 'null' images: description: Source array was empty in the reviewed captures; item fields remain unspecified. type: - array - 'null' items: {} is_ad: description: Optional is ad supplied by this operation. Null means unknown. type: - boolean - 'null' is_pinned: description: Optional is pinned supplied by this operation. Null means unknown. type: - boolean - 'null' media_urls: description: Optional media urls supplied by this operation. Null means unknown. type: - array - 'null' items: description: Optional record supplied by this operation. Null means unknown. type: - string - 'null' music: description: Optional music supplied by this operation. Null means unknown. type: - object - 'null' properties: {} additionalProperties: true platform: description: Optional platform supplied by this operation. Null means unknown. type: - string - 'null' play_url: description: Optional play url supplied by this operation. Null means unknown. type: - string - 'null' region: description: Optional region supplied by this operation. Null means unknown. type: - string - 'null' stats: description: Optional stats supplied by this operation. Null means unknown. type: - object - 'null' properties: comments: description: Optional comments supplied by this operation. Null means unknown. type: - number - 'null' downloads: description: Optional downloads supplied by this operation. Null means unknown. type: - number - 'null' likes: description: Optional likes supplied by this operation. Null means unknown. type: - number - 'null' plays: description: Optional plays supplied by this operation. Null means unknown. type: - number - 'null' saves: description: Optional saves supplied by this operation. Null means unknown. type: - number - 'null' shares: description: Optional shares supplied by this operation. Null means unknown. type: - number - 'null' additionalProperties: true thumbnail_url: description: Optional thumbnail url supplied by this operation. Null means unknown. type: - string - 'null' url: description: Original source URL when supplied. type: - string - 'null' video_url: description: Optional video url supplied by this operation. Null means unknown. type: - string - 'null' additionalProperties: true allOf: - anyOf: - required: - author properties: author: description: Public author information supplied with this record. type: - object properties: avatar_url: description: Optional avatar url supplied by this operation. Null means unknown. type: - string - 'null' handle: description: Optional handle supplied by this operation. Null means unknown. type: - string - 'null' id: description: Source identifier. Preserve the supplied type and exact value. type: - string - 'null' name: description: Optional name supplied by this operation. Null means unknown. type: - string - 'null' additionalProperties: true - required: - caption properties: caption: description: Optional caption supplied by this operation. Null means unknown. type: - string minLength: 1 - required: - cover properties: cover: description: Optional cover supplied by this operation. Null means unknown. type: - string minLength: 1 - required: - created_at properties: created_at: description: Source creation time, not the API retrieval time. type: - string minLength: 1 - required: - duration_s properties: duration_s: description: Optional duration s supplied by this operation. Null means unknown. type: - number - required: - id properties: id: description: Source identifier. Preserve the supplied type and exact value. type: - string minLength: 1 - required: - images properties: images: description: Source array was empty in the reviewed captures; item fields remain unspecified. type: - array items: {} - required: - is_ad properties: is_ad: description: Optional is ad supplied by this operation. Null means unknown. type: - boolean - required: - is_pinned properties: is_pinned: description: Optional is pinned supplied by this operation. Null means unknown. type: - boolean - required: - media_urls properties: media_urls: description: Optional media urls supplied by this operation. Null means unknown. type: - array items: description: Optional record supplied by this operation. Null means unknown. type: - string - 'null' - required: - music properties: music: description: Optional music supplied by this operation. Null means unknown. type: - object properties: {} additionalProperties: true - required: - play_url properties: play_url: description: Optional play url supplied by this operation. Null means unknown. type: - string minLength: 1 - required: - region properties: region: description: Optional region supplied by this operation. Null means unknown. type: - string minLength: 1 - required: - stats properties: stats: description: Optional stats supplied by this operation. Null means unknown. type: - object properties: comments: description: Optional comments supplied by this operation. Null means unknown. type: - number - 'null' downloads: description: Optional downloads supplied by this operation. Null means unknown. type: - number - 'null' likes: description: Optional likes supplied by this operation. Null means unknown. type: - number - 'null' plays: description: Optional plays supplied by this operation. Null means unknown. type: - number - 'null' saves: description: Optional saves supplied by this operation. Null means unknown. type: - number - 'null' shares: description: Optional shares supplied by this operation. Null means unknown. type: - number - 'null' additionalProperties: true - required: - thumbnail_url properties: thumbnail_url: description: Optional thumbnail url supplied by this operation. Null means unknown. type: - string minLength: 1 - required: - url properties: url: description: Original source URL when supplied. type: - string minLength: 1 - required: - video_url properties: video_url: description: Optional video url supplied by this operation. Null means unknown. type: - string minLength: 1 playlist_id: description: Optional playlist id supplied by this operation. Null means unknown. type: - string - 'null' additionalProperties: true required: - items x-contract-version: '2026-09-22' x-validation-scope: Required success payload structure; optional fields and source completeness remain separate. examples: - count: 0 dropped: 0 has_more: false items: - author: avatar_url: https://example.com/example handle: example id: example name: example caption: example cover: example created_at: '2026-09-01T12:00:00Z' duration_s: 0 id: example images: [] is_ad: false is_pinned: false media_urls: - example music: {} platform: example play_url: https://example.com/example region: example stats: comments: 0 downloads: 0 likes: 0 plays: 0 saves: 0 shares: 0 thumbnail_url: https://example.com/example url: https://example.com/example video_url: https://example.com/example playlist_id: example default: description: The error envelope — the same shape for every non-2xx status. content: application/json: schema: $ref: '#/components/schemas/Error' x-credits: 7 x-production-available: true x-capacity: status: not_assessed message: Capacity is workload-dependent; configured routes do not establish sustained throughput or an availability guarantee. x-availability-scope: Structural check of the effective registered chain, production permission, adapter, configured cost and quality floor without request parameters. True is not a live-health, credential, quota, subscription-entitlement, complete-data or deployment-exposure guarantee. False means no structurally eligible candidate; null means metadata could not establish availability. Composite child capability still depends on its component routes. x-live-proven: true /v1/tiktok/post: get: operationId: tiktok_post tags: - tiktok summary: Video details description: 'One TikTok video: caption, author, duration and current engagement counts. Costs 1 credit per successful live response.' parameters: - name: url in: query required: true schema: type: string example: https://www.tiktok.com/@nasa/video/7665075736742530317 description: Full TikTok video URL. - name: dry_run in: query required: false schema: type: string enum: - '1' - '0' - 'true' - 'false' example: '1' description: 'Read a zero-credit estimate without fetching sources, running AI, or reserving credits. Cache status is a snapshot, not a guarantee at execution. Accepted values: 1, 0, true, false. Case, spaces, hyphens and underscores are interchangeable.' - name: judgments in: query required: false schema: type: string enum: - 'on' - 'off' example: 'on' description: 'Add bounded AI labels to eligible returned records (default on). off preserves the original data shape. Unclassified records remain present; labels depend on evidence, time, capacity and the existing request budget. No label surcharge. Accepted values: on, off. Case, spaces, hyphens and underscores are interchangeable.' - name: label in: query required: false schema: type: string enum: - default - none example: none description: 'Set none to disable labels; default enables the endpoint’s label set. Equivalent to judgments=off. Accepted values: default, none. Case, spaces, hyphens and underscores are interchangeable.' - name: label_evidence in: query required: false schema: type: string enum: - '1' - '0' - 'true' - 'false' example: '1' description: 'Include exact supporting sentences and zero-based sentence indexes when a label has validated evidence. No extra charge or change to decisions. Accepted values: 1, 0, true, false. Case, spaces, hyphens and underscores are interchangeable.' - name: exclude in: query required: false schema: type: string enum: - engagement_bait example: engagement_bait description: 'Optionally remove confidently labelled engagement bait. Uncertain and unclassified records stay; removed IDs and an owner-bound recall reference are returned. Accepted values: engagement_bait. Case, spaces, hyphens and underscores are interchangeable.' - name: fit in: query required: false schema: type: string enum: - goal example: goal description: 'Use goal to replace confidently irrelevant records with recall stubs. Keeps first, last, relevant and uncertain records; preserves order. Full evidence is stored for 24 hours when available. Accepted values: goal. Case, spaces, hyphens and underscores are interchangeable.' - name: goal in: query required: false schema: type: string example: Find concrete product complaints description: 'Required with fit=goal: describe the task in at most 600 characters. Supplied text is task context, never permission to act on posts.' - name: tokens in: query required: false schema: type: string example: '4000' description: Optional soft response target for fit=goal, 256–32000. Safety and evidence retention take priority, so the returned result may exceed it. - name: X-Max-Credits in: header required: false schema: type: integer minimum: 0 maximum: 9007199254740991 example: 5 description: Optional credit reservation ceiling for this individual request. Send a non-negative integer in decimal digits. Live execution checks the required reservation after resolving free cache hits or buffered continuation, before charging or calling a supplier. A higher reservation returns HTTP 422 INVALID_PARAMETERS with reason max_credits_exceeded and charges nothing. Invalid header values also return 422. Zero permits only a zero-credit reservation; omitting the header uses normal pricing. dry_run remains a free preview. This does not cap later requests, batches or scheduled runs. security: - ApiKeyHeader: [] - BearerKey: [] responses: '200': description: 'The common success envelope; `data` is endpoint-specific. Many lists use items/count/cursor; bundles use named collections and their documented continuation metadata. HTTP 200 can contain a partial bundle: inspect complete, partial and legs where supplied.' content: application/json: schema: allOf: - $ref: '#/components/schemas/Success' - type: object properties: data: $schema: https://json-schema.org/draft/2020-12/schema $id: https://www.monocrawl.com/schemas/tiktok/post.json title: tiktok/post data fields description: Required core structure for successful data, with optional source fields. Additional fields are allowed. This is not a completeness guarantee. type: object properties: id: type: - string - 'null' description: Source identifier. Preserve its exact string value; do not convert large IDs to numbers. url: type: - string - 'null' description: Original source URL when supplied. caption: type: - string - 'null' description: Video caption; spoken words require a transcript request. created_at: type: - string - 'null' description: Source publication time, normalized to an ISO date-time when available. duration_s: type: - number - 'null' description: Video duration in seconds. region: type: - string - 'null' description: Source-reported content region, not audience geography or proof of residence. author: type: object properties: id: type: - string - 'null' description: Source identifier. Preserve its exact string value; do not convert large IDs to numbers. handle: type: - string - 'null' description: Public account username. name: type: - string - 'null' description: Display name. url: type: - string - 'null' description: Original source URL when supplied. followers: type: - number - 'null' description: Follower count supplied with this video; null when absent. No profile-enrichment call is made. region: type: - string - 'null' description: Source-reported account region, not audience geography or proof of residence. avatar_url: type: - string - 'null' description: Original source URL when supplied. verified: type: - boolean - 'null' description: Explicit source verification flag; precise search may omit it. additionalProperties: true stats: type: object properties: plays: type: - number - 'null' description: plays reported by the source; null or absent is unknown, not zero. likes: type: - number - 'null' description: likes reported by the source; null or absent is unknown, not zero. comments: type: - number - 'null' description: comments reported by the source; null or absent is unknown, not zero. shares: type: - number - 'null' description: shares reported by the source; null or absent is unknown, not zero. saves: type: - number - 'null' description: saves reported by the source; null or absent is unknown, not zero. additionalProperties: true music: type: - object - 'null' properties: id: type: - string - 'null' description: Source identifier. Preserve its exact string value; do not convert large IDs to numbers. title: type: - string - 'null' description: Source sound title. author: type: - string - 'null' description: Source sound author. duration_s: type: - number - 'null' description: Source sound duration in seconds. is_original: type: - boolean - 'null' description: Explicit source original-sound flag. play_url: type: - string - 'null' description: Original source URL when supplied. cover_url: type: - string - 'null' description: Original source URL when supplied. additionalProperties: true _warnings: type: array items: type: string description: Collection limitations or component warnings. Read before interpreting coverage. cover_ocr: type: object properties: available: type: - boolean - 'null' description: Whether this post supplied a usable cover URL. scope: type: - string - 'null' description: cover_image_only image_url: type: - string - 'null' description: Original source URL when supplied. endpoint: type: - string - 'null' description: web/parse params: type: object properties: url: type: - string - 'null' description: Original source URL when supplied. additionalProperties: true quote: type: object properties: {} additionalProperties: true read: type: object properties: {} additionalProperties: true note: type: - string - 'null' description: Separate request, price and image-scope limitations. additionalProperties: true additionalProperties: true allOf: - anyOf: - required: - id properties: id: type: - string description: Source identifier. Preserve its exact string value; do not convert large IDs to numbers. minLength: 1 - required: - url properties: url: type: - string description: Original source URL when supplied. minLength: 1 - required: - caption properties: caption: type: - string description: Video caption; spoken words require a transcript request. minLength: 1 - required: - created_at properties: created_at: type: - string description: Source publication time, normalized to an ISO date-time when available. minLength: 1 - required: - duration_s properties: duration_s: type: - number description: Video duration in seconds. - required: - region properties: region: type: - string description: Source-reported content region, not audience geography or proof of residence. minLength: 1 - required: - author properties: author: type: object properties: id: type: - string - 'null' description: Source identifier. Preserve its exact string value; do not convert large IDs to numbers. handle: type: - string - 'null' description: Public account username. name: type: - string - 'null' description: Display name. url: type: - string - 'null' description: Original source URL when supplied. followers: type: - number - 'null' description: Follower count supplied with this video; null when absent. No profile-enrichment call is made. region: type: - string - 'null' description: Source-reported account region, not audience geography or proof of residence. avatar_url: type: - string - 'null' description: Original source URL when supplied. verified: type: - boolean - 'null' description: Explicit source verification flag; precise search may omit it. additionalProperties: true - required: - stats properties: stats: type: object properties: plays: type: - number - 'null' description: plays reported by the source; null or absent is unknown, not zero. likes: type: - number - 'null' description: likes reported by the source; null or absent is unknown, not zero. comments: type: - number - 'null' description: comments reported by the source; null or absent is unknown, not zero. shares: type: - number - 'null' description: shares reported by the source; null or absent is unknown, not zero. saves: type: - number - 'null' description: saves reported by the source; null or absent is unknown, not zero. additionalProperties: true - required: - music properties: music: type: - object properties: id: type: - string - 'null' description: Source identifier. Preserve its exact string value; do not convert large IDs to numbers. title: type: - string - 'null' description: Source sound title. author: type: - string - 'null' description: Source sound author. duration_s: type: - number - 'null' description: Source sound duration in seconds. is_original: type: - boolean - 'null' description: Explicit source original-sound flag. play_url: type: - string - 'null' description: Original source URL when supplied. cover_url: type: - string - 'null' description: Original source URL when supplied. additionalProperties: true - required: - cover_ocr properties: cover_ocr: type: object properties: available: type: - boolean - 'null' description: Whether this post supplied a usable cover URL. scope: type: - string - 'null' description: cover_image_only image_url: type: - string - 'null' description: Original source URL when supplied. endpoint: type: - string - 'null' description: web/parse params: type: object properties: url: type: - string - 'null' description: Original source URL when supplied. additionalProperties: true quote: type: object properties: {} additionalProperties: true read: type: object properties: {} additionalProperties: true note: type: - string - 'null' description: Separate request, price and image-scope limitations. additionalProperties: true x-contract-version: '2026-09-22' x-validation-scope: Required success payload structure; optional fields and source completeness remain separate. examples: - id: '7350000000000000002' url: https://www.tiktok.com/@example_creator/video/7350000000000000002 caption: A desk setup created_at: '2026-09-01T12:00:00.000Z' duration_s: 15 stats: plays: 1200 likes: 100 comments: 12 shares: null saves: 8 default: description: The error envelope — the same shape for every non-2xx status. content: application/json: schema: $ref: '#/components/schemas/Error' x-credits: 1 x-production-available: true x-capacity: status: not_assessed message: Capacity is workload-dependent; configured routes do not establish sustained throughput or an availability guarantee. x-availability-scope: Structural check of the effective registered chain, production permission, adapter, configured cost and quality floor without request parameters. True is not a live-health, credential, quota, subscription-entitlement, complete-data or deployment-exposure guarantee. False means no structurally eligible candidate; null means metadata could not establish availability. Composite child capability still depends on its component routes. x-live-proven: true /v1/tiktok/post-comments: get: operationId: tiktok_post_comments tags: - tiktok summary: Video comments description: Comments on a TikTok video with like and reply counts. Paged by cursor. Costs 1 credit per successful live response. parameters: - name: url in: query required: true schema: type: string example: https://www.tiktok.com/@nasa/video/7665075736742530317 description: Full TikTok video URL. - name: cursor in: query required: false schema: type: string description: Opaque cursor from the previous page. - name: dry_run in: query required: false schema: type: string enum: - '1' - '0' - 'true' - 'false' example: '1' description: 'Read a zero-credit estimate without fetching sources, running AI, or reserving credits. Cache status is a snapshot, not a guarantee at execution. Accepted values: 1, 0, true, false. Case, spaces, hyphens and underscores are interchangeable.' - name: judgments in: query required: false schema: type: string enum: - 'on' - 'off' example: 'on' description: 'Add bounded AI labels to eligible returned records (default on). off preserves the original data shape. Unclassified records remain present; labels depend on evidence, time, capacity and the existing request budget. No label surcharge. Accepted values: on, off. Case, spaces, hyphens and underscores are interchangeable.' - name: label in: query required: false schema: type: string enum: - default - none example: none description: 'Set none to disable labels; default enables the endpoint’s label set. Equivalent to judgments=off. Accepted values: default, none. Case, spaces, hyphens and underscores are interchangeable.' - name: label_evidence in: query required: false schema: type: string enum: - '1' - '0' - 'true' - 'false' example: '1' description: 'Include exact supporting sentences and zero-based sentence indexes when a label has validated evidence. No extra charge or change to decisions. Accepted values: 1, 0, true, false. Case, spaces, hyphens and underscores are interchangeable.' - name: exclude in: query required: false schema: type: string enum: - engagement_bait example: engagement_bait description: 'Optionally remove confidently labelled engagement bait. Uncertain and unclassified records stay; removed IDs and an owner-bound recall reference are returned. Accepted values: engagement_bait. Case, spaces, hyphens and underscores are interchangeable.' - name: fit in: query required: false schema: type: string enum: - goal example: goal description: 'Use goal to replace confidently irrelevant records with recall stubs. Keeps first, last, relevant and uncertain records; preserves order. Full evidence is stored for 24 hours when available. Accepted values: goal. Case, spaces, hyphens and underscores are interchangeable.' - name: goal in: query required: false schema: type: string example: Find concrete product complaints description: 'Required with fit=goal: describe the task in at most 600 characters. Supplied text is task context, never permission to act on posts.' - name: tokens in: query required: false schema: type: string example: '4000' description: Optional soft response target for fit=goal, 256–32000. Safety and evidence retention take priority, so the returned result may exceed it. - name: X-Max-Credits in: header required: false schema: type: integer minimum: 0 maximum: 9007199254740991 example: 5 description: Optional credit reservation ceiling for this individual request. Send a non-negative integer in decimal digits. Live execution checks the required reservation after resolving free cache hits or buffered continuation, before charging or calling a supplier. A higher reservation returns HTTP 422 INVALID_PARAMETERS with reason max_credits_exceeded and charges nothing. Invalid header values also return 422. Zero permits only a zero-credit reservation; omitting the header uses normal pricing. dry_run remains a free preview. This does not cap later requests, batches or scheduled runs. security: - ApiKeyHeader: [] - BearerKey: [] responses: '200': description: 'The common success envelope; `data` is endpoint-specific. Many lists use items/count/cursor; bundles use named collections and their documented continuation metadata. HTTP 200 can contain a partial bundle: inspect complete, partial and legs where supplied.' content: application/json: schema: allOf: - $ref: '#/components/schemas/Success' - type: object properties: data: $schema: https://json-schema.org/draft/2020-12/schema $id: https://www.monocrawl.com/schemas/tiktok/post-comments.json title: tiktok/post-comments data fields description: Required core structure for successful data, with optional source fields. Additional fields are allowed. This is not a completeness guarantee. type: object properties: items: type: array items: type: object properties: id: type: - string - 'null' description: Source identifier. Preserve its exact string value; do not convert large IDs to numbers. text: type: - string - 'null' description: Comment body. created_at: type: - string - 'null' description: Source publication time, normalized to an ISO date-time when available. likes: type: - number - 'null' description: Likes reported by the source; null or absent is unknown, not zero. reply_count: type: - number - 'null' description: Replies reported by the source; null or absent is unknown, not zero. author: type: object properties: id: type: - string - 'null' description: Source identifier. Preserve its exact string value; do not convert large IDs to numbers. handle: type: - string - 'null' description: Public account username. name: type: - string - 'null' description: Display name. url: type: - string - 'null' description: Original source URL when supplied. additionalProperties: true additionalProperties: true allOf: - anyOf: - required: - id properties: id: type: - string description: Source identifier. Preserve its exact string value; do not convert large IDs to numbers. minLength: 1 - required: - text properties: text: type: - string description: Comment body. minLength: 1 - required: - created_at properties: created_at: type: - string description: Source publication time, normalized to an ISO date-time when available. minLength: 1 - required: - likes properties: likes: type: - number description: Likes reported by the source; null or absent is unknown, not zero. - required: - reply_count properties: reply_count: type: - number description: Replies reported by the source; null or absent is unknown, not zero. - required: - author properties: author: type: object properties: id: type: - string - 'null' description: Source identifier. Preserve its exact string value; do not convert large IDs to numbers. handle: type: - string - 'null' description: Public account username. name: type: - string - 'null' description: Display name. url: type: - string - 'null' description: Original source URL when supplied. additionalProperties: true description: Records in this response page. count: type: - number - 'null' description: Returned row count when supplied; not the full source total. cursor: type: - string - 'null' description: Opaque next-page token. A missing token does not prove full history was retrieved. has_more: type: - boolean - 'null' description: Source continuation indicator; null means unknown. _warnings: type: array items: type: string description: Collection limitations or component warnings. Read before interpreting coverage. additionalProperties: true required: - items x-contract-version: '2026-09-22' x-validation-scope: Required success payload structure; optional fields and source completeness remain separate. examples: - items: - id: '7350000000000000003' text: Useful setup likes: 3 reply_count: 0 author: handle: example_reader cursor: null has_more: null default: description: The error envelope — the same shape for every non-2xx status. content: application/json: schema: $ref: '#/components/schemas/Error' x-credits: 1 x-production-available: true x-capacity: status: not_assessed message: Capacity is workload-dependent; configured routes do not establish sustained throughput or an availability guarantee. x-availability-scope: Structural check of the effective registered chain, production permission, adapter, configured cost and quality floor without request parameters. True is not a live-health, credential, quota, subscription-entitlement, complete-data or deployment-exposure guarantee. False means no structurally eligible candidate; null means metadata could not establish availability. Composite child capability still depends on its component routes. x-live-proven: true /v1/tiktok/post-transcript: get: operationId: tiktok_post_transcript tags: - tiktok summary: Video transcript description: The spoken words of a TikTok video as text. transcript is null when the video has no captions — that is the honest answer, not an error. Costs 5 credits per successful live response. parameters: - name: url in: query required: true schema: type: string example: https://www.tiktok.com/@nasa/video/7665075736742530317 description: Full TikTok video URL. - name: dry_run in: query required: false schema: type: string enum: - '1' - '0' - 'true' - 'false' example: '1' description: 'Read a zero-credit estimate without fetching sources, running AI, or reserving credits. Cache status is a snapshot, not a guarantee at execution. Accepted values: 1, 0, true, false. Case, spaces, hyphens and underscores are interchangeable.' - name: X-Max-Credits in: header required: false schema: type: integer minimum: 0 maximum: 9007199254740991 example: 5 description: Optional credit reservation ceiling for this individual request. Send a non-negative integer in decimal digits. Live execution checks the required reservation after resolving free cache hits or buffered continuation, before charging or calling a supplier. A higher reservation returns HTTP 422 INVALID_PARAMETERS with reason max_credits_exceeded and charges nothing. Invalid header values also return 422. Zero permits only a zero-credit reservation; omitting the header uses normal pricing. dry_run remains a free preview. This does not cap later requests, batches or scheduled runs. security: - ApiKeyHeader: [] - BearerKey: [] responses: '200': description: 'The common success envelope; `data` is endpoint-specific. Many lists use items/count/cursor; bundles use named collections and their documented continuation metadata. HTTP 200 can contain a partial bundle: inspect complete, partial and legs where supplied.' content: application/json: schema: allOf: - $ref: '#/components/schemas/Success' - type: object properties: data: $schema: https://json-schema.org/draft/2020-12/schema $id: https://www.monocrawl.com/schemas/tiktok/post-transcript.json title: tiktok/post-transcript data fields description: Optional data supplied by this operation. Null means unknown. type: object properties: has_transcript: description: Optional has transcript supplied by this operation. Null means unknown. type: - boolean - 'null' id: description: Source identifier. Preserve the supplied type and exact value. type: - string - 'null' platform: description: Optional platform supplied by this operation. Null means unknown. type: - string - 'null' transcript: description: Optional transcript supplied by this operation. Null means unknown. type: - string - 'null' url: description: Original source URL when supplied. type: - string - 'null' additionalProperties: true allOf: - anyOf: - required: - has_transcript properties: has_transcript: description: Optional has transcript supplied by this operation. Null means unknown. type: - boolean - required: - id properties: id: description: Source identifier. Preserve the supplied type and exact value. type: - string minLength: 1 - required: - transcript properties: transcript: description: Optional transcript supplied by this operation. Null means unknown. type: - string minLength: 1 - required: - url properties: url: description: Original source URL when supplied. type: - string minLength: 1 x-contract-version: '2026-09-22' x-validation-scope: Required success payload structure; optional fields and source completeness remain separate. examples: - has_transcript: false id: example platform: example transcript: example url: https://example.com/example default: description: The error envelope — the same shape for every non-2xx status. content: application/json: schema: $ref: '#/components/schemas/Error' x-credits: 5 x-production-available: true x-capacity: status: not_assessed message: Capacity is workload-dependent; configured routes do not establish sustained throughput or an availability guarantee. x-availability-scope: Structural check of the effective registered chain, production permission, adapter, configured cost and quality floor without request parameters. True is not a live-health, credential, quota, subscription-entitlement, complete-data or deployment-exposure guarantee. False means no structurally eligible candidate; null means metadata could not establish availability. Composite child capability still depends on its component routes. x-live-proven: true /v1/tiktok/profile: get: operationId: tiktok_profile tags: - tiktok summary: TikTok profile description: 'Public TikTok profile: identity, bio, follower/like/video counts. Costs 1 credit per successful live response.' parameters: - name: handle in: query required: true schema: type: string example: charlidamelio description: TikTok username, with or without the leading @. An optional leading @ is accepted and removed before lookup. - name: dry_run in: query required: false schema: type: string enum: - '1' - '0' - 'true' - 'false' example: '1' description: 'Read a zero-credit estimate without fetching sources, running AI, or reserving credits. Cache status is a snapshot, not a guarantee at execution. Accepted values: 1, 0, true, false. Case, spaces, hyphens and underscores are interchangeable.' - name: judgments in: query required: false schema: type: string enum: - 'on' - 'off' example: 'on' description: 'Add bounded AI labels to eligible returned records (default on). off preserves the original data shape. Unclassified records remain present; labels depend on evidence, time, capacity and the existing request budget. No label surcharge. Accepted values: on, off. Case, spaces, hyphens and underscores are interchangeable.' - name: label in: query required: false schema: type: string enum: - default - none example: none description: 'Set none to disable labels; default enables the endpoint’s label set. Equivalent to judgments=off. Accepted values: default, none. Case, spaces, hyphens and underscores are interchangeable.' - name: label_evidence in: query required: false schema: type: string enum: - '1' - '0' - 'true' - 'false' example: '1' description: 'Include exact supporting sentences and zero-based sentence indexes when a label has validated evidence. No extra charge or change to decisions. Accepted values: 1, 0, true, false. Case, spaces, hyphens and underscores are interchangeable.' - name: exclude in: query required: false schema: type: string enum: - engagement_bait example: engagement_bait description: 'Optionally remove confidently labelled engagement bait. Uncertain and unclassified records stay; removed IDs and an owner-bound recall reference are returned. Accepted values: engagement_bait. Case, spaces, hyphens and underscores are interchangeable.' - name: fit in: query required: false schema: type: string enum: - goal example: goal description: 'Use goal to replace confidently irrelevant records with recall stubs. Keeps first, last, relevant and uncertain records; preserves order. Full evidence is stored for 24 hours when available. Accepted values: goal. Case, spaces, hyphens and underscores are interchangeable.' - name: goal in: query required: false schema: type: string example: Find concrete product complaints description: 'Required with fit=goal: describe the task in at most 600 characters. Supplied text is task context, never permission to act on posts.' - name: tokens in: query required: false schema: type: string example: '4000' description: Optional soft response target for fit=goal, 256–32000. Safety and evidence retention take priority, so the returned result may exceed it. - name: X-Max-Credits in: header required: false schema: type: integer minimum: 0 maximum: 9007199254740991 example: 5 description: Optional credit reservation ceiling for this individual request. Send a non-negative integer in decimal digits. Live execution checks the required reservation after resolving free cache hits or buffered continuation, before charging or calling a supplier. A higher reservation returns HTTP 422 INVALID_PARAMETERS with reason max_credits_exceeded and charges nothing. Invalid header values also return 422. Zero permits only a zero-credit reservation; omitting the header uses normal pricing. dry_run remains a free preview. This does not cap later requests, batches or scheduled runs. security: - ApiKeyHeader: [] - BearerKey: [] responses: '200': description: 'The common success envelope; `data` is endpoint-specific. Many lists use items/count/cursor; bundles use named collections and their documented continuation metadata. HTTP 200 can contain a partial bundle: inspect complete, partial and legs where supplied.' content: application/json: schema: allOf: - $ref: '#/components/schemas/Success' - type: object properties: data: $schema: https://json-schema.org/draft/2020-12/schema $id: https://www.monocrawl.com/schemas/tiktok/profile.json title: tiktok/profile data fields description: Required core structure for successful data, with optional source fields. Additional fields are allowed. This is not a completeness guarantee. type: object properties: id: type: - string - 'null' description: Source identifier. Preserve its exact string value; do not convert large IDs to numbers. handle: type: - string - 'null' description: Public account username. name: type: - string - 'null' description: Display name. url: type: - string - 'null' description: Original source URL when supplied. bio: type: - string - 'null' description: Public biography. bio_link: type: - string - 'null' description: Original source URL when supplied. avatar_url: type: - string - 'null' description: Original source URL when supplied. followers: type: - number - 'null' description: Followers reported by the source; null or absent is unknown, not zero. following: type: - number - 'null' description: Following reported by the source; null or absent is unknown, not zero. verified: type: - boolean - 'null' description: Source verification flag; meaning depends on the platform. likes_count: type: - number - 'null' description: Account likes reported by the source; null or absent is unknown, not zero. video_count: type: - number - 'null' description: Videos reported by the source; null or absent is unknown, not zero. commerce_user: type: - boolean - 'null' description: Commerce-account flag; not a business category. seller: type: - boolean - 'null' description: Seller flag. region: type: - string - 'null' description: Account region supplied by TikTok; not personal residence. business_category: type: - string - 'null' description: Public source category. _warnings: type: array items: type: string description: Collection limitations or component warnings. Read before interpreting coverage. additionalProperties: true allOf: - anyOf: - required: - id properties: id: type: - string description: Source identifier. Preserve its exact string value; do not convert large IDs to numbers. minLength: 1 - required: - handle properties: handle: type: - string description: Public account username. minLength: 1 - required: - name properties: name: type: - string description: Display name. minLength: 1 - required: - url properties: url: type: - string description: Original source URL when supplied. minLength: 1 - required: - bio properties: bio: type: - string description: Public biography. minLength: 1 - required: - bio_link properties: bio_link: type: - string description: Original source URL when supplied. minLength: 1 - required: - avatar_url properties: avatar_url: type: - string description: Original source URL when supplied. minLength: 1 - required: - followers properties: followers: type: - number description: Followers reported by the source; null or absent is unknown, not zero. - required: - following properties: following: type: - number description: Following reported by the source; null or absent is unknown, not zero. - required: - verified properties: verified: type: - boolean description: Source verification flag; meaning depends on the platform. - required: - likes_count properties: likes_count: type: - number description: Account likes reported by the source; null or absent is unknown, not zero. - required: - video_count properties: video_count: type: - number description: Videos reported by the source; null or absent is unknown, not zero. - required: - commerce_user properties: commerce_user: type: - boolean description: Commerce-account flag; not a business category. - required: - seller properties: seller: type: - boolean description: Seller flag. - required: - region properties: region: type: - string description: Account region supplied by TikTok; not personal residence. minLength: 1 - required: - business_category properties: business_category: type: - string description: Public source category. minLength: 1 x-contract-version: '2026-09-22' x-validation-scope: Required success payload structure; optional fields and source completeness remain separate. examples: - id: '7350000000000000001' handle: example_creator name: Example Creator followers: 12000 following: 180 bio: null verified: false default: description: The error envelope — the same shape for every non-2xx status. content: application/json: schema: $ref: '#/components/schemas/Error' x-credits: 1 x-production-available: true x-capacity: status: not_assessed message: Capacity is workload-dependent; configured routes do not establish sustained throughput or an availability guarantee. x-availability-scope: Structural check of the effective registered chain, production permission, adapter, configured cost and quality floor without request parameters. True is not a live-health, credential, quota, subscription-entitlement, complete-data or deployment-exposure guarantee. False means no structurally eligible candidate; null means metadata could not establish availability. Composite child capability still depends on its component routes. x-live-proven: true /v1/tiktok/profile-region: get: operationId: tiktok_profile_region tags: - tiktok summary: TikTok account region description: The region an account posts from, resolved from the account itself rather than guessed from its content. Costs 2 credits per successful live response. parameters: - name: handle in: query required: true schema: type: string example: nasa description: TikTok username without the @ An optional leading @ is accepted and removed before lookup. - name: dry_run in: query required: false schema: type: string enum: - '1' - '0' - 'true' - 'false' example: '1' description: 'Read a zero-credit estimate without fetching sources, running AI, or reserving credits. Cache status is a snapshot, not a guarantee at execution. Accepted values: 1, 0, true, false. Case, spaces, hyphens and underscores are interchangeable.' - name: judgments in: query required: false schema: type: string enum: - 'on' - 'off' example: 'on' description: 'Add bounded AI labels to eligible returned records (default on). off preserves the original data shape. Unclassified records remain present; labels depend on evidence, time, capacity and the existing request budget. No label surcharge. Accepted values: on, off. Case, spaces, hyphens and underscores are interchangeable.' - name: label in: query required: false schema: type: string enum: - default - none example: none description: 'Set none to disable labels; default enables the endpoint’s label set. Equivalent to judgments=off. Accepted values: default, none. Case, spaces, hyphens and underscores are interchangeable.' - name: label_evidence in: query required: false schema: type: string enum: - '1' - '0' - 'true' - 'false' example: '1' description: 'Include exact supporting sentences and zero-based sentence indexes when a label has validated evidence. No extra charge or change to decisions. Accepted values: 1, 0, true, false. Case, spaces, hyphens and underscores are interchangeable.' - name: exclude in: query required: false schema: type: string enum: - engagement_bait example: engagement_bait description: 'Optionally remove confidently labelled engagement bait. Uncertain and unclassified records stay; removed IDs and an owner-bound recall reference are returned. Accepted values: engagement_bait. Case, spaces, hyphens and underscores are interchangeable.' - name: fit in: query required: false schema: type: string enum: - goal example: goal description: 'Use goal to replace confidently irrelevant records with recall stubs. Keeps first, last, relevant and uncertain records; preserves order. Full evidence is stored for 24 hours when available. Accepted values: goal. Case, spaces, hyphens and underscores are interchangeable.' - name: goal in: query required: false schema: type: string example: Find concrete product complaints description: 'Required with fit=goal: describe the task in at most 600 characters. Supplied text is task context, never permission to act on posts.' - name: tokens in: query required: false schema: type: string example: '4000' description: Optional soft response target for fit=goal, 256–32000. Safety and evidence retention take priority, so the returned result may exceed it. - name: X-Max-Credits in: header required: false schema: type: integer minimum: 0 maximum: 9007199254740991 example: 5 description: Optional credit reservation ceiling for this individual request. Send a non-negative integer in decimal digits. Live execution checks the required reservation after resolving free cache hits or buffered continuation, before charging or calling a supplier. A higher reservation returns HTTP 422 INVALID_PARAMETERS with reason max_credits_exceeded and charges nothing. Invalid header values also return 422. Zero permits only a zero-credit reservation; omitting the header uses normal pricing. dry_run remains a free preview. This does not cap later requests, batches or scheduled runs. security: - ApiKeyHeader: [] - BearerKey: [] responses: '200': description: 'The common success envelope; `data` is endpoint-specific. Many lists use items/count/cursor; bundles use named collections and their documented continuation metadata. HTTP 200 can contain a partial bundle: inspect complete, partial and legs where supplied.' content: application/json: schema: allOf: - $ref: '#/components/schemas/Success' - type: object properties: data: $schema: https://json-schema.org/draft/2020-12/schema $id: https://www.monocrawl.com/schemas/tiktok/profile-region.json title: tiktok/profile-region data fields description: Optional data supplied by this operation. Null means unknown. type: object properties: handle: description: Optional handle supplied by this operation. Null means unknown. type: - string - 'null' platform: description: Optional platform supplied by this operation. Null means unknown. type: - string - 'null' region: description: Optional region supplied by this operation. Null means unknown. type: - string - 'null' url: description: Original source URL when supplied. type: - string - 'null' additionalProperties: true allOf: - anyOf: - required: - handle properties: handle: description: Optional handle supplied by this operation. Null means unknown. type: - string minLength: 1 - required: - region properties: region: description: Optional region supplied by this operation. Null means unknown. type: - string minLength: 1 - required: - url properties: url: description: Original source URL when supplied. type: - string minLength: 1 x-contract-version: '2026-09-22' x-validation-scope: Required success payload structure; optional fields and source completeness remain separate. examples: - handle: example platform: example region: example url: https://example.com/example default: description: The error envelope — the same shape for every non-2xx status. content: application/json: schema: $ref: '#/components/schemas/Error' x-credits: 2 x-production-available: true x-capacity: status: not_assessed message: Capacity is workload-dependent; configured routes do not establish sustained throughput or an availability guarantee. x-availability-scope: Structural check of the effective registered chain, production permission, adapter, configured cost and quality floor without request parameters. True is not a live-health, credential, quota, subscription-entitlement, complete-data or deployment-exposure guarantee. False means no structurally eligible candidate; null means metadata could not establish availability. Composite child capability still depends on its component routes. x-live-proven: true /v1/tiktok/profile-videos: get: operationId: tiktok_profile_videos tags: - tiktok summary: Profile videos description: Recent videos for a TikTok account, newest first, with per-video stats. Paged by cursor. Costs 1 credit per successful live response. parameters: - name: handle in: query required: true schema: type: string example: nasa description: TikTok username without the @. An optional leading @ is accepted and removed before lookup. - name: cursor in: query required: false schema: type: string description: Opaque cursor from the previous page. - name: user_id in: query required: false schema: type: string example: '6659752019493208069' description: Numeric TikTok user id, kept as a string. Optional alongside the required handle; can speed up the primary source. This is not a sec_uid. - name: sort_by in: query required: false schema: type: string enum: - latest - popular example: latest description: 'latest (newest first, the default) or popular. latest is served by every source; popular is served by the source that can rank by popularity, so a continuation stays on that source. Accepted values: latest, popular. Case, spaces, hyphens and underscores are interchangeable.' - name: region in: query required: false schema: type: string example: GB description: Two-letter country code for the source request location. It can affect availability and ranking; it does not filter creators by residence or audience country. Keep it unchanged when continuing. - name: max_cursor in: query required: false schema: type: string example: '1734562353000' description: Primary-source alias for cursor. Use the previous response cursor unchanged. The canonical cursor parameter takes precedence when both are supplied. - name: trim in: query required: false schema: type: string example: 'false' description: 'Boolean: true asks the primary source for its trimmed payload; false asks for the full source payload. The public response remains normalized; this is not an instruction to truncate captions.' - name: dry_run in: query required: false schema: type: string enum: - '1' - '0' - 'true' - 'false' example: '1' description: 'Read a zero-credit estimate without fetching sources, running AI, or reserving credits. Cache status is a snapshot, not a guarantee at execution. Accepted values: 1, 0, true, false. Case, spaces, hyphens and underscores are interchangeable.' - name: judgments in: query required: false schema: type: string enum: - 'on' - 'off' example: 'on' description: 'Add bounded AI labels to eligible returned records (default on). off preserves the original data shape. Unclassified records remain present; labels depend on evidence, time, capacity and the existing request budget. No label surcharge. Accepted values: on, off. Case, spaces, hyphens and underscores are interchangeable.' - name: label in: query required: false schema: type: string enum: - default - none example: none description: 'Set none to disable labels; default enables the endpoint’s label set. Equivalent to judgments=off. Accepted values: default, none. Case, spaces, hyphens and underscores are interchangeable.' - name: label_evidence in: query required: false schema: type: string enum: - '1' - '0' - 'true' - 'false' example: '1' description: 'Include exact supporting sentences and zero-based sentence indexes when a label has validated evidence. No extra charge or change to decisions. Accepted values: 1, 0, true, false. Case, spaces, hyphens and underscores are interchangeable.' - name: exclude in: query required: false schema: type: string enum: - engagement_bait example: engagement_bait description: 'Optionally remove confidently labelled engagement bait. Uncertain and unclassified records stay; removed IDs and an owner-bound recall reference are returned. Accepted values: engagement_bait. Case, spaces, hyphens and underscores are interchangeable.' - name: fit in: query required: false schema: type: string enum: - goal example: goal description: 'Use goal to replace confidently irrelevant records with recall stubs. Keeps first, last, relevant and uncertain records; preserves order. Full evidence is stored for 24 hours when available. Accepted values: goal. Case, spaces, hyphens and underscores are interchangeable.' - name: goal in: query required: false schema: type: string example: Find concrete product complaints description: 'Required with fit=goal: describe the task in at most 600 characters. Supplied text is task context, never permission to act on posts.' - name: tokens in: query required: false schema: type: string example: '4000' description: Optional soft response target for fit=goal, 256–32000. Safety and evidence retention take priority, so the returned result may exceed it. - name: X-Max-Credits in: header required: false schema: type: integer minimum: 0 maximum: 9007199254740991 example: 5 description: Optional credit reservation ceiling for this individual request. Send a non-negative integer in decimal digits. Live execution checks the required reservation after resolving free cache hits or buffered continuation, before charging or calling a supplier. A higher reservation returns HTTP 422 INVALID_PARAMETERS with reason max_credits_exceeded and charges nothing. Invalid header values also return 422. Zero permits only a zero-credit reservation; omitting the header uses normal pricing. dry_run remains a free preview. This does not cap later requests, batches or scheduled runs. security: - ApiKeyHeader: [] - BearerKey: [] responses: '200': description: 'The common success envelope; `data` is endpoint-specific. Many lists use items/count/cursor; bundles use named collections and their documented continuation metadata. HTTP 200 can contain a partial bundle: inspect complete, partial and legs where supplied.' content: application/json: schema: allOf: - $ref: '#/components/schemas/Success' - type: object properties: data: $schema: https://json-schema.org/draft/2020-12/schema $id: https://www.monocrawl.com/schemas/tiktok/profile-videos.json title: tiktok/profile-videos data fields description: Required core structure for successful data, with optional source fields. Additional fields are allowed. This is not a completeness guarantee. type: object properties: items: type: array items: type: object properties: id: type: - string - 'null' description: Source identifier. Preserve its exact string value; do not convert large IDs to numbers. url: type: - string - 'null' description: Original source URL when supplied. caption: type: - string - 'null' description: Video caption; spoken words require a transcript request. created_at: type: - string - 'null' description: Source publication time, normalized to an ISO date-time when available. duration_s: type: - number - 'null' description: Video duration in seconds. region: type: - string - 'null' description: Source-reported content region, not audience geography or proof of residence. author: type: object properties: id: type: - string - 'null' description: Source identifier. Preserve its exact string value; do not convert large IDs to numbers. handle: type: - string - 'null' description: Public account username. name: type: - string - 'null' description: Display name. url: type: - string - 'null' description: Original source URL when supplied. followers: type: - number - 'null' description: Follower count supplied with this video; null when absent. No profile-enrichment call is made. region: type: - string - 'null' description: Source-reported account region, not audience geography or proof of residence. avatar_url: type: - string - 'null' description: Original source URL when supplied. verified: type: - boolean - 'null' description: Explicit source verification flag; precise search may omit it. additionalProperties: true stats: type: object properties: plays: type: - number - 'null' description: plays reported by the source; null or absent is unknown, not zero. likes: type: - number - 'null' description: likes reported by the source; null or absent is unknown, not zero. comments: type: - number - 'null' description: comments reported by the source; null or absent is unknown, not zero. shares: type: - number - 'null' description: shares reported by the source; null or absent is unknown, not zero. saves: type: - number - 'null' description: saves reported by the source; null or absent is unknown, not zero. additionalProperties: true music: type: - object - 'null' properties: id: type: - string - 'null' description: Source identifier. Preserve its exact string value; do not convert large IDs to numbers. title: type: - string - 'null' description: Source sound title. author: type: - string - 'null' description: Source sound author. duration_s: type: - number - 'null' description: Source sound duration in seconds. is_original: type: - boolean - 'null' description: Explicit source original-sound flag. play_url: type: - string - 'null' description: Original source URL when supplied. cover_url: type: - string - 'null' description: Original source URL when supplied. additionalProperties: true additionalProperties: true allOf: - anyOf: - required: - id properties: id: type: - string description: Source identifier. Preserve its exact string value; do not convert large IDs to numbers. minLength: 1 - required: - url properties: url: type: - string description: Original source URL when supplied. minLength: 1 - required: - caption properties: caption: type: - string description: Video caption; spoken words require a transcript request. minLength: 1 - required: - created_at properties: created_at: type: - string description: Source publication time, normalized to an ISO date-time when available. minLength: 1 - required: - duration_s properties: duration_s: type: - number description: Video duration in seconds. - required: - region properties: region: type: - string description: Source-reported content region, not audience geography or proof of residence. minLength: 1 - required: - author properties: author: type: object properties: id: type: - string - 'null' description: Source identifier. Preserve its exact string value; do not convert large IDs to numbers. handle: type: - string - 'null' description: Public account username. name: type: - string - 'null' description: Display name. url: type: - string - 'null' description: Original source URL when supplied. followers: type: - number - 'null' description: Follower count supplied with this video; null when absent. No profile-enrichment call is made. region: type: - string - 'null' description: Source-reported account region, not audience geography or proof of residence. avatar_url: type: - string - 'null' description: Original source URL when supplied. verified: type: - boolean - 'null' description: Explicit source verification flag; precise search may omit it. additionalProperties: true - required: - stats properties: stats: type: object properties: plays: type: - number - 'null' description: plays reported by the source; null or absent is unknown, not zero. likes: type: - number - 'null' description: likes reported by the source; null or absent is unknown, not zero. comments: type: - number - 'null' description: comments reported by the source; null or absent is unknown, not zero. shares: type: - number - 'null' description: shares reported by the source; null or absent is unknown, not zero. saves: type: - number - 'null' description: saves reported by the source; null or absent is unknown, not zero. additionalProperties: true - required: - music properties: music: type: - object properties: id: type: - string - 'null' description: Source identifier. Preserve its exact string value; do not convert large IDs to numbers. title: type: - string - 'null' description: Source sound title. author: type: - string - 'null' description: Source sound author. duration_s: type: - number - 'null' description: Source sound duration in seconds. is_original: type: - boolean - 'null' description: Explicit source original-sound flag. play_url: type: - string - 'null' description: Original source URL when supplied. cover_url: type: - string - 'null' description: Original source URL when supplied. additionalProperties: true description: Records in this response page. count: type: - number - 'null' description: Returned row count when supplied; not the full source total. cursor: type: - string - 'null' description: Opaque next-page token. A missing token does not prove full history was retrieved. has_more: type: - boolean - 'null' description: Source continuation indicator; null means unknown. _warnings: type: array items: type: string description: Collection limitations or component warnings. Read before interpreting coverage. additionalProperties: true required: - items x-contract-version: '2026-09-22' x-validation-scope: Required success payload structure; optional fields and source completeness remain separate. examples: - items: - id: '7350000000000000002' url: https://www.tiktok.com/@example_creator/video/7350000000000000002 caption: A desk setup created_at: '2026-09-01T12:00:00.000Z' duration_s: 15 stats: plays: 1200 likes: 100 comments: 12 shares: null saves: 8 cursor: null has_more: null default: description: The error envelope — the same shape for every non-2xx status. content: application/json: schema: $ref: '#/components/schemas/Error' x-credits: 1 x-production-available: true x-capacity: status: not_assessed message: Capacity is workload-dependent; configured routes do not establish sustained throughput or an availability guarantee. x-availability-scope: Structural check of the effective registered chain, production permission, adapter, configured cost and quality floor without request parameters. True is not a live-health, credential, quota, subscription-entitlement, complete-data or deployment-exposure guarantee. False means no structurally eligible candidate; null means metadata could not establish availability. Composite child capability still depends on its component routes. x-live-proven: true /v1/tiktok/profile/full: get: operationId: tiktok_profile_full tags: - tiktok summary: TikTok profile with posts (one page) description: 'A real public profile plus one page of posts/videos, preserving original normalized component fields and source order. HTTP 200 may be partial: inspect complete, partial and legs. Failed profile: no posts requested, zero charge. Failed posts: profile retained and only that successful component charged. Cached components use the public cache-hit price. Computed fields summarize the returned page, including available engagement averages and observed posting frequency. Missing metrics remain unknown. Costs 2 credits per successful live response.' parameters: - name: handle in: query required: true schema: type: string example: mrbeast description: Public profile identifier. LinkedIn accepts /company/name or /in/name URLs. An optional leading @ is accepted and removed before lookup. - name: posts in: query required: false schema: type: string example: '25' description: Desired page size, 1-100. Existing components choose their own page size; the entire single source page is preserved, even if longer or shorter, so no records are skipped between cursors. No automatic extra pages. - name: cursor in: query required: false schema: type: string description: Opaque posts_cursor from the previous response; use posts_pagination.next_params to retain all required context. Unsupported component continuation is refused before calls. - name: include in: query required: false schema: type: string example: posts,computed description: 'CSV: posts and/or computed (default both), or profile alone. Profile is always returned. Computed is arithmetic over this page only, not an AI summary.' - name: user_id in: query required: false schema: type: string description: Exact numeric string, optional alongside handle; numeric ID-only profile lookup is not supported. - name: sort_by in: query required: false schema: type: string enum: - latest - popular example: latest description: 'latest or popular, forwarded to the videos component. Accepted values: latest, popular. Case, spaces, hyphens and underscores are interchangeable.' - name: region in: query required: false schema: type: string example: GB description: Two-letter source region, forwarded unchanged. - name: trim in: query required: false schema: type: string example: 'false' description: Source trimming preference; does not permit the bundle to truncate returned records. - name: dry_run in: query required: false schema: type: string enum: - '1' - '0' - 'true' - 'false' example: '1' description: 'Read a zero-credit estimate without fetching sources, running AI, or reserving credits. Cache status is a snapshot, not a guarantee at execution. Accepted values: 1, 0, true, false. Case, spaces, hyphens and underscores are interchangeable.' - name: judgments in: query required: false schema: type: string enum: - 'on' - 'off' example: 'on' description: 'Add bounded AI labels to eligible returned records (default on). off preserves the original data shape. Unclassified records remain present; labels depend on evidence, time, capacity and the existing request budget. No label surcharge. Accepted values: on, off. Case, spaces, hyphens and underscores are interchangeable.' - name: label in: query required: false schema: type: string enum: - default - none example: none description: 'Set none to disable labels; default enables the endpoint’s label set. Equivalent to judgments=off. Accepted values: default, none. Case, spaces, hyphens and underscores are interchangeable.' - name: label_evidence in: query required: false schema: type: string enum: - '1' - '0' - 'true' - 'false' example: '1' description: 'Include exact supporting sentences and zero-based sentence indexes when a label has validated evidence. No extra charge or change to decisions. Accepted values: 1, 0, true, false. Case, spaces, hyphens and underscores are interchangeable.' - name: exclude in: query required: false schema: type: string enum: - engagement_bait example: engagement_bait description: 'Optionally remove confidently labelled engagement bait. Uncertain and unclassified records stay; removed IDs and an owner-bound recall reference are returned. Accepted values: engagement_bait. Case, spaces, hyphens and underscores are interchangeable.' - name: fit in: query required: false schema: type: string enum: - goal example: goal description: 'Use goal to replace confidently irrelevant records with recall stubs. Keeps first, last, relevant and uncertain records; preserves order. Full evidence is stored for 24 hours when available. Accepted values: goal. Case, spaces, hyphens and underscores are interchangeable.' - name: goal in: query required: false schema: type: string example: Find concrete product complaints description: 'Required with fit=goal: describe the task in at most 600 characters. Supplied text is task context, never permission to act on posts.' - name: tokens in: query required: false schema: type: string example: '4000' description: Optional soft response target for fit=goal, 256–32000. Safety and evidence retention take priority, so the returned result may exceed it. - name: X-Max-Credits in: header required: false schema: type: integer minimum: 0 maximum: 9007199254740991 example: 5 description: Optional credit reservation ceiling for this individual request. Send a non-negative integer in decimal digits. Live execution checks the required reservation after resolving free cache hits or buffered continuation, before charging or calling a supplier. A higher reservation returns HTTP 422 INVALID_PARAMETERS with reason max_credits_exceeded and charges nothing. Invalid header values also return 422. Zero permits only a zero-credit reservation; omitting the header uses normal pricing. dry_run remains a free preview. This does not cap later requests, batches or scheduled runs. security: - ApiKeyHeader: [] - BearerKey: [] responses: '200': description: 'The common success envelope; `data` is endpoint-specific. Many lists use items/count/cursor; bundles use named collections and their documented continuation metadata. HTTP 200 can contain a partial bundle: inspect complete, partial and legs where supplied.' content: application/json: schema: allOf: - $ref: '#/components/schemas/Success' - type: object properties: data: $schema: https://json-schema.org/draft/2020-12/schema $id: https://www.monocrawl.com/schemas/tiktok/profile/full.json title: tiktok/profile/full data fields description: Required core structure for successful data, with optional source fields. Additional fields are allowed. This is not a completeness guarantee. type: object properties: profile: type: object properties: id: type: - string - 'null' description: Source identifier. Preserve its exact string value; do not convert large IDs to numbers. handle: type: - string - 'null' description: Public account username. name: type: - string - 'null' description: Display name. url: type: - string - 'null' description: Original source URL when supplied. bio: type: - string - 'null' description: Public biography. bio_link: type: - string - 'null' description: Original source URL when supplied. avatar_url: type: - string - 'null' description: Original source URL when supplied. followers: type: - number - 'null' description: Followers reported by the source; null or absent is unknown, not zero. following: type: - number - 'null' description: Following reported by the source; null or absent is unknown, not zero. verified: type: - boolean - 'null' description: Source verification flag; meaning depends on the platform. likes_count: type: - number - 'null' description: Account likes reported by the source; null or absent is unknown, not zero. video_count: type: - number - 'null' description: Videos reported by the source; null or absent is unknown, not zero. commerce_user: type: - boolean - 'null' description: Commerce-account flag; not a business category. seller: type: - boolean - 'null' description: Seller flag. region: type: - string - 'null' description: Account region supplied by TikTok; not personal residence. business_category: type: - string - 'null' description: Public source category. additionalProperties: true posts: type: - array - 'null' items: type: object properties: id: type: - string - 'null' description: Source identifier. Preserve its exact string value; do not convert large IDs to numbers. url: type: - string - 'null' description: Original source URL when supplied. caption: type: - string - 'null' description: Video caption; spoken words require a transcript request. created_at: type: - string - 'null' description: Source publication time, normalized to an ISO date-time when available. duration_s: type: - number - 'null' description: Video duration in seconds. region: type: - string - 'null' description: Source-reported content region, not audience geography or proof of residence. author: type: object properties: id: type: - string - 'null' description: Source identifier. Preserve its exact string value; do not convert large IDs to numbers. handle: type: - string - 'null' description: Public account username. name: type: - string - 'null' description: Display name. url: type: - string - 'null' description: Original source URL when supplied. followers: type: - number - 'null' description: Follower count supplied with this video; null when absent. No profile-enrichment call is made. region: type: - string - 'null' description: Source-reported account region, not audience geography or proof of residence. avatar_url: type: - string - 'null' description: Original source URL when supplied. verified: type: - boolean - 'null' description: Explicit source verification flag; precise search may omit it. additionalProperties: true stats: type: object properties: plays: type: - number - 'null' description: plays reported by the source; null or absent is unknown, not zero. likes: type: - number - 'null' description: likes reported by the source; null or absent is unknown, not zero. comments: type: - number - 'null' description: comments reported by the source; null or absent is unknown, not zero. shares: type: - number - 'null' description: shares reported by the source; null or absent is unknown, not zero. saves: type: - number - 'null' description: saves reported by the source; null or absent is unknown, not zero. additionalProperties: true music: type: - object - 'null' properties: id: type: - string - 'null' description: Source identifier. Preserve its exact string value; do not convert large IDs to numbers. title: type: - string - 'null' description: Source sound title. author: type: - string - 'null' description: Source sound author. duration_s: type: - number - 'null' description: Source sound duration in seconds. is_original: type: - boolean - 'null' description: Explicit source original-sound flag. play_url: type: - string - 'null' description: Original source URL when supplied. cover_url: type: - string - 'null' description: Original source URL when supplied. additionalProperties: true additionalProperties: true computed: type: - object - 'null' properties: sample_size: type: - number - 'null' description: Returned rows reported by the source; null or absent is unknown, not zero. metric_samples: type: object properties: likes: type: - number - 'null' description: Number of usable numeric observations for likes; each metric uses its own available sample. comments: type: - number - 'null' description: Number of usable numeric observations for comments; each metric uses its own available sample. shares: type: - number - 'null' description: Number of usable numeric observations for shares; each metric uses its own available sample. views: type: - number - 'null' description: Number of usable numeric observations for views; each metric uses its own available sample. additionalProperties: true averages: type: object properties: likes: type: - number - 'null' description: Arithmetic mean for likes; each metric uses its own available sample. comments: type: - number - 'null' description: Arithmetic mean for comments; each metric uses its own available sample. shares: type: - number - 'null' description: Arithmetic mean for shares; each metric uses its own available sample. views: type: - number - 'null' description: Arithmetic mean for views; each metric uses its own available sample. additionalProperties: true posting_window: type: object properties: posts_with_timestamps: type: - number - 'null' description: Rows with usable timestamps reported by the source; null or absent is unknown, not zero. start: type: - string - 'null' description: Source publication time, normalized to an ISO date-time when available. end: type: - string - 'null' description: Source publication time, normalized to an ISO date-time when available. days: type: - number - 'null' description: Elapsed days between earliest and latest valid timestamps; null with fewer than two dates. additionalProperties: true observed_posts_per_day: type: - number - 'null' description: (posts_with_timestamps - 1) / days; null unless days is positive. This describes the returned page only. additionalProperties: true complete: type: - boolean - 'null' description: All requested components succeeded; not a full-history guarantee. partial: type: - boolean - 'null' description: One or more requested components failed. legs: type: array items: type: object properties: component: type: - string - 'null' description: Component name. endpoint: type: - string - 'null' description: Component route. ok: type: - boolean - 'null' description: Whether usable component data was returned. status: type: - number - 'null' description: Component HTTP status. credits: type: - number - 'null' description: Confirmed component charge. error: type: - string - 'null' description: Public component failure description. additionalProperties: true posts_cursor: type: - string - 'null' description: Returned posts continuation, if available. posts_pagination: type: object properties: requested: type: - number - 'null' description: Desired rows reported by the source; null or absent is unknown, not zero. returned: type: - number - 'null' description: Returned rows reported by the source; null or absent is unknown, not zero. total: type: - number - 'null' description: Source total reported by the source; null or absent is unknown, not zero. has_more: type: - boolean - 'null' description: Source continuation indicator. next_params: type: - object - 'null' properties: handle: type: - string - 'null' description: Account handle. cursor: type: - string - 'null' description: Opaque cursor; pass every supplied next parameter together. additionalProperties: true additionalProperties: true _warnings: type: array items: type: string description: Collection limitations or component warnings. Read before interpreting coverage. additionalProperties: true allOf: - anyOf: - required: - profile properties: profile: type: object properties: id: type: - string - 'null' description: Source identifier. Preserve its exact string value; do not convert large IDs to numbers. handle: type: - string - 'null' description: Public account username. name: type: - string - 'null' description: Display name. url: type: - string - 'null' description: Original source URL when supplied. bio: type: - string - 'null' description: Public biography. bio_link: type: - string - 'null' description: Original source URL when supplied. avatar_url: type: - string - 'null' description: Original source URL when supplied. followers: type: - number - 'null' description: Followers reported by the source; null or absent is unknown, not zero. following: type: - number - 'null' description: Following reported by the source; null or absent is unknown, not zero. verified: type: - boolean - 'null' description: Source verification flag; meaning depends on the platform. likes_count: type: - number - 'null' description: Account likes reported by the source; null or absent is unknown, not zero. video_count: type: - number - 'null' description: Videos reported by the source; null or absent is unknown, not zero. commerce_user: type: - boolean - 'null' description: Commerce-account flag; not a business category. seller: type: - boolean - 'null' description: Seller flag. region: type: - string - 'null' description: Account region supplied by TikTok; not personal residence. business_category: type: - string - 'null' description: Public source category. additionalProperties: true - required: - posts properties: posts: type: - array items: type: object properties: id: type: - string - 'null' description: Source identifier. Preserve its exact string value; do not convert large IDs to numbers. url: type: - string - 'null' description: Original source URL when supplied. caption: type: - string - 'null' description: Video caption; spoken words require a transcript request. created_at: type: - string - 'null' description: Source publication time, normalized to an ISO date-time when available. duration_s: type: - number - 'null' description: Video duration in seconds. region: type: - string - 'null' description: Source-reported content region, not audience geography or proof of residence. author: type: object properties: id: type: - string - 'null' description: Source identifier. Preserve its exact string value; do not convert large IDs to numbers. handle: type: - string - 'null' description: Public account username. name: type: - string - 'null' description: Display name. url: type: - string - 'null' description: Original source URL when supplied. followers: type: - number - 'null' description: Follower count supplied with this video; null when absent. No profile-enrichment call is made. region: type: - string - 'null' description: Source-reported account region, not audience geography or proof of residence. avatar_url: type: - string - 'null' description: Original source URL when supplied. verified: type: - boolean - 'null' description: Explicit source verification flag; precise search may omit it. additionalProperties: true stats: type: object properties: plays: type: - number - 'null' description: plays reported by the source; null or absent is unknown, not zero. likes: type: - number - 'null' description: likes reported by the source; null or absent is unknown, not zero. comments: type: - number - 'null' description: comments reported by the source; null or absent is unknown, not zero. shares: type: - number - 'null' description: shares reported by the source; null or absent is unknown, not zero. saves: type: - number - 'null' description: saves reported by the source; null or absent is unknown, not zero. additionalProperties: true music: type: - object - 'null' properties: id: type: - string - 'null' description: Source identifier. Preserve its exact string value; do not convert large IDs to numbers. title: type: - string - 'null' description: Source sound title. author: type: - string - 'null' description: Source sound author. duration_s: type: - number - 'null' description: Source sound duration in seconds. is_original: type: - boolean - 'null' description: Explicit source original-sound flag. play_url: type: - string - 'null' description: Original source URL when supplied. cover_url: type: - string - 'null' description: Original source URL when supplied. additionalProperties: true additionalProperties: true - required: - computed properties: computed: type: - object properties: sample_size: type: - number - 'null' description: Returned rows reported by the source; null or absent is unknown, not zero. metric_samples: type: object properties: likes: type: - number - 'null' description: Number of usable numeric observations for likes; each metric uses its own available sample. comments: type: - number - 'null' description: Number of usable numeric observations for comments; each metric uses its own available sample. shares: type: - number - 'null' description: Number of usable numeric observations for shares; each metric uses its own available sample. views: type: - number - 'null' description: Number of usable numeric observations for views; each metric uses its own available sample. additionalProperties: true averages: type: object properties: likes: type: - number - 'null' description: Arithmetic mean for likes; each metric uses its own available sample. comments: type: - number - 'null' description: Arithmetic mean for comments; each metric uses its own available sample. shares: type: - number - 'null' description: Arithmetic mean for shares; each metric uses its own available sample. views: type: - number - 'null' description: Arithmetic mean for views; each metric uses its own available sample. additionalProperties: true posting_window: type: object properties: posts_with_timestamps: type: - number - 'null' description: Rows with usable timestamps reported by the source; null or absent is unknown, not zero. start: type: - string - 'null' description: Source publication time, normalized to an ISO date-time when available. end: type: - string - 'null' description: Source publication time, normalized to an ISO date-time when available. days: type: - number - 'null' description: Elapsed days between earliest and latest valid timestamps; null with fewer than two dates. additionalProperties: true observed_posts_per_day: type: - number - 'null' description: (posts_with_timestamps - 1) / days; null unless days is positive. This describes the returned page only. additionalProperties: true - required: - legs properties: legs: type: array items: type: object properties: component: type: - string - 'null' description: Component name. endpoint: type: - string - 'null' description: Component route. ok: type: - boolean - 'null' description: Whether usable component data was returned. status: type: - number - 'null' description: Component HTTP status. credits: type: - number - 'null' description: Confirmed component charge. error: type: - string - 'null' description: Public component failure description. additionalProperties: true - required: - posts_cursor properties: posts_cursor: type: - string description: Returned posts continuation, if available. minLength: 1 - required: - posts_pagination properties: posts_pagination: type: object properties: requested: type: - number - 'null' description: Desired rows reported by the source; null or absent is unknown, not zero. returned: type: - number - 'null' description: Returned rows reported by the source; null or absent is unknown, not zero. total: type: - number - 'null' description: Source total reported by the source; null or absent is unknown, not zero. has_more: type: - boolean - 'null' description: Source continuation indicator. next_params: type: - object - 'null' properties: handle: type: - string - 'null' description: Account handle. cursor: type: - string - 'null' description: Opaque cursor; pass every supplied next parameter together. additionalProperties: true additionalProperties: true x-contract-version: '2026-09-22' x-validation-scope: Required success payload structure; optional fields and source completeness remain separate. examples: - profile: id: '7350000000000000001' handle: example_creator name: Example Creator followers: 12000 following: 180 bio: null verified: false posts: - id: '7350000000000000002' url: https://www.tiktok.com/@example_creator/video/7350000000000000002 caption: A desk setup created_at: '2026-09-01T12:00:00.000Z' duration_s: 15 stats: plays: 1200 likes: 100 comments: 12 shares: null saves: 8 complete: true partial: false posts_cursor: null posts_pagination: returned: 1 has_more: null next_params: null default: description: The error envelope — the same shape for every non-2xx status. content: application/json: schema: $ref: '#/components/schemas/Error' x-credits: 2 x-production-available: true x-capacity: status: not_assessed message: Capacity is workload-dependent; configured routes do not establish sustained throughput or an availability guarantee. x-availability-scope: Structural check of the effective registered chain, production permission, adapter, configured cost and quality floor without request parameters. True is not a live-health, credential, quota, subscription-entitlement, complete-data or deployment-exposure guarantee. False means no structurally eligible candidate; null means metadata could not establish availability. Composite child capability still depends on its component routes. x-live-proven: true /v1/tiktok/search: get: operationId: tiktok_search tags: - tiktok summary: Video search description: Search TikTok videos by keyword, newest-relevant first, with per-video engagement counts. Paged by cursor. Costs 2 credits per successful live response. parameters: - name: query in: query required: true schema: type: string example: coffee brewing description: Search term. - name: cursor in: query required: false schema: type: string description: Opaque cursor from the previous page. - name: region in: query required: false schema: type: string example: US description: Two-letter country code for the source request location. It can affect availability and ranking; it does not filter creators by residence or audience country. Keep it unchanged when continuing. - name: sort_by in: query required: false schema: type: string enum: - relevance - most_liked - latest - date_posted description: 'relevance (default) or most-liked. Accepted values: relevance, most_liked, latest, date_posted. Case, spaces, hyphens and underscores are interchangeable.' - name: date_posted in: query required: false schema: type: string enum: - all - all_time - yesterday - past_day - this_week - past_week - this_month - past_month - last_3_months - past_3_months - last_6_months - past_6_months x-value-aliases: last-day: yesterday last-week: this_week last-month: this_month description: 'Restrict by post date, e.g. past-week. Accepted values: all, all_time, yesterday, past_day, this_week, past_week, this_month, past_month, last_3_months, past_3_months, last_6_months, past_6_months. Case, spaces, hyphens and underscores are interchangeable.' - name: dry_run in: query required: false schema: type: string enum: - '1' - '0' - 'true' - 'false' example: '1' description: 'Read a zero-credit estimate without fetching sources, running AI, or reserving credits. Cache status is a snapshot, not a guarantee at execution. Accepted values: 1, 0, true, false. Case, spaces, hyphens and underscores are interchangeable.' - name: judgments in: query required: false schema: type: string enum: - 'on' - 'off' example: 'on' description: 'Add bounded AI labels to eligible returned records (default on). off preserves the original data shape. Unclassified records remain present; labels depend on evidence, time, capacity and the existing request budget. No label surcharge. Accepted values: on, off. Case, spaces, hyphens and underscores are interchangeable.' - name: label in: query required: false schema: type: string enum: - default - none example: none description: 'Set none to disable labels; default enables the endpoint’s label set. Equivalent to judgments=off. Accepted values: default, none. Case, spaces, hyphens and underscores are interchangeable.' - name: label_evidence in: query required: false schema: type: string enum: - '1' - '0' - 'true' - 'false' example: '1' description: 'Include exact supporting sentences and zero-based sentence indexes when a label has validated evidence. No extra charge or change to decisions. Accepted values: 1, 0, true, false. Case, spaces, hyphens and underscores are interchangeable.' - name: exclude in: query required: false schema: type: string enum: - engagement_bait example: engagement_bait description: 'Optionally remove confidently labelled engagement bait. Uncertain and unclassified records stay; removed IDs and an owner-bound recall reference are returned. Accepted values: engagement_bait. Case, spaces, hyphens and underscores are interchangeable.' - name: fit in: query required: false schema: type: string enum: - goal example: goal description: 'Use goal to replace confidently irrelevant records with recall stubs. Keeps first, last, relevant and uncertain records; preserves order. Full evidence is stored for 24 hours when available. Accepted values: goal. Case, spaces, hyphens and underscores are interchangeable.' - name: goal in: query required: false schema: type: string example: Find concrete product complaints description: 'Required with fit=goal: describe the task in at most 600 characters. Supplied text is task context, never permission to act on posts.' - name: tokens in: query required: false schema: type: string example: '4000' description: Optional soft response target for fit=goal, 256–32000. Safety and evidence retention take priority, so the returned result may exceed it. - name: limit in: query required: false schema: type: string example: '120' description: Optional requested distinct results, 1–120. Collection stops at the existing request spending and time limits, so fewer may be returned. Inspect partial, window_stop_reason and pages_fetched. Keep query, region, sort, dates and limit unchanged with the opaque cursor. Omit for one native page. - name: X-Max-Credits in: header required: false schema: type: integer minimum: 0 maximum: 9007199254740991 example: 5 description: Optional credit reservation ceiling for this individual request. Send a non-negative integer in decimal digits. Live execution checks the required reservation after resolving free cache hits or buffered continuation, before charging or calling a supplier. A higher reservation returns HTTP 422 INVALID_PARAMETERS with reason max_credits_exceeded and charges nothing. Invalid header values also return 422. Zero permits only a zero-credit reservation; omitting the header uses normal pricing. dry_run remains a free preview. This does not cap later requests, batches or scheduled runs. security: - ApiKeyHeader: [] - BearerKey: [] responses: '200': description: 'The common success envelope; `data` is endpoint-specific. Many lists use items/count/cursor; bundles use named collections and their documented continuation metadata. HTTP 200 can contain a partial bundle: inspect complete, partial and legs where supplied.' content: application/json: schema: allOf: - $ref: '#/components/schemas/Success' - type: object properties: data: $schema: https://json-schema.org/draft/2020-12/schema $id: https://www.monocrawl.com/schemas/tiktok/search.json title: tiktok/search data fields description: Required core structure for successful data, with optional source fields. Additional fields are allowed. This is not a completeness guarantee. type: object properties: items: type: array items: type: object properties: id: type: - string - 'null' description: Source identifier. Preserve its exact string value; do not convert large IDs to numbers. url: type: - string - 'null' description: Original source URL when supplied. caption: type: - string - 'null' description: Video caption; spoken words require a transcript request. created_at: type: - string - 'null' description: Source publication time, normalized to an ISO date-time when available. duration_s: type: - number - 'null' description: Video duration in seconds. region: type: - string - 'null' description: Source-reported content region, not audience geography or proof of residence. author: type: object properties: id: type: - string - 'null' description: Source identifier. Preserve its exact string value; do not convert large IDs to numbers. handle: type: - string - 'null' description: Public account username. name: type: - string - 'null' description: Display name. url: type: - string - 'null' description: Original source URL when supplied. followers: type: - number - 'null' description: Follower count supplied with this video; null when absent. No profile-enrichment call is made. region: type: - string - 'null' description: Source-reported account region, not audience geography or proof of residence. avatar_url: type: - string - 'null' description: Original source URL when supplied. verified: type: - boolean - 'null' description: Explicit source verification flag; precise search may omit it. additionalProperties: true stats: type: object properties: plays: type: - number - 'null' description: plays reported by the source; null or absent is unknown, not zero. likes: type: - number - 'null' description: likes reported by the source; null or absent is unknown, not zero. comments: type: - number - 'null' description: comments reported by the source; null or absent is unknown, not zero. shares: type: - number - 'null' description: shares reported by the source; null or absent is unknown, not zero. saves: type: - number - 'null' description: saves reported by the source; null or absent is unknown, not zero. additionalProperties: true music: type: - object - 'null' properties: id: type: - string - 'null' description: Source identifier. Preserve its exact string value; do not convert large IDs to numbers. title: type: - string - 'null' description: Source sound title. author: type: - string - 'null' description: Source sound author. duration_s: type: - number - 'null' description: Source sound duration in seconds. is_original: type: - boolean - 'null' description: Explicit source original-sound flag. play_url: type: - string - 'null' description: Original source URL when supplied. cover_url: type: - string - 'null' description: Original source URL when supplied. additionalProperties: true additionalProperties: true allOf: - anyOf: - required: - id properties: id: type: - string description: Source identifier. Preserve its exact string value; do not convert large IDs to numbers. minLength: 1 - required: - url properties: url: type: - string description: Original source URL when supplied. minLength: 1 - required: - caption properties: caption: type: - string description: Video caption; spoken words require a transcript request. minLength: 1 - required: - created_at properties: created_at: type: - string description: Source publication time, normalized to an ISO date-time when available. minLength: 1 - required: - duration_s properties: duration_s: type: - number description: Video duration in seconds. - required: - region properties: region: type: - string description: Source-reported content region, not audience geography or proof of residence. minLength: 1 - required: - author properties: author: type: object properties: id: type: - string - 'null' description: Source identifier. Preserve its exact string value; do not convert large IDs to numbers. handle: type: - string - 'null' description: Public account username. name: type: - string - 'null' description: Display name. url: type: - string - 'null' description: Original source URL when supplied. followers: type: - number - 'null' description: Follower count supplied with this video; null when absent. No profile-enrichment call is made. region: type: - string - 'null' description: Source-reported account region, not audience geography or proof of residence. avatar_url: type: - string - 'null' description: Original source URL when supplied. verified: type: - boolean - 'null' description: Explicit source verification flag; precise search may omit it. additionalProperties: true - required: - stats properties: stats: type: object properties: plays: type: - number - 'null' description: plays reported by the source; null or absent is unknown, not zero. likes: type: - number - 'null' description: likes reported by the source; null or absent is unknown, not zero. comments: type: - number - 'null' description: comments reported by the source; null or absent is unknown, not zero. shares: type: - number - 'null' description: shares reported by the source; null or absent is unknown, not zero. saves: type: - number - 'null' description: saves reported by the source; null or absent is unknown, not zero. additionalProperties: true - required: - music properties: music: type: - object properties: id: type: - string - 'null' description: Source identifier. Preserve its exact string value; do not convert large IDs to numbers. title: type: - string - 'null' description: Source sound title. author: type: - string - 'null' description: Source sound author. duration_s: type: - number - 'null' description: Source sound duration in seconds. is_original: type: - boolean - 'null' description: Explicit source original-sound flag. play_url: type: - string - 'null' description: Original source URL when supplied. cover_url: type: - string - 'null' description: Original source URL when supplied. additionalProperties: true description: Records in this response page. count: type: - number - 'null' description: Returned row count when supplied; not the full source total. cursor: type: - string - 'null' description: Opaque next-page token. A missing token does not prove full history was retrieved. has_more: type: - boolean - 'null' description: Source continuation indicator; null means unknown. requested_limit: type: - number - 'null' description: Requested distinct rows when limit is supplied; 1–120. pages_fetched: type: - number - 'null' description: Successful native pages fetched by this request. Zero can mean previously fetched overflow was served. partial: type: - boolean - 'null' description: Collection was interrupted by funding, time, receipt or source limits. window_stop_reason: type: - string - 'null' description: requested_limit, source_exhausted, funding_limit, receipt_pending, deadline, source_unavailable, invalid_source_page, continuation_unavailable, repeated_cursor or page_limit. _warnings: type: array items: type: string description: Collection limitations or component warnings. Read before interpreting coverage. additionalProperties: true required: - items x-contract-version: '2026-09-22' x-validation-scope: Required success payload structure; optional fields and source completeness remain separate. examples: - items: - id: '7350000000000000002' url: https://www.tiktok.com/@example_creator/video/7350000000000000002 caption: A desk setup created_at: '2026-09-01T12:00:00.000Z' duration_s: 15 stats: plays: 1200 likes: 100 comments: 12 shares: null saves: 8 cursor: null has_more: null default: description: The error envelope — the same shape for every non-2xx status. content: application/json: schema: $ref: '#/components/schemas/Error' x-credits: 2 x-production-available: true x-capacity: status: not_assessed message: Capacity is workload-dependent; configured routes do not establish sustained throughput or an availability guarantee. x-availability-scope: Structural check of the effective registered chain, production permission, adapter, configured cost and quality floor without request parameters. True is not a live-health, credential, quota, subscription-entitlement, complete-data or deployment-exposure guarantee. False means no structurally eligible candidate; null means metadata could not establish availability. Composite child capability still depends on its component routes. x-live-proven: true /v1/tiktok/search-hashtag: get: operationId: tiktok_search_hashtag tags: - tiktok summary: Hashtag search description: Videos posted under a TikTok hashtag with engagement counts. Paged by cursor. Costs 1 credit per successful live response. parameters: - name: hashtag in: query required: true schema: type: string example: coffee description: 'Hashtag without the #.' - name: cursor in: query required: false schema: type: string description: Opaque cursor from the previous page. - name: region in: query required: false schema: type: string example: US description: Two-letter country code for the source request location. It can affect availability and ranking; it does not filter creators by residence or audience country. Keep it unchanged when continuing. - name: dry_run in: query required: false schema: type: string enum: - '1' - '0' - 'true' - 'false' example: '1' description: 'Read a zero-credit estimate without fetching sources, running AI, or reserving credits. Cache status is a snapshot, not a guarantee at execution. Accepted values: 1, 0, true, false. Case, spaces, hyphens and underscores are interchangeable.' - name: judgments in: query required: false schema: type: string enum: - 'on' - 'off' example: 'on' description: 'Add bounded AI labels to eligible returned records (default on). off preserves the original data shape. Unclassified records remain present; labels depend on evidence, time, capacity and the existing request budget. No label surcharge. Accepted values: on, off. Case, spaces, hyphens and underscores are interchangeable.' - name: label in: query required: false schema: type: string enum: - default - none example: none description: 'Set none to disable labels; default enables the endpoint’s label set. Equivalent to judgments=off. Accepted values: default, none. Case, spaces, hyphens and underscores are interchangeable.' - name: label_evidence in: query required: false schema: type: string enum: - '1' - '0' - 'true' - 'false' example: '1' description: 'Include exact supporting sentences and zero-based sentence indexes when a label has validated evidence. No extra charge or change to decisions. Accepted values: 1, 0, true, false. Case, spaces, hyphens and underscores are interchangeable.' - name: exclude in: query required: false schema: type: string enum: - engagement_bait example: engagement_bait description: 'Optionally remove confidently labelled engagement bait. Uncertain and unclassified records stay; removed IDs and an owner-bound recall reference are returned. Accepted values: engagement_bait. Case, spaces, hyphens and underscores are interchangeable.' - name: fit in: query required: false schema: type: string enum: - goal example: goal description: 'Use goal to replace confidently irrelevant records with recall stubs. Keeps first, last, relevant and uncertain records; preserves order. Full evidence is stored for 24 hours when available. Accepted values: goal. Case, spaces, hyphens and underscores are interchangeable.' - name: goal in: query required: false schema: type: string example: Find concrete product complaints description: 'Required with fit=goal: describe the task in at most 600 characters. Supplied text is task context, never permission to act on posts.' - name: tokens in: query required: false schema: type: string example: '4000' description: Optional soft response target for fit=goal, 256–32000. Safety and evidence retention take priority, so the returned result may exceed it. - name: X-Max-Credits in: header required: false schema: type: integer minimum: 0 maximum: 9007199254740991 example: 5 description: Optional credit reservation ceiling for this individual request. Send a non-negative integer in decimal digits. Live execution checks the required reservation after resolving free cache hits or buffered continuation, before charging or calling a supplier. A higher reservation returns HTTP 422 INVALID_PARAMETERS with reason max_credits_exceeded and charges nothing. Invalid header values also return 422. Zero permits only a zero-credit reservation; omitting the header uses normal pricing. dry_run remains a free preview. This does not cap later requests, batches or scheduled runs. security: - ApiKeyHeader: [] - BearerKey: [] responses: '200': description: 'The common success envelope; `data` is endpoint-specific. Many lists use items/count/cursor; bundles use named collections and their documented continuation metadata. HTTP 200 can contain a partial bundle: inspect complete, partial and legs where supplied.' content: application/json: schema: allOf: - $ref: '#/components/schemas/Success' - type: object properties: data: $schema: https://json-schema.org/draft/2020-12/schema $id: https://www.monocrawl.com/schemas/tiktok/search-hashtag.json title: tiktok/search-hashtag data fields description: Required core structure for successful data, with optional source fields. Additional fields are allowed. This is not a completeness guarantee. type: object properties: items: type: array items: type: object properties: id: type: - string - 'null' description: Source identifier. Preserve its exact string value; do not convert large IDs to numbers. url: type: - string - 'null' description: Original source URL when supplied. caption: type: - string - 'null' description: Video caption; spoken words require a transcript request. created_at: type: - string - 'null' description: Source publication time, normalized to an ISO date-time when available. duration_s: type: - number - 'null' description: Video duration in seconds. region: type: - string - 'null' description: Source-reported content region, not audience geography or proof of residence. author: type: object properties: id: type: - string - 'null' description: Source identifier. Preserve its exact string value; do not convert large IDs to numbers. handle: type: - string - 'null' description: Public account username. name: type: - string - 'null' description: Display name. url: type: - string - 'null' description: Original source URL when supplied. followers: type: - number - 'null' description: Follower count supplied with this video; null when absent. No profile-enrichment call is made. region: type: - string - 'null' description: Source-reported account region, not audience geography or proof of residence. avatar_url: type: - string - 'null' description: Original source URL when supplied. verified: type: - boolean - 'null' description: Explicit source verification flag; precise search may omit it. additionalProperties: true stats: type: object properties: plays: type: - number - 'null' description: plays reported by the source; null or absent is unknown, not zero. likes: type: - number - 'null' description: likes reported by the source; null or absent is unknown, not zero. comments: type: - number - 'null' description: comments reported by the source; null or absent is unknown, not zero. shares: type: - number - 'null' description: shares reported by the source; null or absent is unknown, not zero. saves: type: - number - 'null' description: saves reported by the source; null or absent is unknown, not zero. additionalProperties: true music: type: - object - 'null' properties: id: type: - string - 'null' description: Source identifier. Preserve its exact string value; do not convert large IDs to numbers. title: type: - string - 'null' description: Source sound title. author: type: - string - 'null' description: Source sound author. duration_s: type: - number - 'null' description: Source sound duration in seconds. is_original: type: - boolean - 'null' description: Explicit source original-sound flag. play_url: type: - string - 'null' description: Original source URL when supplied. cover_url: type: - string - 'null' description: Original source URL when supplied. additionalProperties: true additionalProperties: true allOf: - anyOf: - required: - id properties: id: type: - string description: Source identifier. Preserve its exact string value; do not convert large IDs to numbers. minLength: 1 - required: - url properties: url: type: - string description: Original source URL when supplied. minLength: 1 - required: - caption properties: caption: type: - string description: Video caption; spoken words require a transcript request. minLength: 1 - required: - created_at properties: created_at: type: - string description: Source publication time, normalized to an ISO date-time when available. minLength: 1 - required: - duration_s properties: duration_s: type: - number description: Video duration in seconds. - required: - region properties: region: type: - string description: Source-reported content region, not audience geography or proof of residence. minLength: 1 - required: - author properties: author: type: object properties: id: type: - string - 'null' description: Source identifier. Preserve its exact string value; do not convert large IDs to numbers. handle: type: - string - 'null' description: Public account username. name: type: - string - 'null' description: Display name. url: type: - string - 'null' description: Original source URL when supplied. followers: type: - number - 'null' description: Follower count supplied with this video; null when absent. No profile-enrichment call is made. region: type: - string - 'null' description: Source-reported account region, not audience geography or proof of residence. avatar_url: type: - string - 'null' description: Original source URL when supplied. verified: type: - boolean - 'null' description: Explicit source verification flag; precise search may omit it. additionalProperties: true - required: - stats properties: stats: type: object properties: plays: type: - number - 'null' description: plays reported by the source; null or absent is unknown, not zero. likes: type: - number - 'null' description: likes reported by the source; null or absent is unknown, not zero. comments: type: - number - 'null' description: comments reported by the source; null or absent is unknown, not zero. shares: type: - number - 'null' description: shares reported by the source; null or absent is unknown, not zero. saves: type: - number - 'null' description: saves reported by the source; null or absent is unknown, not zero. additionalProperties: true - required: - music properties: music: type: - object properties: id: type: - string - 'null' description: Source identifier. Preserve its exact string value; do not convert large IDs to numbers. title: type: - string - 'null' description: Source sound title. author: type: - string - 'null' description: Source sound author. duration_s: type: - number - 'null' description: Source sound duration in seconds. is_original: type: - boolean - 'null' description: Explicit source original-sound flag. play_url: type: - string - 'null' description: Original source URL when supplied. cover_url: type: - string - 'null' description: Original source URL when supplied. additionalProperties: true description: Records in this response page. count: type: - number - 'null' description: Returned row count when supplied; not the full source total. cursor: type: - string - 'null' description: Opaque next-page token. A missing token does not prove full history was retrieved. has_more: type: - boolean - 'null' description: Source continuation indicator; null means unknown. _warnings: type: array items: type: string description: Collection limitations or component warnings. Read before interpreting coverage. additionalProperties: true required: - items x-contract-version: '2026-09-22' x-validation-scope: Required success payload structure; optional fields and source completeness remain separate. examples: - items: - id: '7350000000000000002' url: https://www.tiktok.com/@example_creator/video/7350000000000000002 caption: A desk setup created_at: '2026-09-01T12:00:00.000Z' duration_s: 15 stats: plays: 1200 likes: 100 comments: 12 shares: null saves: 8 cursor: null has_more: null default: description: The error envelope — the same shape for every non-2xx status. content: application/json: schema: $ref: '#/components/schemas/Error' x-credits: 1 x-production-available: true x-capacity: status: not_assessed message: Capacity is workload-dependent; configured routes do not establish sustained throughput or an availability guarantee. x-availability-scope: Structural check of the effective registered chain, production permission, adapter, configured cost and quality floor without request parameters. True is not a live-health, credential, quota, subscription-entitlement, complete-data or deployment-exposure guarantee. False means no structurally eligible candidate; null means metadata could not establish availability. Composite child capability still depends on its component routes. x-live-proven: true /v1/tiktok/search-music: get: operationId: tiktok_search_music tags: - tiktok summary: TikTok sound search description: 'TikTok sounds matching a keyword: title, artist, duration, cover, a preview URL and how many videos use each. Costs 1 credit per successful live response.' parameters: - name: query in: query required: true schema: type: string example: espresso description: Search words - name: limit in: query required: false schema: type: string example: '20' description: Sounds per page, up to 20 - name: cursor in: query required: false schema: type: string example: '' description: Page cursor from the previous answer - name: region in: query required: false schema: type: string example: US description: Two-letter region - name: dry_run in: query required: false schema: type: string enum: - '1' - '0' - 'true' - 'false' example: '1' description: 'Read a zero-credit estimate without fetching sources, running AI, or reserving credits. Cache status is a snapshot, not a guarantee at execution. Accepted values: 1, 0, true, false. Case, spaces, hyphens and underscores are interchangeable.' - name: X-Max-Credits in: header required: false schema: type: integer minimum: 0 maximum: 9007199254740991 example: 5 description: Optional credit reservation ceiling for this individual request. Send a non-negative integer in decimal digits. Live execution checks the required reservation after resolving free cache hits or buffered continuation, before charging or calling a supplier. A higher reservation returns HTTP 422 INVALID_PARAMETERS with reason max_credits_exceeded and charges nothing. Invalid header values also return 422. Zero permits only a zero-credit reservation; omitting the header uses normal pricing. dry_run remains a free preview. This does not cap later requests, batches or scheduled runs. security: - ApiKeyHeader: [] - BearerKey: [] responses: '200': description: 'The common success envelope; `data` is endpoint-specific. Many lists use items/count/cursor; bundles use named collections and their documented continuation metadata. HTTP 200 can contain a partial bundle: inspect complete, partial and legs where supplied.' content: application/json: schema: allOf: - $ref: '#/components/schemas/Success' - type: object properties: data: $schema: https://json-schema.org/draft/2020-12/schema $id: https://www.monocrawl.com/schemas/tiktok/search-music.json title: tiktok/search-music data fields description: Optional data supplied by this operation. Null means unknown. type: object properties: count: description: Number of records in this response, not lifetime or total matches. type: - number - 'null' cursor: description: Opaque next-page token; pass it back unchanged. Null does not prove complete history. type: - string - 'null' dropped: description: Optional dropped supplied by this operation. Null means unknown. type: - number - 'null' has_more: description: Source continuation indicator; null means unknown. type: - boolean - 'null' items: description: Returned records. Source coverage and completeness vary. type: - array items: description: Optional record supplied by this operation. Null means unknown. type: object properties: album: description: Optional album supplied by this operation. Null means unknown. type: - string - 'null' artists: description: Optional artists supplied by this operation. Null means unknown. type: - array - 'null' items: description: Optional record supplied by this operation. Null means unknown. type: - string - 'null' author: description: Public author information supplied with this record. type: - string - 'null' commercial: description: Optional commercial supplied by this operation. Null means unknown. type: - boolean - 'null' cover: description: Optional cover supplied by this operation. Null means unknown. type: - string - 'null' duration_seconds: description: Optional duration seconds supplied by this operation. Null means unknown. type: - number - 'null' id: description: Source identifier. Preserve the supplied type and exact value. type: - string - 'null' is_original: description: Optional is original supplied by this operation. Null means unknown. type: - boolean - 'null' owner_handle: description: Optional owner handle supplied by this operation. Null means unknown. type: - string - 'null' platform: description: Optional platform supplied by this operation. Null means unknown. type: - string - 'null' play_url: description: Optional play url supplied by this operation. Null means unknown. type: - string - 'null' title: description: Source title when supplied. type: - string - 'null' url: description: Original source URL when supplied. type: - string - 'null' video_count: description: Optional video count supplied by this operation. Null means unknown. type: - number - 'null' additionalProperties: true allOf: - anyOf: - required: - album properties: album: description: Optional album supplied by this operation. Null means unknown. type: - string minLength: 1 - required: - artists properties: artists: description: Optional artists supplied by this operation. Null means unknown. type: - array items: description: Optional record supplied by this operation. Null means unknown. type: - string - 'null' - required: - author properties: author: description: Public author information supplied with this record. type: - string minLength: 1 - required: - commercial properties: commercial: description: Optional commercial supplied by this operation. Null means unknown. type: - boolean - required: - cover properties: cover: description: Optional cover supplied by this operation. Null means unknown. type: - string minLength: 1 - required: - duration_seconds properties: duration_seconds: description: Optional duration seconds supplied by this operation. Null means unknown. type: - number - required: - id properties: id: description: Source identifier. Preserve the supplied type and exact value. type: - string minLength: 1 - required: - is_original properties: is_original: description: Optional is original supplied by this operation. Null means unknown. type: - boolean - required: - owner_handle properties: owner_handle: description: Optional owner handle supplied by this operation. Null means unknown. type: - string minLength: 1 - required: - play_url properties: play_url: description: Optional play url supplied by this operation. Null means unknown. type: - string minLength: 1 - required: - title properties: title: description: Source title when supplied. type: - string minLength: 1 - required: - url properties: url: description: Original source URL when supplied. type: - string minLength: 1 - required: - video_count properties: video_count: description: Optional video count supplied by this operation. Null means unknown. type: - number query: description: Optional query supplied by this operation. Null means unknown. type: - string - 'null' region: description: Optional region supplied by this operation. Null means unknown. type: - string - 'null' additionalProperties: true required: - items x-contract-version: '2026-09-22' x-validation-scope: Required success payload structure; optional fields and source completeness remain separate. examples: - count: 0 cursor: null dropped: 0 has_more: false items: - album: example artists: - example author: example commercial: false cover: example duration_seconds: 0 id: example is_original: false owner_handle: example platform: example play_url: https://example.com/example title: example url: https://example.com/example video_count: 0 query: example region: example default: description: The error envelope — the same shape for every non-2xx status. content: application/json: schema: $ref: '#/components/schemas/Error' x-credits: 1 x-production-available: true x-capacity: status: not_assessed message: Capacity is workload-dependent; configured routes do not establish sustained throughput or an availability guarantee. x-availability-scope: Structural check of the effective registered chain, production permission, adapter, configured cost and quality floor without request parameters. True is not a live-health, credential, quota, subscription-entitlement, complete-data or deployment-exposure guarantee. False means no structurally eligible candidate; null means metadata could not establish availability. Composite child capability still depends on its component routes. x-live-proven: true /v1/tiktok/search-top: get: operationId: tiktok_search_top tags: - tiktok summary: TikTok top results description: 'The top tab of a TikTok search: the videos TikTok ranks first for a query, as the standard video shape. Costs 1 credit per successful live response.' parameters: - name: query in: query required: true schema: type: string example: james webb telescope description: Search query - name: publish_time in: query required: false schema: type: string enum: - all - all_time - yesterday - past_day - this_week - past_week - this_month - past_month - last_3_months - past_3_months - last_6_months - past_6_months example: '' description: 'Restrict to a publish window when supported Accepted values: all, all_time, yesterday, past_day, this_week, past_week, this_month, past_month, last_3_months, past_3_months, last_6_months, past_6_months. Case, spaces, hyphens and underscores are interchangeable.' - name: sort_by in: query required: false schema: type: string enum: - relevance - most_liked - latest - date_posted example: '' description: 'Sort order when supported Accepted values: relevance, most_liked, latest, date_posted. Case, spaces, hyphens and underscores are interchangeable.' - name: region in: query required: false schema: type: string example: US description: Two-letter region - name: cursor in: query required: false schema: type: string example: '' description: Opaque cursor from the previous page - name: include_music in: query required: false schema: type: string enum: - 'true' - 'false' x-value-aliases: '0': 'false' '1': 'true' example: 'true' description: 'Prefer a native search page with exact string music IDs and supplied author verification, at the same one-credit price. Supported for relevance order with no publish window. Results can differ from ordinary search; keep this option when following its cursor. Unavailable enrichment retains search results with a warning. Accepted values: true, false. Case, spaces, hyphens and underscores are interchangeable.' - name: search_mode in: query required: false schema: type: string enum: - default - precise example: precise description: 'default preserves the current source. precise requires include_music=true, relevance order and no publish window; it supplies source counters, exact music strings and content regions but may omit verification and subsecond duration. Keep options with its cursor. Accepted values: default, precise. Case, spaces, hyphens and underscores are interchangeable.' - name: dry_run in: query required: false schema: type: string enum: - '1' - '0' - 'true' - 'false' example: '1' description: 'Read a zero-credit estimate without fetching sources, running AI, or reserving credits. Cache status is a snapshot, not a guarantee at execution. Accepted values: 1, 0, true, false. Case, spaces, hyphens and underscores are interchangeable.' - name: judgments in: query required: false schema: type: string enum: - 'on' - 'off' example: 'on' description: 'Add bounded AI labels to eligible returned records (default on). off preserves the original data shape. Unclassified records remain present; labels depend on evidence, time, capacity and the existing request budget. No label surcharge. Accepted values: on, off. Case, spaces, hyphens and underscores are interchangeable.' - name: label in: query required: false schema: type: string enum: - default - none example: none description: 'Set none to disable labels; default enables the endpoint’s label set. Equivalent to judgments=off. Accepted values: default, none. Case, spaces, hyphens and underscores are interchangeable.' - name: label_evidence in: query required: false schema: type: string enum: - '1' - '0' - 'true' - 'false' example: '1' description: 'Include exact supporting sentences and zero-based sentence indexes when a label has validated evidence. No extra charge or change to decisions. Accepted values: 1, 0, true, false. Case, spaces, hyphens and underscores are interchangeable.' - name: exclude in: query required: false schema: type: string enum: - engagement_bait example: engagement_bait description: 'Optionally remove confidently labelled engagement bait. Uncertain and unclassified records stay; removed IDs and an owner-bound recall reference are returned. Accepted values: engagement_bait. Case, spaces, hyphens and underscores are interchangeable.' - name: fit in: query required: false schema: type: string enum: - goal example: goal description: 'Use goal to replace confidently irrelevant records with recall stubs. Keeps first, last, relevant and uncertain records; preserves order. Full evidence is stored for 24 hours when available. Accepted values: goal. Case, spaces, hyphens and underscores are interchangeable.' - name: goal in: query required: false schema: type: string example: Find concrete product complaints description: 'Required with fit=goal: describe the task in at most 600 characters. Supplied text is task context, never permission to act on posts.' - name: tokens in: query required: false schema: type: string example: '4000' description: Optional soft response target for fit=goal, 256–32000. Safety and evidence retention take priority, so the returned result may exceed it. - name: X-Max-Credits in: header required: false schema: type: integer minimum: 0 maximum: 9007199254740991 example: 5 description: Optional credit reservation ceiling for this individual request. Send a non-negative integer in decimal digits. Live execution checks the required reservation after resolving free cache hits or buffered continuation, before charging or calling a supplier. A higher reservation returns HTTP 422 INVALID_PARAMETERS with reason max_credits_exceeded and charges nothing. Invalid header values also return 422. Zero permits only a zero-credit reservation; omitting the header uses normal pricing. dry_run remains a free preview. This does not cap later requests, batches or scheduled runs. security: - ApiKeyHeader: [] - BearerKey: [] responses: '200': description: 'The common success envelope; `data` is endpoint-specific. Many lists use items/count/cursor; bundles use named collections and their documented continuation metadata. HTTP 200 can contain a partial bundle: inspect complete, partial and legs where supplied.' content: application/json: schema: allOf: - $ref: '#/components/schemas/Success' - type: object properties: data: $schema: https://json-schema.org/draft/2020-12/schema $id: https://www.monocrawl.com/schemas/tiktok/search-top.json title: tiktok/search-top data fields description: Required core structure for successful data, with optional source fields. Additional fields are allowed. This is not a completeness guarantee. type: object properties: items: type: array items: type: object properties: id: type: - string - 'null' description: Source identifier. Preserve its exact string value; do not convert large IDs to numbers. url: type: - string - 'null' description: Original source URL when supplied. caption: type: - string - 'null' description: Video caption; spoken words require a transcript request. created_at: type: - string - 'null' description: Source publication time, normalized to an ISO date-time when available. duration_s: type: - number - 'null' description: Video duration in seconds. region: type: - string - 'null' description: Source-reported content region, not audience geography or proof of residence. author: type: object properties: id: type: - string - 'null' description: Source identifier. Preserve its exact string value; do not convert large IDs to numbers. handle: type: - string - 'null' description: Public account username. name: type: - string - 'null' description: Display name. url: type: - string - 'null' description: Original source URL when supplied. followers: type: - number - 'null' description: Follower count supplied with this video; null when absent. No profile-enrichment call is made. region: type: - string - 'null' description: Source-reported account region, not audience geography or proof of residence. avatar_url: type: - string - 'null' description: Original source URL when supplied. verified: type: - boolean - 'null' description: Explicit source verification flag; precise search may omit it. additionalProperties: true stats: type: object properties: plays: type: - number - 'null' description: plays reported by the source; null or absent is unknown, not zero. likes: type: - number - 'null' description: likes reported by the source; null or absent is unknown, not zero. comments: type: - number - 'null' description: comments reported by the source; null or absent is unknown, not zero. shares: type: - number - 'null' description: shares reported by the source; null or absent is unknown, not zero. saves: type: - number - 'null' description: saves reported by the source; null or absent is unknown, not zero. additionalProperties: true music: type: - object - 'null' properties: id: type: - string - 'null' description: Source identifier. Preserve its exact string value; do not convert large IDs to numbers. title: type: - string - 'null' description: Source sound title. author: type: - string - 'null' description: Source sound author. duration_s: type: - number - 'null' description: Source sound duration in seconds. is_original: type: - boolean - 'null' description: Explicit source original-sound flag. play_url: type: - string - 'null' description: Original source URL when supplied. cover_url: type: - string - 'null' description: Original source URL when supplied. additionalProperties: true additionalProperties: true allOf: - anyOf: - required: - id properties: id: type: - string description: Source identifier. Preserve its exact string value; do not convert large IDs to numbers. minLength: 1 - required: - url properties: url: type: - string description: Original source URL when supplied. minLength: 1 - required: - caption properties: caption: type: - string description: Video caption; spoken words require a transcript request. minLength: 1 - required: - created_at properties: created_at: type: - string description: Source publication time, normalized to an ISO date-time when available. minLength: 1 - required: - duration_s properties: duration_s: type: - number description: Video duration in seconds. - required: - region properties: region: type: - string description: Source-reported content region, not audience geography or proof of residence. minLength: 1 - required: - author properties: author: type: object properties: id: type: - string - 'null' description: Source identifier. Preserve its exact string value; do not convert large IDs to numbers. handle: type: - string - 'null' description: Public account username. name: type: - string - 'null' description: Display name. url: type: - string - 'null' description: Original source URL when supplied. followers: type: - number - 'null' description: Follower count supplied with this video; null when absent. No profile-enrichment call is made. region: type: - string - 'null' description: Source-reported account region, not audience geography or proof of residence. avatar_url: type: - string - 'null' description: Original source URL when supplied. verified: type: - boolean - 'null' description: Explicit source verification flag; precise search may omit it. additionalProperties: true - required: - stats properties: stats: type: object properties: plays: type: - number - 'null' description: plays reported by the source; null or absent is unknown, not zero. likes: type: - number - 'null' description: likes reported by the source; null or absent is unknown, not zero. comments: type: - number - 'null' description: comments reported by the source; null or absent is unknown, not zero. shares: type: - number - 'null' description: shares reported by the source; null or absent is unknown, not zero. saves: type: - number - 'null' description: saves reported by the source; null or absent is unknown, not zero. additionalProperties: true - required: - music properties: music: type: - object properties: id: type: - string - 'null' description: Source identifier. Preserve its exact string value; do not convert large IDs to numbers. title: type: - string - 'null' description: Source sound title. author: type: - string - 'null' description: Source sound author. duration_s: type: - number - 'null' description: Source sound duration in seconds. is_original: type: - boolean - 'null' description: Explicit source original-sound flag. play_url: type: - string - 'null' description: Original source URL when supplied. cover_url: type: - string - 'null' description: Original source URL when supplied. additionalProperties: true description: Records in this response page. count: type: - number - 'null' description: Returned row count when supplied; not the full source total. cursor: type: - string - 'null' description: Opaque next-page token. A missing token does not prove full history was retrieved. has_more: type: - boolean - 'null' description: Source continuation indicator; null means unknown. _warnings: type: array items: type: string description: Collection limitations or component warnings. Read before interpreting coverage. additionalProperties: true required: - items x-contract-version: '2026-09-22' x-validation-scope: Required success payload structure; optional fields and source completeness remain separate. examples: - items: - id: '7350000000000000002' url: https://www.tiktok.com/@example_creator/video/7350000000000000002 caption: A desk setup created_at: '2026-09-01T12:00:00.000Z' duration_s: 15 stats: plays: 1200 likes: 100 comments: 12 shares: null saves: 8 cursor: null has_more: null default: description: The error envelope — the same shape for every non-2xx status. content: application/json: schema: $ref: '#/components/schemas/Error' x-credits: 1 x-production-available: true x-capacity: status: not_assessed message: Capacity is workload-dependent; configured routes do not establish sustained throughput or an availability guarantee. x-availability-scope: Structural check of the effective registered chain, production permission, adapter, configured cost and quality floor without request parameters. True is not a live-health, credential, quota, subscription-entitlement, complete-data or deployment-exposure guarantee. False means no structurally eligible candidate; null means metadata could not establish availability. Composite child capability still depends on its component routes. x-live-proven: true /v1/tiktok/search-users: get: operationId: tiktok_search_users tags: - tiktok summary: User search description: Search TikTok accounts by keyword. Paged by cursor. Costs 2 credits per successful live response. parameters: - name: query in: query required: true schema: type: string example: space description: Search term. - name: cursor in: query required: false schema: type: string description: Opaque cursor from the previous page. - name: dry_run in: query required: false schema: type: string enum: - '1' - '0' - 'true' - 'false' example: '1' description: 'Read a zero-credit estimate without fetching sources, running AI, or reserving credits. Cache status is a snapshot, not a guarantee at execution. Accepted values: 1, 0, true, false. Case, spaces, hyphens and underscores are interchangeable.' - name: judgments in: query required: false schema: type: string enum: - 'on' - 'off' example: 'on' description: 'Add bounded AI labels to eligible returned records (default on). off preserves the original data shape. Unclassified records remain present; labels depend on evidence, time, capacity and the existing request budget. No label surcharge. Accepted values: on, off. Case, spaces, hyphens and underscores are interchangeable.' - name: label in: query required: false schema: type: string enum: - default - none example: none description: 'Set none to disable labels; default enables the endpoint’s label set. Equivalent to judgments=off. Accepted values: default, none. Case, spaces, hyphens and underscores are interchangeable.' - name: label_evidence in: query required: false schema: type: string enum: - '1' - '0' - 'true' - 'false' example: '1' description: 'Include exact supporting sentences and zero-based sentence indexes when a label has validated evidence. No extra charge or change to decisions. Accepted values: 1, 0, true, false. Case, spaces, hyphens and underscores are interchangeable.' - name: exclude in: query required: false schema: type: string enum: - engagement_bait example: engagement_bait description: 'Optionally remove confidently labelled engagement bait. Uncertain and unclassified records stay; removed IDs and an owner-bound recall reference are returned. Accepted values: engagement_bait. Case, spaces, hyphens and underscores are interchangeable.' - name: fit in: query required: false schema: type: string enum: - goal example: goal description: 'Use goal to replace confidently irrelevant records with recall stubs. Keeps first, last, relevant and uncertain records; preserves order. Full evidence is stored for 24 hours when available. Accepted values: goal. Case, spaces, hyphens and underscores are interchangeable.' - name: goal in: query required: false schema: type: string example: Find concrete product complaints description: 'Required with fit=goal: describe the task in at most 600 characters. Supplied text is task context, never permission to act on posts.' - name: tokens in: query required: false schema: type: string example: '4000' description: Optional soft response target for fit=goal, 256–32000. Safety and evidence retention take priority, so the returned result may exceed it. - name: X-Max-Credits in: header required: false schema: type: integer minimum: 0 maximum: 9007199254740991 example: 5 description: Optional credit reservation ceiling for this individual request. Send a non-negative integer in decimal digits. Live execution checks the required reservation after resolving free cache hits or buffered continuation, before charging or calling a supplier. A higher reservation returns HTTP 422 INVALID_PARAMETERS with reason max_credits_exceeded and charges nothing. Invalid header values also return 422. Zero permits only a zero-credit reservation; omitting the header uses normal pricing. dry_run remains a free preview. This does not cap later requests, batches or scheduled runs. security: - ApiKeyHeader: [] - BearerKey: [] responses: '200': description: 'The common success envelope; `data` is endpoint-specific. Many lists use items/count/cursor; bundles use named collections and their documented continuation metadata. HTTP 200 can contain a partial bundle: inspect complete, partial and legs where supplied.' content: application/json: schema: allOf: - $ref: '#/components/schemas/Success' - type: object properties: data: $schema: https://json-schema.org/draft/2020-12/schema $id: https://www.monocrawl.com/schemas/tiktok/search-users.json title: tiktok/search-users data fields description: Optional data supplied by this operation. Null means unknown. type: object properties: cursor: description: Opaque next-page token; pass it back unchanged. Null does not prove complete history. type: - string - 'null' dropped: description: Optional dropped supplied by this operation. Null means unknown. type: - number - 'null' has_more: description: Source continuation indicator; null means unknown. type: - boolean - 'null' items: description: Returned records. Source coverage and completeness vary. type: - array items: description: Optional record supplied by this operation. Null means unknown. type: object properties: avatar_url: description: Optional avatar url supplied by this operation. Null means unknown. type: - string - 'null' followers: description: Optional followers supplied by this operation. Null means unknown. type: - number - 'null' following: description: Optional following supplied by this operation. Null means unknown. type: - number - 'null' handle: description: Optional handle supplied by this operation. Null means unknown. type: - string - 'null' id: description: Source identifier. Preserve the supplied type and exact value. type: - string - 'null' likes_count: description: Optional likes count supplied by this operation. Null means unknown. type: - number - 'null' name: description: Optional name supplied by this operation. Null means unknown. type: - string - 'null' platform: description: Optional platform supplied by this operation. Null means unknown. type: - string - 'null' verified: description: Optional verified supplied by this operation. Null means unknown. type: - boolean - 'null' videos_count: description: Optional videos count supplied by this operation. Null means unknown. type: - number - 'null' additionalProperties: true allOf: - anyOf: - required: - avatar_url properties: avatar_url: description: Optional avatar url supplied by this operation. Null means unknown. type: - string minLength: 1 - required: - followers properties: followers: description: Optional followers supplied by this operation. Null means unknown. type: - number - required: - following properties: following: description: Optional following supplied by this operation. Null means unknown. type: - number - required: - handle properties: handle: description: Optional handle supplied by this operation. Null means unknown. type: - string minLength: 1 - required: - id properties: id: description: Source identifier. Preserve the supplied type and exact value. type: - string minLength: 1 - required: - likes_count properties: likes_count: description: Optional likes count supplied by this operation. Null means unknown. type: - number - required: - name properties: name: description: Optional name supplied by this operation. Null means unknown. type: - string minLength: 1 - required: - verified properties: verified: description: Optional verified supplied by this operation. Null means unknown. type: - boolean - required: - videos_count properties: videos_count: description: Optional videos count supplied by this operation. Null means unknown. type: - number additionalProperties: true required: - items x-contract-version: '2026-09-22' x-validation-scope: Required success payload structure; optional fields and source completeness remain separate. examples: - cursor: null dropped: 0 has_more: false items: - avatar_url: https://example.com/example followers: 0 following: 0 handle: example id: example likes_count: 0 name: example platform: example verified: false videos_count: 0 default: description: The error envelope — the same shape for every non-2xx status. content: application/json: schema: $ref: '#/components/schemas/Error' x-credits: 2 x-production-available: true x-capacity: status: not_assessed message: Capacity is workload-dependent; configured routes do not establish sustained throughput or an availability guarantee. x-availability-scope: Structural check of the effective registered chain, production permission, adapter, configured cost and quality floor without request parameters. True is not a live-health, credential, quota, subscription-entitlement, complete-data or deployment-exposure guarantee. False means no structurally eligible candidate; null means metadata could not establish availability. Composite child capability still depends on its component routes. x-live-proven: true /v1/tiktok/song: get: operationId: tiktok_song tags: - tiktok summary: Sound details description: 'One TikTok sound: title, artists, duration and how many videos use it — the id feeds tiktok/song-videos. Costs 1 credit per successful live response.' parameters: - name: id in: query required: true schema: type: string example: '7439295283975702544' description: TikTok sound/clip id. - name: dry_run in: query required: false schema: type: string enum: - '1' - '0' - 'true' - 'false' example: '1' description: 'Read a zero-credit estimate without fetching sources, running AI, or reserving credits. Cache status is a snapshot, not a guarantee at execution. Accepted values: 1, 0, true, false. Case, spaces, hyphens and underscores are interchangeable.' - name: X-Max-Credits in: header required: false schema: type: integer minimum: 0 maximum: 9007199254740991 example: 5 description: Optional credit reservation ceiling for this individual request. Send a non-negative integer in decimal digits. Live execution checks the required reservation after resolving free cache hits or buffered continuation, before charging or calling a supplier. A higher reservation returns HTTP 422 INVALID_PARAMETERS with reason max_credits_exceeded and charges nothing. Invalid header values also return 422. Zero permits only a zero-credit reservation; omitting the header uses normal pricing. dry_run remains a free preview. This does not cap later requests, batches or scheduled runs. security: - ApiKeyHeader: [] - BearerKey: [] responses: '200': description: 'The common success envelope; `data` is endpoint-specific. Many lists use items/count/cursor; bundles use named collections and their documented continuation metadata. HTTP 200 can contain a partial bundle: inspect complete, partial and legs where supplied.' content: application/json: schema: allOf: - $ref: '#/components/schemas/Success' - type: object properties: data: $schema: https://json-schema.org/draft/2020-12/schema $id: https://www.monocrawl.com/schemas/tiktok/song.json title: tiktok/song data fields description: Optional data supplied by this operation. Null means unknown. type: object properties: album: description: Optional album supplied by this operation. Null means unknown. type: - string - 'null' artists: description: Optional artists supplied by this operation. Null means unknown. type: - array - 'null' items: description: Optional record supplied by this operation. Null means unknown. type: - string - 'null' author: description: Public author information supplied with this record. type: - string - 'null' commercial: description: Optional commercial supplied by this operation. Null means unknown. type: - boolean - 'null' cover: description: Optional cover supplied by this operation. Null means unknown. type: - string - 'null' duration_seconds: description: Optional duration seconds supplied by this operation. Null means unknown. type: - number - 'null' id: description: Source identifier. Preserve the supplied type and exact value. type: - string - 'null' is_original: description: Optional is original supplied by this operation. Null means unknown. type: - boolean - 'null' platform: description: Optional platform supplied by this operation. Null means unknown. type: - string - 'null' play_url: description: Optional play url supplied by this operation. Null means unknown. type: - string - 'null' title: description: Source title when supplied. type: - string - 'null' url: description: Original source URL when supplied. type: - string - 'null' video_count: description: Optional video count supplied by this operation. Null means unknown. type: - number - 'null' additionalProperties: true allOf: - anyOf: - required: - album properties: album: description: Optional album supplied by this operation. Null means unknown. type: - string minLength: 1 - required: - artists properties: artists: description: Optional artists supplied by this operation. Null means unknown. type: - array items: description: Optional record supplied by this operation. Null means unknown. type: - string - 'null' - required: - author properties: author: description: Public author information supplied with this record. type: - string minLength: 1 - required: - commercial properties: commercial: description: Optional commercial supplied by this operation. Null means unknown. type: - boolean - required: - cover properties: cover: description: Optional cover supplied by this operation. Null means unknown. type: - string minLength: 1 - required: - duration_seconds properties: duration_seconds: description: Optional duration seconds supplied by this operation. Null means unknown. type: - number - required: - id properties: id: description: Source identifier. Preserve the supplied type and exact value. type: - string minLength: 1 - required: - is_original properties: is_original: description: Optional is original supplied by this operation. Null means unknown. type: - boolean - required: - play_url properties: play_url: description: Optional play url supplied by this operation. Null means unknown. type: - string minLength: 1 - required: - title properties: title: description: Source title when supplied. type: - string minLength: 1 - required: - url properties: url: description: Original source URL when supplied. type: - string minLength: 1 - required: - video_count properties: video_count: description: Optional video count supplied by this operation. Null means unknown. type: - number x-contract-version: '2026-09-22' x-validation-scope: Required success payload structure; optional fields and source completeness remain separate. examples: - album: example artists: - example author: example commercial: false cover: example duration_seconds: 0 id: example is_original: false platform: example play_url: https://example.com/example title: example url: https://example.com/example video_count: 0 default: description: The error envelope — the same shape for every non-2xx status. content: application/json: schema: $ref: '#/components/schemas/Error' x-credits: 1 x-production-available: true x-capacity: status: not_assessed message: Capacity is workload-dependent; configured routes do not establish sustained throughput or an availability guarantee. x-availability-scope: Structural check of the effective registered chain, production permission, adapter, configured cost and quality floor without request parameters. True is not a live-health, credential, quota, subscription-entitlement, complete-data or deployment-exposure guarantee. False means no structurally eligible candidate; null means metadata could not establish availability. Composite child capability still depends on its component routes. x-live-proven: true /v1/tiktok/song-videos: get: operationId: tiktok_song_videos tags: - tiktok summary: Videos using a sound description: Videos that use a specific TikTok sound — sound-trend intelligence. Paged by cursor. Costs 1 credit per successful live response. parameters: - name: id in: query required: true schema: type: string example: '7439295283975702544' description: TikTok sound/clip id. - name: cursor in: query required: false schema: type: string description: Opaque cursor from the previous page. - name: dry_run in: query required: false schema: type: string enum: - '1' - '0' - 'true' - 'false' example: '1' description: 'Read a zero-credit estimate without fetching sources, running AI, or reserving credits. Cache status is a snapshot, not a guarantee at execution. Accepted values: 1, 0, true, false. Case, spaces, hyphens and underscores are interchangeable.' - name: judgments in: query required: false schema: type: string enum: - 'on' - 'off' example: 'on' description: 'Add bounded AI labels to eligible returned records (default on). off preserves the original data shape. Unclassified records remain present; labels depend on evidence, time, capacity and the existing request budget. No label surcharge. Accepted values: on, off. Case, spaces, hyphens and underscores are interchangeable.' - name: label in: query required: false schema: type: string enum: - default - none example: none description: 'Set none to disable labels; default enables the endpoint’s label set. Equivalent to judgments=off. Accepted values: default, none. Case, spaces, hyphens and underscores are interchangeable.' - name: label_evidence in: query required: false schema: type: string enum: - '1' - '0' - 'true' - 'false' example: '1' description: 'Include exact supporting sentences and zero-based sentence indexes when a label has validated evidence. No extra charge or change to decisions. Accepted values: 1, 0, true, false. Case, spaces, hyphens and underscores are interchangeable.' - name: exclude in: query required: false schema: type: string enum: - engagement_bait example: engagement_bait description: 'Optionally remove confidently labelled engagement bait. Uncertain and unclassified records stay; removed IDs and an owner-bound recall reference are returned. Accepted values: engagement_bait. Case, spaces, hyphens and underscores are interchangeable.' - name: fit in: query required: false schema: type: string enum: - goal example: goal description: 'Use goal to replace confidently irrelevant records with recall stubs. Keeps first, last, relevant and uncertain records; preserves order. Full evidence is stored for 24 hours when available. Accepted values: goal. Case, spaces, hyphens and underscores are interchangeable.' - name: goal in: query required: false schema: type: string example: Find concrete product complaints description: 'Required with fit=goal: describe the task in at most 600 characters. Supplied text is task context, never permission to act on posts.' - name: tokens in: query required: false schema: type: string example: '4000' description: Optional soft response target for fit=goal, 256–32000. Safety and evidence retention take priority, so the returned result may exceed it. - name: X-Max-Credits in: header required: false schema: type: integer minimum: 0 maximum: 9007199254740991 example: 5 description: Optional credit reservation ceiling for this individual request. Send a non-negative integer in decimal digits. Live execution checks the required reservation after resolving free cache hits or buffered continuation, before charging or calling a supplier. A higher reservation returns HTTP 422 INVALID_PARAMETERS with reason max_credits_exceeded and charges nothing. Invalid header values also return 422. Zero permits only a zero-credit reservation; omitting the header uses normal pricing. dry_run remains a free preview. This does not cap later requests, batches or scheduled runs. security: - ApiKeyHeader: [] - BearerKey: [] responses: '200': description: 'The common success envelope; `data` is endpoint-specific. Many lists use items/count/cursor; bundles use named collections and their documented continuation metadata. HTTP 200 can contain a partial bundle: inspect complete, partial and legs where supplied.' content: application/json: schema: allOf: - $ref: '#/components/schemas/Success' - type: object properties: data: $schema: https://json-schema.org/draft/2020-12/schema $id: https://www.monocrawl.com/schemas/tiktok/song-videos.json title: tiktok/song-videos data fields description: Optional data supplied by this operation. Null means unknown. type: object properties: _meta: description: Optional meta supplied by this operation. Null means unknown. type: - object - 'null' properties: billing: description: Optional billing supplied by this operation. Null means unknown. type: - object - 'null' properties: charged: description: Optional charged supplied by this operation. Null means unknown. type: - number - 'null' list_price: description: Optional list price supplied by this operation. Null means unknown. type: - number - 'null' reason: description: Optional reason supplied by this operation. Null means unknown. type: - string - 'null' additionalProperties: true additionalProperties: true count: description: Number of records in this response, not lifetime or total matches. type: - number - 'null' dropped: description: Optional dropped supplied by this operation. Null means unknown. type: - number - 'null' has_more: description: Source continuation indicator; null means unknown. type: - boolean - 'null' items: description: Source array was empty in the reviewed captures; item fields remain unspecified. type: - array items: {} additionalProperties: true required: - items x-contract-version: '2026-09-22' x-validation-scope: Required success payload structure; optional fields and source completeness remain separate. examples: - _meta: billing: charged: 0 list_price: 0 reason: example count: 0 dropped: 0 has_more: false items: [] default: description: The error envelope — the same shape for every non-2xx status. content: application/json: schema: $ref: '#/components/schemas/Error' x-credits: 1 x-production-available: true x-capacity: status: not_assessed message: Capacity is workload-dependent; configured routes do not establish sustained throughput or an availability guarantee. x-availability-scope: Structural check of the effective registered chain, production permission, adapter, configured cost and quality floor without request parameters. True is not a live-health, credential, quota, subscription-entitlement, complete-data or deployment-exposure guarantee. False means no structurally eligible candidate; null means metadata could not establish availability. Composite child capability still depends on its component routes. x-live-proven: true /v1/tiktok/suggestions: get: operationId: tiktok_suggestions tags: - tiktok summary: TikTok search suggestions description: What TikTok suggests as you type a query, in order, with the language and score of each suggestion. Costs 2 credits per successful live response. parameters: - name: query in: query required: true schema: type: string example: space description: Partial query to complete - name: region in: query required: false schema: type: string example: US description: Two-letter region for the suggestions - name: dry_run in: query required: false schema: type: string enum: - '1' - '0' - 'true' - 'false' example: '1' description: 'Read a zero-credit estimate without fetching sources, running AI, or reserving credits. Cache status is a snapshot, not a guarantee at execution. Accepted values: 1, 0, true, false. Case, spaces, hyphens and underscores are interchangeable.' - name: X-Max-Credits in: header required: false schema: type: integer minimum: 0 maximum: 9007199254740991 example: 5 description: Optional credit reservation ceiling for this individual request. Send a non-negative integer in decimal digits. Live execution checks the required reservation after resolving free cache hits or buffered continuation, before charging or calling a supplier. A higher reservation returns HTTP 422 INVALID_PARAMETERS with reason max_credits_exceeded and charges nothing. Invalid header values also return 422. Zero permits only a zero-credit reservation; omitting the header uses normal pricing. dry_run remains a free preview. This does not cap later requests, batches or scheduled runs. security: - ApiKeyHeader: [] - BearerKey: [] responses: '200': description: 'The common success envelope; `data` is endpoint-specific. Many lists use items/count/cursor; bundles use named collections and their documented continuation metadata. HTTP 200 can contain a partial bundle: inspect complete, partial and legs where supplied.' content: application/json: schema: allOf: - $ref: '#/components/schemas/Success' - type: object properties: data: $schema: https://json-schema.org/draft/2020-12/schema $id: https://www.monocrawl.com/schemas/tiktok/suggestions.json title: tiktok/suggestions data fields description: Optional data supplied by this operation. Null means unknown. type: object properties: count: description: Number of records in this response, not lifetime or total matches. type: - number - 'null' items: description: Returned records. Source coverage and completeness vary. type: - array items: description: Optional record supplied by this operation. Null means unknown. type: object properties: language: description: Optional language supplied by this operation. Null means unknown. type: - string - 'null' position: description: Optional position supplied by this operation. Null means unknown. type: - number - 'null' score: description: Optional score supplied by this operation. Null means unknown. type: - number - 'null' text: description: Source text when supplied. type: - string - 'null' additionalProperties: true allOf: - anyOf: - required: - language properties: language: description: Optional language supplied by this operation. Null means unknown. type: - string minLength: 1 - required: - position properties: position: description: Optional position supplied by this operation. Null means unknown. type: - number - required: - score properties: score: description: Optional score supplied by this operation. Null means unknown. type: - number - required: - text properties: text: description: Source text when supplied. type: - string minLength: 1 additionalProperties: true required: - items x-contract-version: '2026-09-22' x-validation-scope: Required success payload structure; optional fields and source completeness remain separate. examples: - count: 0 items: - language: example position: 0 score: 0 text: example default: description: The error envelope — the same shape for every non-2xx status. content: application/json: schema: $ref: '#/components/schemas/Error' x-credits: 2 x-production-available: true x-capacity: status: not_assessed message: Capacity is workload-dependent; configured routes do not establish sustained throughput or an availability guarantee. x-availability-scope: Structural check of the effective registered chain, production permission, adapter, configured cost and quality floor without request parameters. True is not a live-health, credential, quota, subscription-entitlement, complete-data or deployment-exposure guarantee. False means no structurally eligible candidate; null means metadata could not establish availability. Composite child capability still depends on its component routes. x-live-proven: true /v1/tiktok/trending: get: operationId: tiktok_trending tags: - tiktok summary: Trending feed description: TikTok's trending feed for a region — what is going viral right now, with per-video stats. Costs 4 credits per successful live response. parameters: - name: region in: query required: true schema: type: string example: US description: Two-letter region code. - name: dry_run in: query required: false schema: type: string enum: - '1' - '0' - 'true' - 'false' example: '1' description: 'Read a zero-credit estimate without fetching sources, running AI, or reserving credits. Cache status is a snapshot, not a guarantee at execution. Accepted values: 1, 0, true, false. Case, spaces, hyphens and underscores are interchangeable.' - name: X-Max-Credits in: header required: false schema: type: integer minimum: 0 maximum: 9007199254740991 example: 5 description: Optional credit reservation ceiling for this individual request. Send a non-negative integer in decimal digits. Live execution checks the required reservation after resolving free cache hits or buffered continuation, before charging or calling a supplier. A higher reservation returns HTTP 422 INVALID_PARAMETERS with reason max_credits_exceeded and charges nothing. Invalid header values also return 422. Zero permits only a zero-credit reservation; omitting the header uses normal pricing. dry_run remains a free preview. This does not cap later requests, batches or scheduled runs. security: - ApiKeyHeader: [] - BearerKey: [] responses: '200': description: 'The common success envelope; `data` is endpoint-specific. Many lists use items/count/cursor; bundles use named collections and their documented continuation metadata. HTTP 200 can contain a partial bundle: inspect complete, partial and legs where supplied.' content: application/json: schema: allOf: - $ref: '#/components/schemas/Success' - type: object properties: data: $schema: https://json-schema.org/draft/2020-12/schema $id: https://www.monocrawl.com/schemas/tiktok/trending.json title: tiktok/trending data fields description: Optional data supplied by this operation. Null means unknown. type: object properties: items: description: Returned records. Source coverage and completeness vary. type: - array items: description: Optional record supplied by this operation. Null means unknown. type: object properties: author: description: Public author information supplied with this record. type: - object - 'null' properties: avatar_url: description: Optional avatar url supplied by this operation. Null means unknown. type: - string - 'null' handle: description: Optional handle supplied by this operation. Null means unknown. type: - string - 'null' id: description: Source identifier. Preserve the supplied type and exact value. type: - string - 'null' name: description: Optional name supplied by this operation. Null means unknown. type: - string - 'null' additionalProperties: true caption: description: Optional caption supplied by this operation. Null means unknown. type: - string - 'null' created_at: description: Source creation time, not the API retrieval time. type: - string - 'null' duration_s: description: Optional duration s supplied by this operation. Null means unknown. type: - number - 'null' hashtags: description: Source array was empty in the reviewed captures; item fields remain unspecified. type: - array - 'null' items: {} id: description: Source identifier. Preserve the supplied type and exact value. type: - string - 'null' images: description: Optional images supplied by this operation. Null means unknown. type: - array - 'null' items: description: Optional record supplied by this operation. Null means unknown. type: - string - 'null' media_urls: description: Optional media urls supplied by this operation. Null means unknown. type: - array - 'null' items: description: Optional record supplied by this operation. Null means unknown. type: - string - 'null' platform: description: Optional platform supplied by this operation. Null means unknown. type: - string - 'null' region: description: Optional region supplied by this operation. Null means unknown. type: - string - 'null' stats: description: Optional stats supplied by this operation. Null means unknown. type: - object - 'null' properties: comments: description: Optional comments supplied by this operation. Null means unknown. type: - number - 'null' likes: description: Optional likes supplied by this operation. Null means unknown. type: - number - 'null' plays: description: Optional plays supplied by this operation. Null means unknown. type: - number - 'null' saves: description: Optional saves supplied by this operation. Null means unknown. type: - number - 'null' shares: description: Optional shares supplied by this operation. Null means unknown. type: - number - 'null' additionalProperties: true thumbnail_url: description: Optional thumbnail url supplied by this operation. Null means unknown. type: - string - 'null' url: description: Original source URL when supplied. type: - string - 'null' video_url: description: Optional video url supplied by this operation. Null means unknown. type: - string - 'null' additionalProperties: true allOf: - anyOf: - required: - author properties: author: description: Public author information supplied with this record. type: - object properties: avatar_url: description: Optional avatar url supplied by this operation. Null means unknown. type: - string - 'null' handle: description: Optional handle supplied by this operation. Null means unknown. type: - string - 'null' id: description: Source identifier. Preserve the supplied type and exact value. type: - string - 'null' name: description: Optional name supplied by this operation. Null means unknown. type: - string - 'null' additionalProperties: true - required: - caption properties: caption: description: Optional caption supplied by this operation. Null means unknown. type: - string minLength: 1 - required: - created_at properties: created_at: description: Source creation time, not the API retrieval time. type: - string minLength: 1 - required: - duration_s properties: duration_s: description: Optional duration s supplied by this operation. Null means unknown. type: - number - required: - hashtags properties: hashtags: description: Source array was empty in the reviewed captures; item fields remain unspecified. type: - array items: {} - required: - id properties: id: description: Source identifier. Preserve the supplied type and exact value. type: - string minLength: 1 - required: - images properties: images: description: Optional images supplied by this operation. Null means unknown. type: - array items: description: Optional record supplied by this operation. Null means unknown. type: - string - 'null' - required: - media_urls properties: media_urls: description: Optional media urls supplied by this operation. Null means unknown. type: - array items: description: Optional record supplied by this operation. Null means unknown. type: - string - 'null' - required: - region properties: region: description: Optional region supplied by this operation. Null means unknown. type: - string minLength: 1 - required: - stats properties: stats: description: Optional stats supplied by this operation. Null means unknown. type: - object properties: comments: description: Optional comments supplied by this operation. Null means unknown. type: - number - 'null' likes: description: Optional likes supplied by this operation. Null means unknown. type: - number - 'null' plays: description: Optional plays supplied by this operation. Null means unknown. type: - number - 'null' saves: description: Optional saves supplied by this operation. Null means unknown. type: - number - 'null' shares: description: Optional shares supplied by this operation. Null means unknown. type: - number - 'null' additionalProperties: true - required: - thumbnail_url properties: thumbnail_url: description: Optional thumbnail url supplied by this operation. Null means unknown. type: - string minLength: 1 - required: - url properties: url: description: Original source URL when supplied. type: - string minLength: 1 - required: - video_url properties: video_url: description: Optional video url supplied by this operation. Null means unknown. type: - string minLength: 1 additionalProperties: true required: - items x-contract-version: '2026-09-22' x-validation-scope: Required success payload structure; optional fields and source completeness remain separate. examples: - items: - author: avatar_url: https://example.com/example handle: example id: example name: example caption: example created_at: '2026-09-01T12:00:00Z' duration_s: 0 hashtags: [] id: example images: - example media_urls: - example platform: example region: example stats: comments: 0 likes: 0 plays: 0 saves: 0 shares: 0 thumbnail_url: https://example.com/example url: https://example.com/example video_url: https://example.com/example default: description: The error envelope — the same shape for every non-2xx status. content: application/json: schema: $ref: '#/components/schemas/Error' x-credits: 4 x-production-available: true x-capacity: status: not_assessed message: Capacity is workload-dependent; configured routes do not establish sustained throughput or an availability guarantee. x-availability-scope: Structural check of the effective registered chain, production permission, adapter, configured cost and quality floor without request parameters. True is not a live-health, credential, quota, subscription-entitlement, complete-data or deployment-exposure guarantee. False means no structurally eligible candidate; null means metadata could not establish availability. Composite child capability still depends on its component routes. x-live-proven: true /v1/tiktok/user-audience: get: operationId: tiktok_user_audience tags: - tiktok summary: Sampled audience geography description: Retrieve source-reported country counts. Source percentages can be null. Calculated returned_count_share_percentage uses returned_count_total only; it is not whole-audience reach. Sampling method and collection time are unknown. Costs 30 credits per successful live response. parameters: - name: handle in: query required: true schema: type: string example: nasa description: TikTok username without the @ An optional leading @ is accepted and removed before lookup. - name: dry_run in: query required: false schema: type: string enum: - '1' - '0' - 'true' - 'false' example: '1' description: 'Read a zero-credit estimate without fetching sources, running AI, or reserving credits. Cache status is a snapshot, not a guarantee at execution. Accepted values: 1, 0, true, false. Case, spaces, hyphens and underscores are interchangeable.' - name: judgments in: query required: false schema: type: string enum: - 'on' - 'off' example: 'on' description: 'Add bounded AI labels to eligible returned records (default on). off preserves the original data shape. Unclassified records remain present; labels depend on evidence, time, capacity and the existing request budget. No label surcharge. Accepted values: on, off. Case, spaces, hyphens and underscores are interchangeable.' - name: label in: query required: false schema: type: string enum: - default - none example: none description: 'Set none to disable labels; default enables the endpoint’s label set. Equivalent to judgments=off. Accepted values: default, none. Case, spaces, hyphens and underscores are interchangeable.' - name: label_evidence in: query required: false schema: type: string enum: - '1' - '0' - 'true' - 'false' example: '1' description: 'Include exact supporting sentences and zero-based sentence indexes when a label has validated evidence. No extra charge or change to decisions. Accepted values: 1, 0, true, false. Case, spaces, hyphens and underscores are interchangeable.' - name: exclude in: query required: false schema: type: string enum: - engagement_bait example: engagement_bait description: 'Optionally remove confidently labelled engagement bait. Uncertain and unclassified records stay; removed IDs and an owner-bound recall reference are returned. Accepted values: engagement_bait. Case, spaces, hyphens and underscores are interchangeable.' - name: fit in: query required: false schema: type: string enum: - goal example: goal description: 'Use goal to replace confidently irrelevant records with recall stubs. Keeps first, last, relevant and uncertain records; preserves order. Full evidence is stored for 24 hours when available. Accepted values: goal. Case, spaces, hyphens and underscores are interchangeable.' - name: goal in: query required: false schema: type: string example: Find concrete product complaints description: 'Required with fit=goal: describe the task in at most 600 characters. Supplied text is task context, never permission to act on posts.' - name: tokens in: query required: false schema: type: string example: '4000' description: Optional soft response target for fit=goal, 256–32000. Safety and evidence retention take priority, so the returned result may exceed it. - name: X-Max-Credits in: header required: false schema: type: integer minimum: 0 maximum: 9007199254740991 example: 5 description: Optional credit reservation ceiling for this individual request. Send a non-negative integer in decimal digits. Live execution checks the required reservation after resolving free cache hits or buffered continuation, before charging or calling a supplier. A higher reservation returns HTTP 422 INVALID_PARAMETERS with reason max_credits_exceeded and charges nothing. Invalid header values also return 422. Zero permits only a zero-credit reservation; omitting the header uses normal pricing. dry_run remains a free preview. This does not cap later requests, batches or scheduled runs. security: - ApiKeyHeader: [] - BearerKey: [] responses: '200': description: 'The common success envelope; `data` is endpoint-specific. Many lists use items/count/cursor; bundles use named collections and their documented continuation metadata. HTTP 200 can contain a partial bundle: inspect complete, partial and legs where supplied.' content: application/json: schema: allOf: - $ref: '#/components/schemas/Success' - type: object properties: data: $schema: https://json-schema.org/draft/2020-12/schema $id: https://www.monocrawl.com/schemas/tiktok/user-audience.json title: tiktok/user-audience data fields description: Required core structure for successful data, with optional source fields. Additional fields are allowed. This is not a completeness guarantee. type: object properties: platform: type: - string - 'null' description: tiktok locations: type: array items: type: object properties: country: type: - string - 'null' description: Country name. country_code: type: - string - 'null' description: Source country code. count: type: - number - 'null' description: Source-reported country count; unknown sampling method. percentage: type: - number - 'null' description: Source percentage only, 0–100; null when absent. Its denominator is not independently verified. returned_count_share_percentage: type: - number - 'null' description: Calculated percentage of returned_count_total only; not a whole-audience percentage. additionalProperties: true allOf: - anyOf: - required: - country properties: country: type: - string description: Country name. minLength: 1 - required: - country_code properties: country_code: type: - string description: Source country code. minLength: 1 - required: - percentage properties: percentage: type: - number description: Source percentage only, 0–100; null when absent. Its denominator is not independently verified. - required: - returned_count_share_percentage properties: returned_count_share_percentage: type: - number description: Calculated percentage of returned_count_total only; not a whole-audience percentage. returned_count_total: type: - number - 'null' description: Sum of returned country counts, or null if any count is missing or invalid. sampling: type: object properties: share_basis: type: - string - 'null' description: returned_country_counts methodology: type: - string - 'null' description: Unknown when null. sampled_at: type: - string - 'null' description: Unknown when null. note: type: - string - 'null' description: Sampling limitations. additionalProperties: true _warnings: type: array items: type: string description: Collection limitations or component warnings. Read before interpreting coverage. additionalProperties: true required: - locations x-contract-version: '2026-09-22' x-validation-scope: Required success payload structure; optional fields and source completeness remain separate. examples: - platform: tiktok locations: - country: United Kingdom country_code: GB count: 30 percentage: null returned_count_share_percentage: 100 returned_count_total: 30 sampling: share_basis: returned_country_counts methodology: null sampled_at: null default: description: The error envelope — the same shape for every non-2xx status. content: application/json: schema: $ref: '#/components/schemas/Error' x-credits: 30 x-production-available: true x-capacity: status: not_assessed message: Capacity is workload-dependent; configured routes do not establish sustained throughput or an availability guarantee. x-availability-scope: Structural check of the effective registered chain, production permission, adapter, configured cost and quality floor without request parameters. True is not a live-health, credential, quota, subscription-entitlement, complete-data or deployment-exposure guarantee. False means no structurally eligible candidate; null means metadata could not establish availability. Composite child capability still depends on its component routes. x-live-proven: true /v1/tiktok/user-followers: get: operationId: tiktok_user_followers tags: - tiktok summary: Followers description: An account's followers with per-user follower counts. Paged by min_time cursor. Costs 1 credit per successful live response. parameters: - name: handle in: query required: true schema: type: string example: stoolpresidente description: TikTok username without the @ (or pass user_id). An optional leading @ is accepted and removed before lookup. - name: user_id in: query required: false schema: type: string description: Numeric user id — alternative to handle. - name: cursor in: query required: false schema: type: string description: min_time value from the previous page. - name: dry_run in: query required: false schema: type: string enum: - '1' - '0' - 'true' - 'false' example: '1' description: 'Read a zero-credit estimate without fetching sources, running AI, or reserving credits. Cache status is a snapshot, not a guarantee at execution. Accepted values: 1, 0, true, false. Case, spaces, hyphens and underscores are interchangeable.' - name: X-Max-Credits in: header required: false schema: type: integer minimum: 0 maximum: 9007199254740991 example: 5 description: Optional credit reservation ceiling for this individual request. Send a non-negative integer in decimal digits. Live execution checks the required reservation after resolving free cache hits or buffered continuation, before charging or calling a supplier. A higher reservation returns HTTP 422 INVALID_PARAMETERS with reason max_credits_exceeded and charges nothing. Invalid header values also return 422. Zero permits only a zero-credit reservation; omitting the header uses normal pricing. dry_run remains a free preview. This does not cap later requests, batches or scheduled runs. security: - ApiKeyHeader: [] - BearerKey: [] responses: '200': description: 'The common success envelope; `data` is endpoint-specific. Many lists use items/count/cursor; bundles use named collections and their documented continuation metadata. HTTP 200 can contain a partial bundle: inspect complete, partial and legs where supplied.' content: application/json: schema: allOf: - $ref: '#/components/schemas/Success' - type: object properties: data: $schema: https://json-schema.org/draft/2020-12/schema $id: https://www.monocrawl.com/schemas/tiktok/user-followers.json title: tiktok/user-followers data fields description: Optional data supplied by this operation. Null means unknown. type: object properties: cursor: description: Opaque next-page token; pass it back unchanged. Null does not prove complete history. type: - string - 'null' dropped: description: Optional dropped supplied by this operation. Null means unknown. type: - number - 'null' items: description: Returned records. Source coverage and completeness vary. type: - array items: description: Optional record supplied by this operation. Null means unknown. type: object properties: avatar_url: description: Optional avatar url supplied by this operation. Null means unknown. type: - string - 'null' bio: description: Optional bio supplied by this operation. Null means unknown. type: - string - 'null' followers: description: Optional followers supplied by this operation. Null means unknown. type: - number - 'null' following: description: Optional following supplied by this operation. Null means unknown. type: - number - 'null' handle: description: Optional handle supplied by this operation. Null means unknown. type: - string - 'null' id: description: Source identifier. Preserve the supplied type and exact value. type: - string - 'null' language: description: Optional language supplied by this operation. Null means unknown. type: - string - 'null' name: description: Optional name supplied by this operation. Null means unknown. type: - string - 'null' platform: description: Optional platform supplied by this operation. Null means unknown. type: - string - 'null' region: description: Optional region supplied by this operation. Null means unknown. type: - string - 'null' additionalProperties: true allOf: - anyOf: - required: - avatar_url properties: avatar_url: description: Optional avatar url supplied by this operation. Null means unknown. type: - string minLength: 1 - required: - bio properties: bio: description: Optional bio supplied by this operation. Null means unknown. type: - string minLength: 1 - required: - followers properties: followers: description: Optional followers supplied by this operation. Null means unknown. type: - number - required: - following properties: following: description: Optional following supplied by this operation. Null means unknown. type: - number - required: - handle properties: handle: description: Optional handle supplied by this operation. Null means unknown. type: - string minLength: 1 - required: - id properties: id: description: Source identifier. Preserve the supplied type and exact value. type: - string minLength: 1 - required: - language properties: language: description: Optional language supplied by this operation. Null means unknown. type: - string minLength: 1 - required: - name properties: name: description: Optional name supplied by this operation. Null means unknown. type: - string minLength: 1 - required: - region properties: region: description: Optional region supplied by this operation. Null means unknown. type: - string minLength: 1 additionalProperties: true required: - items x-contract-version: '2026-09-22' x-validation-scope: Required success payload structure; optional fields and source completeness remain separate. examples: - cursor: null dropped: 0 items: - avatar_url: https://example.com/example bio: example followers: 0 following: 0 handle: example id: example language: example name: example platform: example region: example default: description: The error envelope — the same shape for every non-2xx status. content: application/json: schema: $ref: '#/components/schemas/Error' x-credits: 1 x-production-available: true x-capacity: status: not_assessed message: Capacity is workload-dependent; configured routes do not establish sustained throughput or an availability guarantee. x-availability-scope: Structural check of the effective registered chain, production permission, adapter, configured cost and quality floor without request parameters. True is not a live-health, credential, quota, subscription-entitlement, complete-data or deployment-exposure guarantee. False means no structurally eligible candidate; null means metadata could not establish availability. Composite child capability still depends on its component routes. x-live-proven: true /v1/tiktok/user-following: get: operationId: tiktok_user_following tags: - tiktok summary: Following description: The accounts a TikTok user follows. Paged by min_time cursor. Costs 1 credit per successful live response. parameters: - name: handle in: query required: true schema: type: string example: stoolpresidente description: TikTok username without the @. An optional leading @ is accepted and removed before lookup. - name: cursor in: query required: false schema: type: string description: min_time value from the previous page. - name: dry_run in: query required: false schema: type: string enum: - '1' - '0' - 'true' - 'false' example: '1' description: 'Read a zero-credit estimate without fetching sources, running AI, or reserving credits. Cache status is a snapshot, not a guarantee at execution. Accepted values: 1, 0, true, false. Case, spaces, hyphens and underscores are interchangeable.' - name: X-Max-Credits in: header required: false schema: type: integer minimum: 0 maximum: 9007199254740991 example: 5 description: Optional credit reservation ceiling for this individual request. Send a non-negative integer in decimal digits. Live execution checks the required reservation after resolving free cache hits or buffered continuation, before charging or calling a supplier. A higher reservation returns HTTP 422 INVALID_PARAMETERS with reason max_credits_exceeded and charges nothing. Invalid header values also return 422. Zero permits only a zero-credit reservation; omitting the header uses normal pricing. dry_run remains a free preview. This does not cap later requests, batches or scheduled runs. security: - ApiKeyHeader: [] - BearerKey: [] responses: '200': description: 'The common success envelope; `data` is endpoint-specific. Many lists use items/count/cursor; bundles use named collections and their documented continuation metadata. HTTP 200 can contain a partial bundle: inspect complete, partial and legs where supplied.' content: application/json: schema: allOf: - $ref: '#/components/schemas/Success' - type: object properties: data: $schema: https://json-schema.org/draft/2020-12/schema $id: https://www.monocrawl.com/schemas/tiktok/user-following.json title: tiktok/user-following data fields description: Optional data supplied by this operation. Null means unknown. type: object properties: cursor: description: Opaque next-page token; pass it back unchanged. Null does not prove complete history. type: - string - 'null' dropped: description: Optional dropped supplied by this operation. Null means unknown. type: - number - 'null' items: description: Returned records. Source coverage and completeness vary. type: - array items: description: Optional record supplied by this operation. Null means unknown. type: object properties: avatar_url: description: Optional avatar url supplied by this operation. Null means unknown. type: - string - 'null' bio: description: Optional bio supplied by this operation. Null means unknown. type: - string - 'null' followers: description: Optional followers supplied by this operation. Null means unknown. type: - number - 'null' following: description: Optional following supplied by this operation. Null means unknown. type: - number - 'null' handle: description: Optional handle supplied by this operation. Null means unknown. type: - string - 'null' id: description: Source identifier. Preserve the supplied type and exact value. type: - string - 'null' language: description: Optional language supplied by this operation. Null means unknown. type: - string - 'null' name: description: Optional name supplied by this operation. Null means unknown. type: - string - 'null' platform: description: Optional platform supplied by this operation. Null means unknown. type: - string - 'null' region: description: Optional region supplied by this operation. Null means unknown. type: - string - 'null' additionalProperties: true allOf: - anyOf: - required: - avatar_url properties: avatar_url: description: Optional avatar url supplied by this operation. Null means unknown. type: - string minLength: 1 - required: - bio properties: bio: description: Optional bio supplied by this operation. Null means unknown. type: - string minLength: 1 - required: - followers properties: followers: description: Optional followers supplied by this operation. Null means unknown. type: - number - required: - following properties: following: description: Optional following supplied by this operation. Null means unknown. type: - number - required: - handle properties: handle: description: Optional handle supplied by this operation. Null means unknown. type: - string minLength: 1 - required: - id properties: id: description: Source identifier. Preserve the supplied type and exact value. type: - string minLength: 1 - required: - language properties: language: description: Optional language supplied by this operation. Null means unknown. type: - string minLength: 1 - required: - name properties: name: description: Optional name supplied by this operation. Null means unknown. type: - string minLength: 1 - required: - region properties: region: description: Optional region supplied by this operation. Null means unknown. type: - string minLength: 1 additionalProperties: true required: - items x-contract-version: '2026-09-22' x-validation-scope: Required success payload structure; optional fields and source completeness remain separate. examples: - cursor: null dropped: 0 items: - avatar_url: https://example.com/example bio: example followers: 0 following: 0 handle: example id: example language: example name: example platform: example region: example default: description: The error envelope — the same shape for every non-2xx status. content: application/json: schema: $ref: '#/components/schemas/Error' x-credits: 1 x-production-available: true x-capacity: status: not_assessed message: Capacity is workload-dependent; configured routes do not establish sustained throughput or an availability guarantee. x-availability-scope: Structural check of the effective registered chain, production permission, adapter, configured cost and quality floor without request parameters. True is not a live-health, credential, quota, subscription-entitlement, complete-data or deployment-exposure guarantee. False means no structurally eligible candidate; null means metadata could not establish availability. Composite child capability still depends on its component routes. x-live-proven: true /v1/tiktok/user-liked-videos: get: operationId: tiktok_user_liked_videos tags: - tiktok summary: TikTok liked videos description: Videos an account has liked, when it shows its likes publicly; empty otherwise. Same video shape as the profile-videos route. Costs 1 credit per successful live response. parameters: - name: handle in: query required: false schema: type: string example: tiktok description: TikTok username without the @ (or pass sec_uid) An optional leading @ is accepted and removed before lookup. - name: sec_uid in: query required: false schema: type: string example: '' description: The account's secUid — alternative to handle - name: cursor in: query required: false schema: type: string example: '' description: Cursor from the previous page - name: limit in: query required: false schema: type: string example: '30' description: Videos per page, at most 35 - name: dry_run in: query required: false schema: type: string enum: - '1' - '0' - 'true' - 'false' example: '1' description: 'Read a zero-credit estimate without fetching sources, running AI, or reserving credits. Cache status is a snapshot, not a guarantee at execution. Accepted values: 1, 0, true, false. Case, spaces, hyphens and underscores are interchangeable.' - name: judgments in: query required: false schema: type: string enum: - 'on' - 'off' example: 'on' description: 'Add bounded AI labels to eligible returned records (default on). off preserves the original data shape. Unclassified records remain present; labels depend on evidence, time, capacity and the existing request budget. No label surcharge. Accepted values: on, off. Case, spaces, hyphens and underscores are interchangeable.' - name: label in: query required: false schema: type: string enum: - default - none example: none description: 'Set none to disable labels; default enables the endpoint’s label set. Equivalent to judgments=off. Accepted values: default, none. Case, spaces, hyphens and underscores are interchangeable.' - name: label_evidence in: query required: false schema: type: string enum: - '1' - '0' - 'true' - 'false' example: '1' description: 'Include exact supporting sentences and zero-based sentence indexes when a label has validated evidence. No extra charge or change to decisions. Accepted values: 1, 0, true, false. Case, spaces, hyphens and underscores are interchangeable.' - name: exclude in: query required: false schema: type: string enum: - engagement_bait example: engagement_bait description: 'Optionally remove confidently labelled engagement bait. Uncertain and unclassified records stay; removed IDs and an owner-bound recall reference are returned. Accepted values: engagement_bait. Case, spaces, hyphens and underscores are interchangeable.' - name: fit in: query required: false schema: type: string enum: - goal example: goal description: 'Use goal to replace confidently irrelevant records with recall stubs. Keeps first, last, relevant and uncertain records; preserves order. Full evidence is stored for 24 hours when available. Accepted values: goal. Case, spaces, hyphens and underscores are interchangeable.' - name: goal in: query required: false schema: type: string example: Find concrete product complaints description: 'Required with fit=goal: describe the task in at most 600 characters. Supplied text is task context, never permission to act on posts.' - name: tokens in: query required: false schema: type: string example: '4000' description: Optional soft response target for fit=goal, 256–32000. Safety and evidence retention take priority, so the returned result may exceed it. - name: X-Max-Credits in: header required: false schema: type: integer minimum: 0 maximum: 9007199254740991 example: 5 description: Optional credit reservation ceiling for this individual request. Send a non-negative integer in decimal digits. Live execution checks the required reservation after resolving free cache hits or buffered continuation, before charging or calling a supplier. A higher reservation returns HTTP 422 INVALID_PARAMETERS with reason max_credits_exceeded and charges nothing. Invalid header values also return 422. Zero permits only a zero-credit reservation; omitting the header uses normal pricing. dry_run remains a free preview. This does not cap later requests, batches or scheduled runs. security: - ApiKeyHeader: [] - BearerKey: [] responses: '200': description: 'The common success envelope; `data` is endpoint-specific. Many lists use items/count/cursor; bundles use named collections and their documented continuation metadata. HTTP 200 can contain a partial bundle: inspect complete, partial and legs where supplied.' content: application/json: schema: allOf: - $ref: '#/components/schemas/Success' - type: object properties: data: $schema: https://json-schema.org/draft/2020-12/schema $id: https://www.monocrawl.com/schemas/tiktok/user-liked-videos.json title: tiktok/user-liked-videos data fields description: Optional data supplied by this operation. Null means unknown. type: object properties: _meta: description: Optional meta supplied by this operation. Null means unknown. type: - object - 'null' properties: billing: description: Optional billing supplied by this operation. Null means unknown. type: - object - 'null' properties: charged: description: Optional charged supplied by this operation. Null means unknown. type: - number - 'null' list_price: description: Optional list price supplied by this operation. Null means unknown. type: - number - 'null' reason: description: Optional reason supplied by this operation. Null means unknown. type: - string - 'null' additionalProperties: true additionalProperties: true count: description: Number of records in this response, not lifetime or total matches. type: - number - 'null' cursor: description: Opaque next-page token; pass it back unchanged. Null does not prove complete history. type: - string - 'null' dropped: description: Optional dropped supplied by this operation. Null means unknown. type: - number - 'null' has_more: description: Source continuation indicator; null means unknown. type: - boolean - 'null' items: description: Source array was empty in the reviewed captures; item fields remain unspecified. type: - array items: {} additionalProperties: true required: - items x-contract-version: '2026-09-22' x-validation-scope: Required success payload structure; optional fields and source completeness remain separate. examples: - _meta: billing: charged: 0 list_price: 0 reason: example count: 0 cursor: null dropped: 0 has_more: false items: [] default: description: The error envelope — the same shape for every non-2xx status. content: application/json: schema: $ref: '#/components/schemas/Error' x-credits: 1 x-production-available: true x-capacity: status: not_assessed message: Capacity is workload-dependent; configured routes do not establish sustained throughput or an availability guarantee. x-availability-scope: Structural check of the effective registered chain, production permission, adapter, configured cost and quality floor without request parameters. True is not a live-health, credential, quota, subscription-entitlement, complete-data or deployment-exposure guarantee. False means no structurally eligible candidate; null means metadata could not establish availability. Composite child capability still depends on its component routes. x-live-proven: true /v1/tiktok/user-live: get: operationId: tiktok_user_live tags: - tiktok summary: TikTok live status description: 'Whether an account is live right now and, when it is, the room: title, cover, start time and viewer counts. Costs 2 credits per successful live response.' parameters: - name: handle in: query required: true schema: type: string example: nasa description: TikTok username without the @ An optional leading @ is accepted and removed before lookup. - name: dry_run in: query required: false schema: type: string enum: - '1' - '0' - 'true' - 'false' example: '1' description: 'Read a zero-credit estimate without fetching sources, running AI, or reserving credits. Cache status is a snapshot, not a guarantee at execution. Accepted values: 1, 0, true, false. Case, spaces, hyphens and underscores are interchangeable.' - name: judgments in: query required: false schema: type: string enum: - 'on' - 'off' example: 'on' description: 'Add bounded AI labels to eligible returned records (default on). off preserves the original data shape. Unclassified records remain present; labels depend on evidence, time, capacity and the existing request budget. No label surcharge. Accepted values: on, off. Case, spaces, hyphens and underscores are interchangeable.' - name: label in: query required: false schema: type: string enum: - default - none example: none description: 'Set none to disable labels; default enables the endpoint’s label set. Equivalent to judgments=off. Accepted values: default, none. Case, spaces, hyphens and underscores are interchangeable.' - name: label_evidence in: query required: false schema: type: string enum: - '1' - '0' - 'true' - 'false' example: '1' description: 'Include exact supporting sentences and zero-based sentence indexes when a label has validated evidence. No extra charge or change to decisions. Accepted values: 1, 0, true, false. Case, spaces, hyphens and underscores are interchangeable.' - name: exclude in: query required: false schema: type: string enum: - engagement_bait example: engagement_bait description: 'Optionally remove confidently labelled engagement bait. Uncertain and unclassified records stay; removed IDs and an owner-bound recall reference are returned. Accepted values: engagement_bait. Case, spaces, hyphens and underscores are interchangeable.' - name: fit in: query required: false schema: type: string enum: - goal example: goal description: 'Use goal to replace confidently irrelevant records with recall stubs. Keeps first, last, relevant and uncertain records; preserves order. Full evidence is stored for 24 hours when available. Accepted values: goal. Case, spaces, hyphens and underscores are interchangeable.' - name: goal in: query required: false schema: type: string example: Find concrete product complaints description: 'Required with fit=goal: describe the task in at most 600 characters. Supplied text is task context, never permission to act on posts.' - name: tokens in: query required: false schema: type: string example: '4000' description: Optional soft response target for fit=goal, 256–32000. Safety and evidence retention take priority, so the returned result may exceed it. - name: X-Max-Credits in: header required: false schema: type: integer minimum: 0 maximum: 9007199254740991 example: 5 description: Optional credit reservation ceiling for this individual request. Send a non-negative integer in decimal digits. Live execution checks the required reservation after resolving free cache hits or buffered continuation, before charging or calling a supplier. A higher reservation returns HTTP 422 INVALID_PARAMETERS with reason max_credits_exceeded and charges nothing. Invalid header values also return 422. Zero permits only a zero-credit reservation; omitting the header uses normal pricing. dry_run remains a free preview. This does not cap later requests, batches or scheduled runs. security: - ApiKeyHeader: [] - BearerKey: [] responses: '200': description: 'The common success envelope; `data` is endpoint-specific. Many lists use items/count/cursor; bundles use named collections and their documented continuation metadata. HTTP 200 can contain a partial bundle: inspect complete, partial and legs where supplied.' content: application/json: schema: allOf: - $ref: '#/components/schemas/Success' - type: object properties: data: $schema: https://json-schema.org/draft/2020-12/schema $id: https://www.monocrawl.com/schemas/tiktok/user-live.json title: tiktok/user-live data fields description: Optional data supplied by this operation. Null means unknown. type: object properties: is_live: description: Optional is live supplied by this operation. Null means unknown. type: - boolean - 'null' platform: description: Optional platform supplied by this operation. Null means unknown. type: - string - 'null' room: description: Optional room supplied by this operation. Null means unknown. type: - object - 'null' properties: cover_url: description: Optional cover url supplied by this operation. Null means unknown. type: - string - 'null' id: description: Source identifier. Preserve the supplied type and exact value. type: - string - 'null' mode: description: Optional mode supplied by this operation. Null means unknown. type: - number - 'null' started_at: description: Optional started at supplied by this operation. Null means unknown. type: - string - 'null' status: description: Optional status supplied by this operation. Null means unknown. type: - number - 'null' subscribers_only: description: Optional subscribers only supplied by this operation. Null means unknown. type: - boolean - 'null' total_entered: description: Optional total entered supplied by this operation. Null means unknown. type: - number - 'null' viewers: description: Optional viewers supplied by this operation. Null means unknown. type: - number - 'null' additionalProperties: true user: description: Optional user supplied by this operation. Null means unknown. type: - object - 'null' properties: avatar_url: description: Optional avatar url supplied by this operation. Null means unknown. type: - string - 'null' bio: description: Optional bio supplied by this operation. Null means unknown. type: - string - 'null' followers: description: Optional followers supplied by this operation. Null means unknown. type: - number - 'null' following: description: Optional following supplied by this operation. Null means unknown. type: - number - 'null' handle: description: Optional handle supplied by this operation. Null means unknown. type: - string - 'null' id: description: Source identifier. Preserve the supplied type and exact value. type: - string - 'null' name: description: Optional name supplied by this operation. Null means unknown. type: - string - 'null' verified: description: Optional verified supplied by this operation. Null means unknown. type: - boolean - 'null' additionalProperties: true additionalProperties: true allOf: - anyOf: - required: - is_live properties: is_live: description: Optional is live supplied by this operation. Null means unknown. type: - boolean - required: - room properties: room: description: Optional room supplied by this operation. Null means unknown. type: - object properties: cover_url: description: Optional cover url supplied by this operation. Null means unknown. type: - string - 'null' id: description: Source identifier. Preserve the supplied type and exact value. type: - string - 'null' mode: description: Optional mode supplied by this operation. Null means unknown. type: - number - 'null' started_at: description: Optional started at supplied by this operation. Null means unknown. type: - string - 'null' status: description: Optional status supplied by this operation. Null means unknown. type: - number - 'null' subscribers_only: description: Optional subscribers only supplied by this operation. Null means unknown. type: - boolean - 'null' total_entered: description: Optional total entered supplied by this operation. Null means unknown. type: - number - 'null' viewers: description: Optional viewers supplied by this operation. Null means unknown. type: - number - 'null' additionalProperties: true - required: - user properties: user: description: Optional user supplied by this operation. Null means unknown. type: - object properties: avatar_url: description: Optional avatar url supplied by this operation. Null means unknown. type: - string - 'null' bio: description: Optional bio supplied by this operation. Null means unknown. type: - string - 'null' followers: description: Optional followers supplied by this operation. Null means unknown. type: - number - 'null' following: description: Optional following supplied by this operation. Null means unknown. type: - number - 'null' handle: description: Optional handle supplied by this operation. Null means unknown. type: - string - 'null' id: description: Source identifier. Preserve the supplied type and exact value. type: - string - 'null' name: description: Optional name supplied by this operation. Null means unknown. type: - string - 'null' verified: description: Optional verified supplied by this operation. Null means unknown. type: - boolean - 'null' additionalProperties: true x-contract-version: '2026-09-22' x-validation-scope: Required success payload structure; optional fields and source completeness remain separate. examples: - is_live: false platform: example room: cover_url: https://example.com/example id: example mode: 0 started_at: '2026-09-01T12:00:00Z' status: 0 subscribers_only: false total_entered: 0 viewers: 0 user: avatar_url: https://example.com/example bio: example followers: 0 following: 0 handle: example id: example name: example verified: false default: description: The error envelope — the same shape for every non-2xx status. content: application/json: schema: $ref: '#/components/schemas/Error' x-credits: 2 x-production-available: true x-capacity: status: not_assessed message: Capacity is workload-dependent; configured routes do not establish sustained throughput or an availability guarantee. x-availability-scope: Structural check of the effective registered chain, production permission, adapter, configured cost and quality floor without request parameters. True is not a live-health, credential, quota, subscription-entitlement, complete-data or deployment-exposure guarantee. False means no structurally eligible candidate; null means metadata could not establish availability. Composite child capability still depends on its component routes. x-live-proven: true /v1/tiktok/user-playlists: get: operationId: tiktok_user_playlists tags: - tiktok summary: TikTok playlists description: 'The playlists a creator has published: name, video count, cover and URL; paged by cursor. Costs 1 credit per successful live response.' parameters: - name: handle in: query required: false schema: type: string example: tiktok description: TikTok username without the @ (or pass sec_uid) An optional leading @ is accepted and removed before lookup. - name: sec_uid in: query required: false schema: type: string example: '' description: The account's secUid — alternative to handle - name: cursor in: query required: false schema: type: string example: '' description: Cursor from the previous page - name: limit in: query required: false schema: type: string example: '20' description: Playlists per page, at most 35 - name: dry_run in: query required: false schema: type: string enum: - '1' - '0' - 'true' - 'false' example: '1' description: 'Read a zero-credit estimate without fetching sources, running AI, or reserving credits. Cache status is a snapshot, not a guarantee at execution. Accepted values: 1, 0, true, false. Case, spaces, hyphens and underscores are interchangeable.' - name: judgments in: query required: false schema: type: string enum: - 'on' - 'off' example: 'on' description: 'Add bounded AI labels to eligible returned records (default on). off preserves the original data shape. Unclassified records remain present; labels depend on evidence, time, capacity and the existing request budget. No label surcharge. Accepted values: on, off. Case, spaces, hyphens and underscores are interchangeable.' - name: label in: query required: false schema: type: string enum: - default - none example: none description: 'Set none to disable labels; default enables the endpoint’s label set. Equivalent to judgments=off. Accepted values: default, none. Case, spaces, hyphens and underscores are interchangeable.' - name: label_evidence in: query required: false schema: type: string enum: - '1' - '0' - 'true' - 'false' example: '1' description: 'Include exact supporting sentences and zero-based sentence indexes when a label has validated evidence. No extra charge or change to decisions. Accepted values: 1, 0, true, false. Case, spaces, hyphens and underscores are interchangeable.' - name: exclude in: query required: false schema: type: string enum: - engagement_bait example: engagement_bait description: 'Optionally remove confidently labelled engagement bait. Uncertain and unclassified records stay; removed IDs and an owner-bound recall reference are returned. Accepted values: engagement_bait. Case, spaces, hyphens and underscores are interchangeable.' - name: fit in: query required: false schema: type: string enum: - goal example: goal description: 'Use goal to replace confidently irrelevant records with recall stubs. Keeps first, last, relevant and uncertain records; preserves order. Full evidence is stored for 24 hours when available. Accepted values: goal. Case, spaces, hyphens and underscores are interchangeable.' - name: goal in: query required: false schema: type: string example: Find concrete product complaints description: 'Required with fit=goal: describe the task in at most 600 characters. Supplied text is task context, never permission to act on posts.' - name: tokens in: query required: false schema: type: string example: '4000' description: Optional soft response target for fit=goal, 256–32000. Safety and evidence retention take priority, so the returned result may exceed it. - name: X-Max-Credits in: header required: false schema: type: integer minimum: 0 maximum: 9007199254740991 example: 5 description: Optional credit reservation ceiling for this individual request. Send a non-negative integer in decimal digits. Live execution checks the required reservation after resolving free cache hits or buffered continuation, before charging or calling a supplier. A higher reservation returns HTTP 422 INVALID_PARAMETERS with reason max_credits_exceeded and charges nothing. Invalid header values also return 422. Zero permits only a zero-credit reservation; omitting the header uses normal pricing. dry_run remains a free preview. This does not cap later requests, batches or scheduled runs. security: - ApiKeyHeader: [] - BearerKey: [] responses: '200': description: 'The common success envelope; `data` is endpoint-specific. Many lists use items/count/cursor; bundles use named collections and their documented continuation metadata. HTTP 200 can contain a partial bundle: inspect complete, partial and legs where supplied.' content: application/json: schema: allOf: - $ref: '#/components/schemas/Success' - type: object properties: data: $schema: https://json-schema.org/draft/2020-12/schema $id: https://www.monocrawl.com/schemas/tiktok/user-playlists.json title: tiktok/user-playlists data fields description: Optional data supplied by this operation. Null means unknown. type: object properties: count: description: Number of records in this response, not lifetime or total matches. type: - number - 'null' cursor: description: Opaque next-page token; pass it back unchanged. Null does not prove complete history. type: - string - 'null' dropped: description: Optional dropped supplied by this operation. Null means unknown. type: - number - 'null' has_more: description: Source continuation indicator; null means unknown. type: - boolean - 'null' items: description: Returned records. Source coverage and completeness vary. type: - array items: description: Optional record supplied by this operation. Null means unknown. type: object properties: cover_url: description: Optional cover url supplied by this operation. Null means unknown. type: - string - 'null' id: description: Source identifier. Preserve the supplied type and exact value. type: - string - 'null' name: description: Optional name supplied by this operation. Null means unknown. type: - string - 'null' platform: description: Optional platform supplied by this operation. Null means unknown. type: - string - 'null' url: description: Original source URL when supplied. type: - string - 'null' video_count: description: Optional video count supplied by this operation. Null means unknown. type: - number - 'null' additionalProperties: true allOf: - anyOf: - required: - cover_url properties: cover_url: description: Optional cover url supplied by this operation. Null means unknown. type: - string minLength: 1 - required: - id properties: id: description: Source identifier. Preserve the supplied type and exact value. type: - string minLength: 1 - required: - name properties: name: description: Optional name supplied by this operation. Null means unknown. type: - string minLength: 1 - required: - url properties: url: description: Original source URL when supplied. type: - string minLength: 1 - required: - video_count properties: video_count: description: Optional video count supplied by this operation. Null means unknown. type: - number additionalProperties: true required: - items x-contract-version: '2026-09-22' x-validation-scope: Required success payload structure; optional fields and source completeness remain separate. examples: - count: 0 cursor: null dropped: 0 has_more: false items: - cover_url: https://example.com/example id: example name: example platform: example url: https://example.com/example video_count: 0 default: description: The error envelope — the same shape for every non-2xx status. content: application/json: schema: $ref: '#/components/schemas/Error' x-credits: 1 x-production-available: true x-capacity: status: not_assessed message: Capacity is workload-dependent; configured routes do not establish sustained throughput or an availability guarantee. x-availability-scope: Structural check of the effective registered chain, production permission, adapter, configured cost and quality floor without request parameters. True is not a live-health, credential, quota, subscription-entitlement, complete-data or deployment-exposure guarantee. False means no structurally eligible candidate; null means metadata could not establish availability. Composite child capability still depends on its component routes. x-live-proven: true /v1/tiktok/user-reposts: get: operationId: tiktok_user_reposts tags: - tiktok summary: TikTok reposts description: Videos an account has reposted, newest first; paged by cursor. Costs 1 credit per successful live response. parameters: - name: handle in: query required: false schema: type: string example: tiktok description: TikTok username without the @ (or pass sec_uid) An optional leading @ is accepted and removed before lookup. - name: sec_uid in: query required: false schema: type: string example: '' description: The account's secUid — alternative to handle - name: cursor in: query required: false schema: type: string example: '' description: Cursor from the previous page - name: limit in: query required: false schema: type: string example: '30' description: Videos per page, at most 35 - name: dry_run in: query required: false schema: type: string enum: - '1' - '0' - 'true' - 'false' example: '1' description: 'Read a zero-credit estimate without fetching sources, running AI, or reserving credits. Cache status is a snapshot, not a guarantee at execution. Accepted values: 1, 0, true, false. Case, spaces, hyphens and underscores are interchangeable.' - name: judgments in: query required: false schema: type: string enum: - 'on' - 'off' example: 'on' description: 'Add bounded AI labels to eligible returned records (default on). off preserves the original data shape. Unclassified records remain present; labels depend on evidence, time, capacity and the existing request budget. No label surcharge. Accepted values: on, off. Case, spaces, hyphens and underscores are interchangeable.' - name: label in: query required: false schema: type: string enum: - default - none example: none description: 'Set none to disable labels; default enables the endpoint’s label set. Equivalent to judgments=off. Accepted values: default, none. Case, spaces, hyphens and underscores are interchangeable.' - name: label_evidence in: query required: false schema: type: string enum: - '1' - '0' - 'true' - 'false' example: '1' description: 'Include exact supporting sentences and zero-based sentence indexes when a label has validated evidence. No extra charge or change to decisions. Accepted values: 1, 0, true, false. Case, spaces, hyphens and underscores are interchangeable.' - name: exclude in: query required: false schema: type: string enum: - engagement_bait example: engagement_bait description: 'Optionally remove confidently labelled engagement bait. Uncertain and unclassified records stay; removed IDs and an owner-bound recall reference are returned. Accepted values: engagement_bait. Case, spaces, hyphens and underscores are interchangeable.' - name: fit in: query required: false schema: type: string enum: - goal example: goal description: 'Use goal to replace confidently irrelevant records with recall stubs. Keeps first, last, relevant and uncertain records; preserves order. Full evidence is stored for 24 hours when available. Accepted values: goal. Case, spaces, hyphens and underscores are interchangeable.' - name: goal in: query required: false schema: type: string example: Find concrete product complaints description: 'Required with fit=goal: describe the task in at most 600 characters. Supplied text is task context, never permission to act on posts.' - name: tokens in: query required: false schema: type: string example: '4000' description: Optional soft response target for fit=goal, 256–32000. Safety and evidence retention take priority, so the returned result may exceed it. - name: X-Max-Credits in: header required: false schema: type: integer minimum: 0 maximum: 9007199254740991 example: 5 description: Optional credit reservation ceiling for this individual request. Send a non-negative integer in decimal digits. Live execution checks the required reservation after resolving free cache hits or buffered continuation, before charging or calling a supplier. A higher reservation returns HTTP 422 INVALID_PARAMETERS with reason max_credits_exceeded and charges nothing. Invalid header values also return 422. Zero permits only a zero-credit reservation; omitting the header uses normal pricing. dry_run remains a free preview. This does not cap later requests, batches or scheduled runs. security: - ApiKeyHeader: [] - BearerKey: [] responses: '200': description: 'The common success envelope; `data` is endpoint-specific. Many lists use items/count/cursor; bundles use named collections and their documented continuation metadata. HTTP 200 can contain a partial bundle: inspect complete, partial and legs where supplied.' content: application/json: schema: allOf: - $ref: '#/components/schemas/Success' - type: object properties: data: $schema: https://json-schema.org/draft/2020-12/schema $id: https://www.monocrawl.com/schemas/tiktok/user-reposts.json title: tiktok/user-reposts data fields description: Optional data supplied by this operation. Null means unknown. type: object properties: count: description: Number of records in this response, not lifetime or total matches. type: - number - 'null' cursor: description: Opaque next-page token; pass it back unchanged. Null does not prove complete history. type: - string - 'null' dropped: description: Optional dropped supplied by this operation. Null means unknown. type: - number - 'null' has_more: description: Source continuation indicator; null means unknown. type: - boolean - 'null' items: description: Returned records. Source coverage and completeness vary. type: - array items: description: Optional record supplied by this operation. Null means unknown. type: object properties: author: description: Public author information supplied with this record. type: - object - 'null' properties: avatar_url: description: Optional avatar url supplied by this operation. Null means unknown. type: - string - 'null' followers: description: Optional followers supplied by this operation. Null means unknown. type: - number - 'null' handle: description: Optional handle supplied by this operation. Null means unknown. type: - string - 'null' id: description: Source identifier. Preserve the supplied type and exact value. type: - string - 'null' name: description: Optional name supplied by this operation. Null means unknown. type: - string - 'null' private: description: Optional private supplied by this operation. Null means unknown. type: - boolean - 'null' verified: description: Optional verified supplied by this operation. Null means unknown. type: - boolean - 'null' additionalProperties: true caption: description: Optional caption supplied by this operation. Null means unknown. type: - string - 'null' created_at: description: Source creation time, not the API retrieval time. type: - string - 'null' duration_s: description: Optional duration s supplied by this operation. Null means unknown. type: - number - 'null' hashtags: description: Optional hashtags supplied by this operation. Null means unknown. type: - array - 'null' items: description: Optional record supplied by this operation. Null means unknown. type: - object - 'null' properties: {} additionalProperties: true id: description: Source identifier. Preserve the supplied type and exact value. type: - string - 'null' images: description: Source array was empty in the reviewed captures; item fields remain unspecified. type: - array - 'null' items: {} is_ad: description: Optional is ad supplied by this operation. Null means unknown. type: - boolean - 'null' media_urls: description: Optional media urls supplied by this operation. Null means unknown. type: - array - 'null' items: description: Optional record supplied by this operation. Null means unknown. type: - string - 'null' music: description: Optional music supplied by this operation. Null means unknown. type: - object - 'null' properties: album: description: Optional album supplied by this operation. Null means unknown. type: - string - 'null' author: description: Public author information supplied with this record. type: - string - 'null' cover_url: description: Optional cover url supplied by this operation. Null means unknown. type: - string - 'null' duration_s: description: Optional duration s supplied by this operation. Null means unknown. type: - number - 'null' id: description: Source identifier. Preserve the supplied type and exact value. type: - string - 'null' is_original: description: Optional is original supplied by this operation. Null means unknown. type: - boolean - 'null' play_url: description: Optional play url supplied by this operation. Null means unknown. type: - string - 'null' title: description: Source title when supplied. type: - string - 'null' additionalProperties: true platform: description: Optional platform supplied by this operation. Null means unknown. type: - string - 'null' stats: description: Optional stats supplied by this operation. Null means unknown. type: - object - 'null' properties: comments: description: Optional comments supplied by this operation. Null means unknown. type: - number - 'null' likes: description: Optional likes supplied by this operation. Null means unknown. type: - number - 'null' plays: description: Optional plays supplied by this operation. Null means unknown. type: - number - 'null' saves: description: Optional saves supplied by this operation. Null means unknown. type: - number - 'null' shares: description: Optional shares supplied by this operation. Null means unknown. type: - number - 'null' additionalProperties: true thumbnail_url: description: Optional thumbnail url supplied by this operation. Null means unknown. type: - string - 'null' url: description: Original source URL when supplied. type: - string - 'null' video_url: description: Optional video url supplied by this operation. Null means unknown. type: - string - 'null' additionalProperties: true allOf: - anyOf: - required: - author properties: author: description: Public author information supplied with this record. type: - object properties: avatar_url: description: Optional avatar url supplied by this operation. Null means unknown. type: - string - 'null' followers: description: Optional followers supplied by this operation. Null means unknown. type: - number - 'null' handle: description: Optional handle supplied by this operation. Null means unknown. type: - string - 'null' id: description: Source identifier. Preserve the supplied type and exact value. type: - string - 'null' name: description: Optional name supplied by this operation. Null means unknown. type: - string - 'null' private: description: Optional private supplied by this operation. Null means unknown. type: - boolean - 'null' verified: description: Optional verified supplied by this operation. Null means unknown. type: - boolean - 'null' additionalProperties: true - required: - caption properties: caption: description: Optional caption supplied by this operation. Null means unknown. type: - string minLength: 1 - required: - created_at properties: created_at: description: Source creation time, not the API retrieval time. type: - string minLength: 1 - required: - duration_s properties: duration_s: description: Optional duration s supplied by this operation. Null means unknown. type: - number - required: - hashtags properties: hashtags: description: Optional hashtags supplied by this operation. Null means unknown. type: - array items: description: Optional record supplied by this operation. Null means unknown. type: - object - 'null' properties: {} additionalProperties: true - required: - id properties: id: description: Source identifier. Preserve the supplied type and exact value. type: - string minLength: 1 - required: - images properties: images: description: Source array was empty in the reviewed captures; item fields remain unspecified. type: - array items: {} - required: - is_ad properties: is_ad: description: Optional is ad supplied by this operation. Null means unknown. type: - boolean - required: - media_urls properties: media_urls: description: Optional media urls supplied by this operation. Null means unknown. type: - array items: description: Optional record supplied by this operation. Null means unknown. type: - string - 'null' - required: - music properties: music: description: Optional music supplied by this operation. Null means unknown. type: - object properties: album: description: Optional album supplied by this operation. Null means unknown. type: - string - 'null' author: description: Public author information supplied with this record. type: - string - 'null' cover_url: description: Optional cover url supplied by this operation. Null means unknown. type: - string - 'null' duration_s: description: Optional duration s supplied by this operation. Null means unknown. type: - number - 'null' id: description: Source identifier. Preserve the supplied type and exact value. type: - string - 'null' is_original: description: Optional is original supplied by this operation. Null means unknown. type: - boolean - 'null' play_url: description: Optional play url supplied by this operation. Null means unknown. type: - string - 'null' title: description: Source title when supplied. type: - string - 'null' additionalProperties: true - required: - stats properties: stats: description: Optional stats supplied by this operation. Null means unknown. type: - object properties: comments: description: Optional comments supplied by this operation. Null means unknown. type: - number - 'null' likes: description: Optional likes supplied by this operation. Null means unknown. type: - number - 'null' plays: description: Optional plays supplied by this operation. Null means unknown. type: - number - 'null' saves: description: Optional saves supplied by this operation. Null means unknown. type: - number - 'null' shares: description: Optional shares supplied by this operation. Null means unknown. type: - number - 'null' additionalProperties: true - required: - thumbnail_url properties: thumbnail_url: description: Optional thumbnail url supplied by this operation. Null means unknown. type: - string minLength: 1 - required: - url properties: url: description: Original source URL when supplied. type: - string minLength: 1 - required: - video_url properties: video_url: description: Optional video url supplied by this operation. Null means unknown. type: - string minLength: 1 additionalProperties: true required: - items x-contract-version: '2026-09-22' x-validation-scope: Required success payload structure; optional fields and source completeness remain separate. examples: - count: 0 cursor: null dropped: 0 has_more: false items: - author: avatar_url: https://example.com/example followers: 0 handle: example id: example name: example private: false verified: false caption: example created_at: '2026-09-01T12:00:00Z' duration_s: 0 hashtags: - {} id: example images: [] is_ad: false media_urls: - example music: album: example author: example cover_url: https://example.com/example duration_s: 0 id: example is_original: false play_url: https://example.com/example title: example platform: example stats: comments: 0 likes: 0 plays: 0 saves: 0 shares: 0 thumbnail_url: https://example.com/example url: https://example.com/example video_url: https://example.com/example default: description: The error envelope — the same shape for every non-2xx status. content: application/json: schema: $ref: '#/components/schemas/Error' x-credits: 1 x-production-available: true x-capacity: status: not_assessed message: Capacity is workload-dependent; configured routes do not establish sustained throughput or an availability guarantee. x-availability-scope: Structural check of the effective registered chain, production permission, adapter, configured cost and quality floor without request parameters. True is not a live-health, credential, quota, subscription-entitlement, complete-data or deployment-exposure guarantee. False means no structurally eligible candidate; null means metadata could not establish availability. Composite child capability still depends on its component routes. x-live-proven: true /v1/tiktok/videos-popular: get: operationId: tiktok_videos_popular tags: - tiktok summary: Popular TikTok videos description: Anonymous public top-four recent-video board. Source-period and lifetime views, organic views, engagement and six-second view rate, with creators. May include sponsored content. Not the full ranking; no likes/comments/shares are supplied. Costs 1 credit per successful live response. parameters: - name: country in: query required: false schema: type: string enum: - US - JP - VN - TH - ID example: US description: 'US, JP, VN, TH or ID. Accepted values: US, JP, VN, TH, ID. Case, spaces, hyphens and underscores are interchangeable.' - name: period in: query required: false schema: type: string enum: - '7' - '30' example: '7' description: '7 or 30 days; recent-creation board. Source period end is returned. Accepted values: 7, 30. Case, spaces, hyphens and underscores are interchangeable.' - name: sort in: query required: false schema: type: string enum: - views - engagement - six_second_views example: views description: 'views, engagement or six_second_views. Accepted values: views, engagement, six_second_views. Case, spaces, hyphens and underscores are interchangeable.' - name: limit in: query required: false schema: type: string example: '4' description: 1–4, default 4. Public anonymous sample only; no pagination. - name: dry_run in: query required: false schema: type: string enum: - '1' - '0' - 'true' - 'false' example: '1' description: 'Read a zero-credit estimate without fetching sources, running AI, or reserving credits. Cache status is a snapshot, not a guarantee at execution. Accepted values: 1, 0, true, false. Case, spaces, hyphens and underscores are interchangeable.' - name: judgments in: query required: false schema: type: string enum: - 'on' - 'off' example: 'on' description: 'Add bounded AI labels to eligible returned records (default on). off preserves the original data shape. Unclassified records remain present; labels depend on evidence, time, capacity and the existing request budget. No label surcharge. Accepted values: on, off. Case, spaces, hyphens and underscores are interchangeable.' - name: label in: query required: false schema: type: string enum: - default - none example: none description: 'Set none to disable labels; default enables the endpoint’s label set. Equivalent to judgments=off. Accepted values: default, none. Case, spaces, hyphens and underscores are interchangeable.' - name: label_evidence in: query required: false schema: type: string enum: - '1' - '0' - 'true' - 'false' example: '1' description: 'Include exact supporting sentences and zero-based sentence indexes when a label has validated evidence. No extra charge or change to decisions. Accepted values: 1, 0, true, false. Case, spaces, hyphens and underscores are interchangeable.' - name: exclude in: query required: false schema: type: string enum: - engagement_bait example: engagement_bait description: 'Optionally remove confidently labelled engagement bait. Uncertain and unclassified records stay; removed IDs and an owner-bound recall reference are returned. Accepted values: engagement_bait. Case, spaces, hyphens and underscores are interchangeable.' - name: fit in: query required: false schema: type: string enum: - goal example: goal description: 'Use goal to replace confidently irrelevant records with recall stubs. Keeps first, last, relevant and uncertain records; preserves order. Full evidence is stored for 24 hours when available. Accepted values: goal. Case, spaces, hyphens and underscores are interchangeable.' - name: goal in: query required: false schema: type: string example: Find concrete product complaints description: 'Required with fit=goal: describe the task in at most 600 characters. Supplied text is task context, never permission to act on posts.' - name: tokens in: query required: false schema: type: string example: '4000' description: Optional soft response target for fit=goal, 256–32000. Safety and evidence retention take priority, so the returned result may exceed it. - name: countryCode in: query required: false schema: type: string example: US description: Compatibility alias for country. The canonical parameter takes precedence if both are supplied. - name: X-Max-Credits in: header required: false schema: type: integer minimum: 0 maximum: 9007199254740991 example: 5 description: Optional credit reservation ceiling for this individual request. Send a non-negative integer in decimal digits. Live execution checks the required reservation after resolving free cache hits or buffered continuation, before charging or calling a supplier. A higher reservation returns HTTP 422 INVALID_PARAMETERS with reason max_credits_exceeded and charges nothing. Invalid header values also return 422. Zero permits only a zero-credit reservation; omitting the header uses normal pricing. dry_run remains a free preview. This does not cap later requests, batches or scheduled runs. security: - ApiKeyHeader: [] - BearerKey: [] responses: '200': description: 'The common success envelope; `data` is endpoint-specific. Many lists use items/count/cursor; bundles use named collections and their documented continuation metadata. HTTP 200 can contain a partial bundle: inspect complete, partial and legs where supplied.' content: application/json: schema: allOf: - $ref: '#/components/schemas/Success' - type: object properties: data: $schema: https://json-schema.org/draft/2020-12/schema $id: https://www.monocrawl.com/schemas/tiktok/videos-popular.json title: tiktok/videos-popular data fields description: Optional data supplied by this operation. Null means unknown. type: object properties: _warnings: description: Optional warnings supplied by this operation. Null means unknown. type: - array - 'null' items: description: Optional record supplied by this operation. Null means unknown. type: - string - 'null' count: description: Number of records in this response, not lifetime or total matches. type: - number - 'null' country: description: Optional country supplied by this operation. Null means unknown. type: - string - 'null' coverage: description: Optional coverage supplied by this operation. Null means unknown. type: - string - 'null' has_more: description: Source continuation indicator; null means unknown. type: - boolean - 'null' items: description: Returned records. Source coverage and completeness vary. type: - array items: description: Optional record supplied by this operation. Null means unknown. type: object properties: author: description: Public author information supplied with this record. type: - object - 'null' properties: followers: description: Optional followers supplied by this operation. Null means unknown. type: - number - 'null' handle: description: Optional handle supplied by this operation. Null means unknown. type: - string - 'null' id: description: Source identifier. Preserve the supplied type and exact value. type: - string - 'null' name: description: Optional name supplied by this operation. Null means unknown. type: - string - 'null' additionalProperties: true caption: description: Optional caption supplied by this operation. Null means unknown. type: - string - 'null' cover_url: description: Optional cover url supplied by this operation. Null means unknown. type: - string - 'null' created_at: description: Source creation time, not the API retrieval time. type: - string - 'null' id: description: Source identifier. Preserve the supplied type and exact value. type: - string - 'null' metrics: description: Optional metrics supplied by this operation. Null means unknown. type: - object - 'null' properties: engagement_rate: description: Optional engagement rate supplied by this operation. Null means unknown. type: - number - 'null' lifetime_organic_views: description: Optional lifetime organic views supplied by this operation. Null means unknown. type: - number - 'null' lifetime_views: description: Optional lifetime views supplied by this operation. Null means unknown. type: - number - 'null' organic_views: description: Optional organic views supplied by this operation. Null means unknown. type: - number - 'null' six_second_view_rate: description: Optional six second view rate supplied by this operation. Null means unknown. type: - number - 'null' views: description: Optional views supplied by this operation. Null means unknown. type: - number - 'null' additionalProperties: true platform: description: Optional platform supplied by this operation. Null means unknown. type: - string - 'null' rank: description: Optional rank supplied by this operation. Null means unknown. type: - number - 'null' url: description: Original source URL when supplied. type: - string - 'null' additionalProperties: true allOf: - anyOf: - required: - author properties: author: description: Public author information supplied with this record. type: - object properties: followers: description: Optional followers supplied by this operation. Null means unknown. type: - number - 'null' handle: description: Optional handle supplied by this operation. Null means unknown. type: - string - 'null' id: description: Source identifier. Preserve the supplied type and exact value. type: - string - 'null' name: description: Optional name supplied by this operation. Null means unknown. type: - string - 'null' additionalProperties: true - required: - caption properties: caption: description: Optional caption supplied by this operation. Null means unknown. type: - string minLength: 1 - required: - cover_url properties: cover_url: description: Optional cover url supplied by this operation. Null means unknown. type: - string minLength: 1 - required: - created_at properties: created_at: description: Source creation time, not the API retrieval time. type: - string minLength: 1 - required: - id properties: id: description: Source identifier. Preserve the supplied type and exact value. type: - string minLength: 1 - required: - metrics properties: metrics: description: Optional metrics supplied by this operation. Null means unknown. type: - object properties: engagement_rate: description: Optional engagement rate supplied by this operation. Null means unknown. type: - number - 'null' lifetime_organic_views: description: Optional lifetime organic views supplied by this operation. Null means unknown. type: - number - 'null' lifetime_views: description: Optional lifetime views supplied by this operation. Null means unknown. type: - number - 'null' organic_views: description: Optional organic views supplied by this operation. Null means unknown. type: - number - 'null' six_second_view_rate: description: Optional six second view rate supplied by this operation. Null means unknown. type: - number - 'null' views: description: Optional views supplied by this operation. Null means unknown. type: - number - 'null' additionalProperties: true - required: - rank properties: rank: description: Optional rank supplied by this operation. Null means unknown. type: - number - required: - url properties: url: description: Original source URL when supplied. type: - string minLength: 1 period: description: Optional period supplied by this operation. Null means unknown. type: - number - 'null' platform: description: Optional platform supplied by this operation. Null means unknown. type: - string - 'null' retrieved_at: description: Optional retrieved at supplied by this operation. Null means unknown. type: - string - 'null' sort: description: Optional sort supplied by this operation. Null means unknown. type: - string - 'null' source_period_end: description: Optional source period end supplied by this operation. Null means unknown. type: - string - 'null' additionalProperties: true required: - items x-contract-version: '2026-09-22' x-validation-scope: Required success payload structure; optional fields and source completeness remain separate. examples: - _warnings: - example count: 0 country: example coverage: example has_more: false items: - author: followers: 0 handle: example id: example name: example caption: example cover_url: https://example.com/example created_at: '2026-09-01T12:00:00Z' id: example metrics: engagement_rate: 0 lifetime_organic_views: 0 lifetime_views: 0 organic_views: 0 six_second_view_rate: 0 views: 0 platform: example rank: 0 url: https://example.com/example period: 0 platform: example retrieved_at: '2026-09-01T12:00:00Z' sort: example source_period_end: example default: description: The error envelope — the same shape for every non-2xx status. content: application/json: schema: $ref: '#/components/schemas/Error' x-credits: 1 x-production-available: true x-capacity: status: not_assessed message: Capacity is workload-dependent; configured routes do not establish sustained throughput or an availability guarantee. x-availability-scope: Structural check of the effective registered chain, production permission, adapter, configured cost and quality floor without request parameters. True is not a live-health, credential, quota, subscription-entitlement, complete-data or deployment-exposure guarantee. False means no structurally eligible candidate; null means metadata could not establish availability. Composite child capability still depends on its component routes. x-live-proven: true components: schemas: Error: type: object required: - success - error - credits_used - request_id properties: success: const: false error: type: object required: - type - message - status properties: type: type: string enum: - UNAUTHORIZED - KEY_REVOKED - KEY_LIMIT_EXCEEDED - RATE_LIMITED - INSUFFICIENT_CREDITS - RESOURCE_NOT_FOUND - INVALID_PARAMETERS - TARGET_ACCESS_DENIED - UPSTREAM_ERROR - UPSTREAM_TIMEOUT - FREE_CAPACITY_UNAVAILABLE - CAPACITY_UNAVAILABLE - ENDPOINT_NOT_FOUND - ENDPOINT_NOT_AVAILABLE - FAIR_USE_EXCEEDED - INTERNAL_ERROR message: type: string status: type: integer doc_url: type: string description: Deep link to the exact section of the errors guide for this type. details: type: object credits_used: type: - integer - 'null' description: Confirmed net charge; null when billing is pending reconciliation. Inspect error.details.billing_status and retain request_id. credits_remaining: type: integer request_id: type: string Success: type: object required: - success - platform - endpoint - data - credits_used - credits_remaining - request_id properties: _completeness: type: object description: Reported response completeness, not a guarantee of complete platform history. Missing source assertions remain unknown. properties: state: type: string enum: - complete - partial - unknown scope: type: string inspection_limited: type: boolean success: const: true platform: type: string endpoint: type: string description: The resolved path, e.g. `/v1/github/profile`. data: description: Amazon responses include marketplace.country and marketplace.domain (resolved request marketplace, UK by default). X profiles preserve location, bio_link and cover_url when supplied. TikTok profiles preserve commerce_user, seller, region, location and business_category when supplied; region identifies the account region rather than personal residence. TikTok comments use platform_default selection, which can change between fetches; keep the same video and options when following cursors. Amazon review variant is readable text. Facebook profiles preserve cover_url, following and created_at when supplied; likes_count and followers are distinct and follower totals may be rounded. Endpoint-specific normalized payload, not one universal post/profile schema. Many lists use items/count/cursor; a null cursor means no usable next cursor was supplied, not proof that all history was retrieved. Check has_more and warnings where present. Social full-profile bundles use posts_cursor and posts_pagination.next_params; retain all returned next parameters. YouTube channel bundles instead use recent_videos, cursor and recent_videos_pagination. Inspect complete/partial/legs where supplied for bounded or failed components. Optional model-derived fields are labelled, not source facts. credits_used: type: integer credits_remaining: type: integer request_id: type: string cached: type: boolean stale: type: boolean description: True only for an explicitly labelled, zero-credit reference snapshot served after a temporary upstream failure. age_seconds: type: integer minimum: 0 description: Age of a stale snapshot since its original retrieval; not reset by outage recovery. fetched_at: type: string format: date-time description: Original retrieval time of a stale snapshot, in UTC. synthetic: type: boolean description: Present and true only on the explicitly requested /sandbox surface. Synthetic responses are representative and charged 0 credits; production /v1 never returns them. degraded: type: boolean description: Reserved for sandbox compatibility. Production /v1 reports upstream failure as an error and never serves a representative fallback. securitySchemes: ApiKeyHeader: type: apiKey in: header name: x-api-key description: Your API key (`mn_…`), from the console. The recommended style. BearerKey: type: http scheme: bearer description: The same key as a Bearer token, for clients that only expose an Authorization field. Keys are never accepted in the query string — URLs leak into logs and referrers. x-provenance: method: harvested publisher: Monocrawl source: https://www.monocrawl.com/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)