> ## Documentation Index > Fetch the complete documentation index at: https://docs.socq.ai/llms.txt > Use this file to discover all available pages before exploring further. # TikTok Ad Library Search > Collect normalized public tiktok ad library search data. # TikTok Ad Library Search ```json theme={"system"} { "query": "Anysphere", "results_limit": 12 } ``` `results_limit` must be a multiple of the 12-record page size. ## Result Fields Task results use the stable SocQ fields below. Source-specific field names and formats are normalized without inferring or enriching values that the source did not provide. To request a smaller field set, use `fields` for MCP queries, `_result_fields` for typed tools, or `--result-fields` in the CLI. Declared fields remain present when their value is `null`. | Field | Type | Nullable | Description | | ------------------------ | --------------- | -------- | ------------------------------------------------------------------------ | | `id` | `string` | Yes | Unique identifier for this result item. | | `platform` | `string` | No | Platform the result belongs to, such as `instagram` or `linkedin`. | | `resource` | `string` | No | SocQ resource represented by the result, such as `videos` or `comments`. | | `type` | `string` | No | Category of the result item, such as `video`, `post`, or `comment`. | | `url` | `string` | Yes | Public URL of the result item when available. | | `published_at` | `string` | Yes | Time the source item was published, in ISO 8601 format when available. | | `collected_at` | `string` | No | Time SocQ collected or processed this result, in ISO 8601 format. | | `text` | `string` | Yes | Advertising copy or creative text. | | `advertiser` | `object` | Yes | Advertiser responsible for the ad. | | `advertiser.id` | `string` | Yes | Unique identifier of the advertiser. | | `advertiser.name` | `string` | Yes | Display name of the advertiser. | | `advertiser.url` | `string` | Yes | Public URL of the advertiser when available. | | `advertiser.logo_url` | `string` | Yes | URL of the company or advertiser logo. | | `start_date` | `string` | Yes | Date the ad started running when available. | | `end_date` | `string` | Yes | Date the ad stopped running when available. | | `countries` | `array` | Yes | Countries or regions where the ad was delivered. | | `platforms` | `array` | Yes | Placements or platforms where the ad was delivered. | | `format` | `string` | Yes | Advertising creative format, such as image or video. | | `landing_page_url` | `string` | Yes | Destination URL opened from the ad. | | `impressions` | `integer` | Yes | Number of ad impressions when reported. | | `media` | `array` | Yes | Images, videos, or other media attached to the result. | | `media.type` | `string` | Yes | Media kind, such as `image` or `video`. | | `media.url` | `string` | Yes | URL of the media asset. | | `media.thumbnail_url` | `string` | Yes | URL of the media preview image. | | `media.width` | `integer` | Yes | Media width in pixels. | | `media.height` | `integer` | Yes | Media height in pixels. | | `media.duration_seconds` | `number` | Yes | Media duration in seconds. | ## Completed Task Response ```json theme={"system"} { "code": 200, "data": { "task_id": "59QTHGPQAGWL15HU", "status": "succeeded", "public_id": "tiktok-ad-library/search", "result_count": 1, "credits_amount": 0.5, "results": { "limit": 50, "next_cursor": null, "has_more": false, "schema_id": "ad", "schema_version": "1.0", "items": [ { "id": "1871316066418689", "platform": "tiktok-ad-library", "resource": "search", "type": "ad", "url": null, "published_at": "2026-07-21T00:00:00Z", "collected_at": "2026-08-11T03:03:36.974127Z", "text": null, "advertiser": { "id": null, "name": "Anysphere", "url": null, "logo_url": null }, "start_date": null, "end_date": null, "countries": null, "platforms": null, "format": null, "landing_page_url": null, "impressions": null, "media": [] } ] } } } ``` ## Use with MCP and CLI | Interface | Value | | ----------- | ---------------------------------------------------------- | | REST | `POST /v1/tiktok-ad-library/search` | | Compact MCP | `socq_execute` with `endpoint: "tiktok-ad-library/search"` | | Typed MCP | `socq_tiktok_ad_library_search` | | CLI | `socq tiktok-ad-library search` | The endpoint uses the asynchronous task flow and returns a task\_id. Poll the task endpoint to read normalized results. ## OpenAPI ````yaml api-manual/agent-api/agent-api.json POST /v1/tiktok-ad-library/search openapi: 3.1.0 info: title: SocQ Agent API version: v1-c051f5df2885 description: Asynchronous social data API generated from the SocQ Capability Registry. servers: - url: https://api.socq.ai security: [] paths: /v1/tiktok-ad-library/search: post: tags: - tiktok-ad-library summary: Get TikTok Ad Library Search description: Fetch normalized search data from TikTok Ad Library. operationId: socq_tiktok_ad_library_search requestBody: required: true content: application/json: schema: $schema: https://json-schema.org/draft/2020-12/schema type: object additionalProperties: false properties: query: type: string minLength: 1 description: Search query. results_limit: type: integer minimum: 12 maximum: 2000 default: 12 multipleOf: 12 required: - query responses: '200': description: Task accepted content: application/json: schema: $ref: '#/components/schemas/AgentSubmitResponse' security: - bearerAuth: [] - apiKeyAuth: [] components: schemas: AgentSubmitResponse: type: object properties: code: type: integer const: 200 data: type: object properties: task_id: type: string status: type: string created_time: type: - string - 'null' idempotent_replay: type: boolean required: - task_id - status securitySchemes: bearerAuth: type: http scheme: bearer apiKeyAuth: type: apiKey in: header name: x-api-key ````