# TikTok search with music IDs

Add include_music=true to top search to request exact music IDs and supplied author verification on one page, at the normal one-credit price.

## One-credit search with music

```
GET /v1/tiktok/search-top?query=space%20exploration&include_music=true
```

Use `data.items[].music.id` as a string and `data.items[].author.verified` as a nullable boolean. The option prefers a source that supplies those fields with up to 30 records per page. Page sizes vary; later pages can be shorter. Missing information stays null.

This option supports relevance order and an all-time search. Other sort orders or publish windows retain the ordinary search path, with a warning when music enrichment is unavailable. The preferred source can return different results from ordinary search.

Keep `include_music=true`, the same key and all other inputs when following the returned cursor. Existing cursors keep their original source. If the preferred source is unavailable, a fallback may return a normal page with a warning. Requests without the option keep their existing behavior.

## Preview, then run

For selected posts still missing an ID, the separate [Node.js lookup workflow](https://www.monocrawl.com/examples/tiktok-search-music.mjs) remains available at component prices. With Node.js 22 or newer, set `MONOCRAWL_API_KEY` and preview the maximum price:

```
node tiktok-search-music.mjs '{"query":"space exploration","maxPosts":5,"maxCredits":6,"estimateOnly":true}'
```

Remove `estimateOnly` to run. `maxPosts` defaults to five and accepts 0–10. Zero runs search only. Each selected distinct post adds one normally priced lookup; duplicated posts share one lookup. Posts that already have an exact music ID need no lookup.

Pass `cursor`, `region`, `publish_time` and `sort_by` when needed. Continue using the same key and search inputs. A run acquires only one search page. `maxDurationSeconds` defaults to 180 and accepts 1–300.

## Exact IDs and partial results

Search sources can omit an ID or send an integer that was already rounded upstream. Those values remain null. A matching [post lookup](https://www.monocrawl.com/docs/endpoints/tiktok/post) can supply the exact string ID for the music. The workflow checks the returned post identity before filling `music.id`, and preserves the other search fields.

`music_lookup_status` distinguishes a successful lookup, an existing ID, an unrequested lookup and an unavailable or failed result. Search rows, timestamps and cursors survive enrichment failures. Availability varies by post; this workflow does not guarantee an ID for every sound.

Ordinary [top search](https://www.monocrawl.com/docs/endpoints/tiktok/search-top) keeps its existing price and pagination. Extra requests happen only when this workflow is run.

## Bound total spending

| Component | Current base price |
| --- | --- |
| [`tiktok/search-top`](https://www.monocrawl.com/docs/endpoints/tiktok/search-top) | 1 credits |
| [`tiktok/post`](https://www.monocrawl.com/docs/endpoints/tiktok/post) | 1 credits |

The initial estimate covers one search plus `maxPosts` lookups. An insufficient `maxCredits` budget spends nothing. Every paid request gets a fresh price preview and an `X-Max-Credits` ceiling. Missing rows, existing music IDs and cache hits can reduce the final charge.

The ledger reports confirmed credits and `credits_reserved_unknown`. A lost paid response stops further spending without an automatic retry; check account usage before rerunning. Search remains charged when a later lookup fails.