Search ads

POST/v1/api/tiktok/ads/search-ads

Search ads in TikTok's Creative Center with multi-dimensional filtering and sorting Discover effective ad cases related to specific industries, keywords, or objectives Provide reference and inspiration for ad planning and creative production

Request body

Call this sync operation at its vendor-qualified URL. The model identity is encoded in the path; only operation-specific input fields belong in the request body.

Optional<integer>ad_format

Ad format, 1=Video ads

Optional<string>ad_language

Ad language code, e.g., en, zh

Optional<string>country_code

Country code, e.g., US, UK, JP

Optional<string>industry

Industry ID list, multiple IDs separated by commas. Full industry ID list: https://github.com/TikHub/TikTok-Ads-Industry-Code

Optional<string>keyword

Search keyword, optional, returns all ads if empty

Optional<integer>like

Like count filter, 1=All

Optional<integer>limit

Items per page, default 20, max 50

Optional<integer>objective

Ad objective, 1=All

Optional<string>order_by

Sort method, "for_you"=Recommended, "likes"=Sort by likes

Optional<integer>page

Page number, default 1

Optional<integer>period

Time period in days, e.g., 7, 30, 120, 180 days

Optional<string>search_id

Search ID (optional)

Response Schema

A synchronous completed response contains exactly one outputs item with only data. Failed and timeout responses contain error and never outputs.

stringidrequired

Opaque SandBase run identifier. Use it exactly as returned; no prefix is guaranteed.

stringstatusrequired

Current public run status.

Allowed values: pending, running, completed, failed, timeout

stringmodelrequired

Public SandBase model name used for this run.

Optional<array<object>>outputs

Present only for completed runs. Contains exactly one item whose only field is data.

Optional<object | array>outputs[0].data

Operation-specific business payload. This reference uses an empty object when no safe example can be confirmed.

Optional<object>error

Present only for failed or timeout runs. Contains a public error type and sanitized message.

Optional<string>error.type

Stable public error category.

Optional<string>error.message

Sanitized error message safe to show to clients.

Optional<object>usage

Usage details when available.

API capabilities

array<string>capability_tagsrequired

Capabilities declared by the API registry.

Default: api, tiktok

stringexecution_moderequired

Execution mode declared by the API registry.

Default: sync

pending response

{"id":"f3d2e8a1-7c4b-4a12-9d2e-123456789abc","status":"pending","model":"tiktok/ads/search-ads"}

running response

{"id":"f3d2e8a1-7c4b-4a12-9d2e-123456789abc","status":"running","model":"tiktok/ads/search-ads"}

completed response

{"id":"f3d2e8a1-7c4b-4a12-9d2e-123456789abc","status":"completed","model":"tiktok/ads/search-ads","outputs":[{"data":{}}]}

failed response

{"id":"f3d2e8a1-7c4b-4a12-9d2e-123456789abc","status":"failed","model":"tiktok/ads/search-ads","error":{"type":"upstream_error","message":"upstream request failed"}}

timeout response

{"id":"f3d2e8a1-7c4b-4a12-9d2e-123456789abc","status":"timeout","model":"tiktok/ads/search-ads","error":{"type":"upstream_error","message":"upstream request failed"}}

curl -X POST https://api.sandbase.ai/v1/api/tiktok/ads/search-ads \
  -H "Authorization: Bearer $SANDBASE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{\n
  "keyword": "keyword"
}'

Response200 OK

{
  "id": "f3d2e8a1-7c4b-4a12-9d2e-123456789abc",
  "status": "completed",
  "model": "tiktok/ads/search-ads",
  "outputs": [
    {
      "data": {}
    }
  ]
}