TikTok Effects Search API

Endpoint facts

Method

GET

API path

/tiktok/mobile/search/effects

Auth

apiKey

Credits

8 credits/request

Charged on

Successful 2xx responses only

Platform

TikTok

Execution

Managed browser rendering where the target needs it

Response schema

#/definitions/tiktokmobile.searchEffectsResponseDoc

How this endpoint behaves

Searches TikTok's effect/sticker catalogue by keyword, as the app's effect picker does. The upstream is GET /aweme/v1/search/effect/, captured from the running 47.4.3 app and reproduced end-to-end against the live gateway.

What an effect carries. Each effects entry is the app's full effect object: name, hint, icon_url, file_url, id/effect_id, types, tags, parent/children, effect_type, music, source, designer_id and schema. The page is unfolded to the top level (effects, cursor, has_more, search_id, use_hot), with bind_effects/collection present only on some queries.

Paging needs both halves of the token. The upstream wraps results in a search session: to fetch the next page you must send the previous response's cursor and search_id together. Sending a cursor without its search_id returns an empty page, so this API rejects that combination with a 400 instead of silently returning nothing. count and offset are shape-parity parameters the server was measured to ignore — the server chooses the page size.

Device-free. The pure-Go placeholder signer returned the same results, so a deployment needs TIKTOK_MOBILE_PARAMS but not the device-backed signer (TIKTOK_MOBILE_SIGNER_URL). It answers on the core aggr16-normal.tiktokv.us / api16-normal-useast5.tiktokv.us pair.

Query parameters:

• keyword: required. Effect name or text; a keyword with no matches is a valid empty page.
• cursor: optional. The cursor from the previous response; 0/omitted is the first page.
• search_id: optional. The search_id from the previous response; required whenever cursor is set.
• count: optional. Accepted for shape parity and validated, but the server was measured to ignore it.

Errors:

• 400 — keyword is missing, cursor/count are out of range, or cursor was sent without search_id.
• 500 — the upstream failed.

Example request:

GET /api/v1/tiktok/mobile/search/effects?keyword=green%20screen

Example response (truncated):

{
  "code": 200,
  "msg": "OK",
  "data": {
    "effects": [
      {
        "name": "Green Screen Brush",
        "hint": "",
        "effect_id": "123",
        "types": ["Green Screen"],
        "tags": ["green screen", "background"],
        "icon_url": {"url_list": ["https://p16-...tiktokcdn-us.com/..."] },
        "file_url": {"uri": "...", "url_list": ["..."]},
        "designer_id": "456",
        "source": "artist",
        "schema": ""
      }
    ],
    "cursor": 100,
    "has_more": true,
    "search_id": "20261021173221C8185FF1D4A1062AD97C",
    "use_hot": false,
    "status_code": 0,
    "status_msg": ""
  }
}

Notes for callers:

• To page: call again with the same keyword plus the previous cursor and search_id; stop when has_more is false.
• use_hot: true marks the app's hot-fallback list (returned when the query has no exact matches).
• This searches the effect catalogue; to search videos that use an effect, use the video search endpoints with the effect name as the keyword.

Shared guides

Related