# searchtok

> tiktok and instagram reels research for agents and scripts: the outliers, hooks and creators in any niche, every number from real posts.

searchtok finds the tiktoks and instagram reels worth copying. give it a niche, an app, a website or a handle and it finds the outliers (posts with far more views than the account usually gets), the hooks behind them and the creators making them.

every endpoint is a searchtok tool, the same ones our own agent uses. views, outlier scores and baselines are worked out in code from real posts, never guessed by a model, and every result links back to the searchtok dashboard.

## ways in

- rest api: https://searchtok.app/api/v1 (live. for any agent or script that can send http: n8n, make, manus, your own code.)
- mcp server: https://searchtok.app/mcp (live. streamable http, for claude, chatgpt, claude code, cursor, codex, openclaw and any agent that takes a remote mcp server. add the url and sign in (oauth), or send your api key as `Authorization: Bearer st_live_...`.)
- cli: npx searchtok
- agent skill: npx skills add Mitchell2398/searchtok-agent

in claude code:

```bash
claude mcp add --transport http searchtok https://searchtok.app/mcp --header "Authorization: Bearer $SEARCHTOK_API_KEY"
```

## quick start

1. sign in and make an api key at https://searchtok.app/app/settings/keys
2. keep it in an environment variable: `export SEARCHTOK_API_KEY=st_live_...`
3. check it works. this one is free:

```sh
curl https://searchtok.app/api/v1/usage \
  -H "Authorization: Bearer $SEARCHTOK_API_KEY"
```

- keys: send your key on every request as `Authorization: Bearer st_live_...`. make and revoke keys at https://searchtok.app/app/settings/keys. every endpoint needs a searchtok plan, except usage and profile, which always work so an agent can tell you where you stand.
- credits: each call costs credits from one pool, shared by every way in. every signed-in response says what it used and what's left in two headers: `credits-used` and `credits-left`. a call that fails is refunded. send the same `Idempotency-Key` header to retry a call without paying twice. credit costs are provisional and may change before launch.
- rate limit: up to 60 requests a minute per key. past that you get a 429 with a `Retry-After` header.
- errors: every error has the same shape. `hint` says what to try next. `{"error": {"code", "message", "hint"}}`

## endpoints

requests and responses are json. an endpoint's input is its tool's input, and its response is the tool's output. credit costs are provisional and may change before launch.

### `search_content` · POST /api/v1/search · credits: 20 per query

Find the TikToks and Instagram Reels that did best for a topic or niche, ranked by outlier score (a post's views ÷ its account's usual views). searchtok's main tool.

input:

