llms.txt
# 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 '{}'
```
### `save_posts` · POST /api/v1/saved · free
Save posts to the user's searchtok Saved page, their swipe file of TikToks and Reels to come back to. Use it when the user asks to save, keep or bookmark posts.
input:
- `ids` (string[]): searchtok post ids from another result, e.g. "tiktok:7301234567890"
- `urls` (string[]): TikTok or Instagram post urls searchtok has already returned
- `unsave` (boolean): True takes them off the Saved page instead
```sh
curl -X POST https://searchtok.app/api/v1/saved \
-H "Authorization: Bearer $SEARCHTOK_API_KEY" \
-H "Content-Type: application/json" \
-d '{"ids":["tiktok:7377548155597950251"]}'
```
### `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