- `query` (string): What to look for, in the words people would search on TikTok: a niche, topic or format ("habit tracker app", "smile transformation"). Short beats long.
- `queries` (string[]): Up to 5 searches in one call, run at the same time (several angles on a niche, or several niches). Faster than one call per query; each query costs what a single search costs. Rows say which queries found them.
- `platforms` (("tiktok" | "instagram")[]): Default: both
- `timeframe` ("7d" | "30d" | "90d" | "1y"): Only posts from this long ago or newer. Default: any time
- `language` (string): Two-letter language, e.g. "en". Posts in other languages are dropped; posts whose language is unknown are kept
- `region` (string): Two-letter country that biases TikTok results (it doesn't filter them)
- `limit` (integer): Rows to return. Default 15 (more for several queries). Results are cut to about 2k tokens (plus about 1k per extra query); the rest are at `link`

```sh
curl -X POST https://searchtok.app/api/v1/search \
  -H "Authorization: Bearer $SEARCHTOK_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"query":"habit tracker app"}'
```

### `find_accounts` · POST /api/v1/accounts/find · 15 credits

Find TikTok or Instagram creators and brands in a niche, with how well their posts do: followers, usual (median) views and outlier rate (how often a post gets 3x+ their usual views).

input:

- `query` (string, required): A niche or topic ("habit tracker app"), or a name to look up
- `platform` ("tiktok" | "instagram"): Default: tiktok

```sh
curl -X POST https://searchtok.app/api/v1/accounts/find \
  -H "Authorization: Bearer $SEARCHTOK_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"query":"habit tracker app"}'
```

### `get_account` · GET /api/v1/accounts/{platform}/{handle} · 3 credits

Look up one TikTok or Instagram account: profile, its usual (median) views, outlier rate, posting rate, format mix and its best recent posts by outlier score.

input:

- `platform` ("tiktok" | "instagram", required, in the path): tiktok or instagram
- `handle` (string, required, in the path): The account's handle, with or without "@"

```sh
curl https://searchtok.app/api/v1/accounts/tiktok/completerapp \
  -H "Authorization: Bearer $SEARCHTOK_API_KEY"
```

### `analyze_brand` · POST /api/v1/brands/analyze · credits: 5 per brand (the brand plus each one compared)

Analyse a brand's or creator's organic TikTok and Instagram from its website, handle or name, optionally side by side with up to 3 others (compare).

input:

- `website` (string): The brand's site, e.g. "acme.com". Its TikTok and Instagram links are read from the page
- `handle` (string): A TikTok or Instagram handle, e.g. "@acme"
- `platform` ("tiktok" | "instagram"): The handle's platform. Default: tiktok
- `name` (string): The brand's name, looked up with TikTok account search
- `compare` (object[]): Up to 3 other brands, same fields, analysed side by side

```sh
curl -X POST https://searchtok.app/api/v1/brands/analyze \
  -H "Authorization: Bearer $SEARCHTOK_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"handle":"@completerapp","compare":[{"handle":"@thehabittracker"}]}'
```

### `analyze_post` · POST /api/v1/posts/analyze · credits: 6 per post

Everything about a TikTok or Instagram post, by url or searchtok id. For several posts, pass them together as ids or urls (up to 8): they're analysed at the same time, much faster than one call each.

input:

- `url` (string): The post's TikTok or Instagram url
- `id` (string): A searchtok post id from another result, e.g. "tiktok:7301234567890"
- `urls` (string[]): Several posts by url (up to 8 in all, with ids), analysed at the same time
- `ids` (string[]): Several posts by searchtok id (up to 8 in all, with urls), analysed at the same time

```sh
curl -X POST https://searchtok.app/api/v1/posts/analyze \
  -H "Authorization: Bearer $SEARCHTOK_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"url":"https://www.tiktok.com/@spaceyflower/video/7377548155597950251"}'
```

### `find_similar` · POST /api/v1/similar · 12 credits

Find posts like a given TikTok or Instagram post (same topic or format), ranked by outlier score.

input:

- `url` (string): The post's TikTok or Instagram url
- `id` (string): A searchtok post id, e.g. "tiktok:7301234567890"
- `limit` (integer): Default 10

```sh
curl -X POST https://searchtok.app/api/v1/similar \
  -H "Authorization: Bearer $SEARCHTOK_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"id":"tiktok:7377548155597950251","limit":10}'
```

### `research` · POST /api/v1/research · credits: 50 quick, 150 deep

Hand a whole question to searchtok's own research agent, which runs many searches and writes a checked report, every claim citing real posts.

input:

- `question` (string, required): The research question, in the user's words
- `depth` ("quick" | "deep"): quick: under 15s, only already-analysed posts. deep: up to a minute, analyses new posts. Default quick

```sh
curl -X POST https://searchtok.app/api/v1/research \
  -H "Authorization: Bearer $SEARCHTOK_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"question":"smile transformation"}'
```

### `get_research` · GET /api/v1/research/{search_id} · free

Fetch a research run's answer by its search_id: a deep run that research started in the background, or any earlier run.

works without a plan.

input:

- `search_id` (string, required, in the path): The run's search_id, from POST /research

```sh
curl https://searchtok.app/api/v1/research/$SEARCH_ID \
  -H "Authorization: Bearer $SEARCHTOK_API_KEY"
```

### `content_ideas` · POST /api/v1/ideas · 150 credits

Content ideas for the user's profile, each built on one video in their niche that beat its account's usual views 2x+ and fits the user (plus up to 2 more posts in its format), with hooks quoted word for word and the beats to film.

input:

- `profile_id` (string): Which saved profile (get_profile). Default: the first
- `count` (integer): How many ideas, 1 to 8. Default 8
- `focus` (string): Narrow the ideas: a theme ("leg day"), a format ("talking head", "talking head fitness") or an account ("@acme": ideas from its posts)

```sh
curl -X POST https://searchtok.app/api/v1/ideas \
  -H "Authorization: Bearer $SEARCHTOK_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'
```

### `build_profile` · POST /api/v1/profile/build · 10 credits

Turn one link into the user's searchtok profile: an App Store or Play link, a website, a TikTok or Instagram handle, or a sentence about the business.

input:

- `input` (string, required): What the profile is for: an App Store or Google Play link, a website ("acme.com"), a TikTok or Instagram handle or profile url ("@acme", "instagram @acme"), or a sentence ("i run a dog grooming van in leeds")
- `save` (boolean): Save it as one of the user's profiles. Default true. Building the same link again updates that profile

```sh
curl -X POST https://searchtok.app/api/v1/profile/build \
  -H "Authorization: Bearer $SEARCHTOK_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"input":"opal.so"}'
```

### `get_profile` · GET /api/v1/profile · free

The user's saved searchtok profile(s): what they make content for (an app, a business, a creator...), their niche, audience and language.

works without a plan.

input:

no input.

```sh
curl https://searchtok.app/api/v1/profile \
  -H "Authorization: Bearer $SEARCHTOK_API_KEY"
```

### `get_usage` · GET /api/v1/usage · free

The user's searchtok plan, credits left, when they reset, and what each tool costs.

works without a plan.

input:

no input.

```sh
curl https://searchtok.app/api/v1/usage \
  -H "Authorization: Bearer $SEARCHTOK_API_KEY"
```

## more

- [api docs](https://searchtok.app/docs/api)
- [openapi spec](https://searchtok.app/api/v1/openapi.json)
- [llms-full.txt](https://searchtok.app/llms-full.txt): every tool's full description, what it returns and a real example response