# ShortsIntel Intelligence API

> Short-form video intelligence for agents: search, enrich, score and track TikTok, Instagram Reels and YouTube Shorts, priced per operation and prepaid.

ShortsIntel is a short-form video intelligence API for agents. It searches, enriches, scores and tracks public videos on TikTok, Instagram Reels and YouTube Shorts, and returns compact JSON built for model context rather than raw vendor payloads.

Core model:
- Every charged operation creates a **Run**; free reads and edits (a balance, a rename, a deletion) answer directly and create none. `wait` (seconds, default 30, max 120) holds the response; if the work finishes you get `{ run, result }`, otherwise `{ run }` with status `running` to poll at `GET /v1/runs/{id}`. The envelope is identical either way.
- Run states: `running`, `completed`, `partial`, `failed`. A `partial` Run keeps its completed items and charges for them, up to what the Balance covers. A `failed` Run charges nothing.
- Lists paginate with `items` and `next_cursor`. Cursors are opaque: pass back the `next_cursor` you were given. Any other cursor is a `400 invalid_request` and is not charged.
- Errors are `application/problem+json` with a stable `code`. Branch on `code`, never on the prose.
- Re-reading a Run is always free. Check `GET /v1/runs` before repeating work you already paid for.

Money:
- Prepaid balance in Credits. Every price, charge and balance is a whole number of Credits. `estimate=true` on any paid operation returns `{ estimate_credits, cached }` without creating a Run or charging anything. Use it before spending.
- A cached result costs the same as a fresh one. A result is cached when a Snapshot under 24 h old is already stored; the Run says so in `cached`.
- Before any work starts, the Balance is checked against the operation's quoted price (for Research and enriched searches, the worst-case quote). If it cannot cover that, the call is a `402 insufficient_balance` and no Run is created or charged.
- A multi-item Run (Research, enriched search) settles per item when it finishes. If the Balance no longer covers every completed item, the completed items are charged in order up to the Balance, the rest fail with `insufficient_balance`, and the Run ends `partial`. A Run that cannot afford any of its work ends `failed` and is not charged.
- Top-ups buy 1,000 credits per US dollar and start at $10.

Limits: 60 requests per minute per key, 10 concurrent running Runs per Customer. `429` carries `Retry-After`.

Auth: `Authorization: Bearer sk_live_...`. Keys are created in the console, shown once and revocable. The MCP endpoint also accepts OAuth 2.1.

## About ShortsIntel

ShortsIntel is a short-form video research tool that plugs into Claude and other AI Assistants. It finds the videos and ads winning on TikTok, Instagram Reels, YouTube Shorts, Facebook and Meta Ads, watches the videos themselves, ranks what is outperforming and hands the findings to the Assistant, which then works as a creative researcher and copywriter. Built for creative strategists and content marketers; charged per Run from prepaid Credits, no subscription. Founded in 2025 by Jackson Gathondu, based in Kenya.

- [About ShortsIntel](https://www.shortsintel.com/about): the story, a fact sheet and answers to common questions.

## Documentation

- [Full reference for agents](https://www.shortsintel.com/llms-full.txt): every endpoint with parameters, prices and examples.
- [OpenAPI 3.1 document](https://www.shortsintel.com/docs/openapi.json)
- [Documentation site](https://www.shortsintel.com/docs)
- [API reference](https://www.shortsintel.com/docs/reference): one page per endpoint, with parameters, schemas, price and samples.
- [Webhook events](https://www.shortsintel.com/docs/reference/events) and [error codes](https://www.shortsintel.com/docs/reference/errors), one page each.
- [MCP quickstart](https://www.shortsintel.com/docs/mcp)
- [MCP server card](https://www.shortsintel.com/.well-known/mcp/server-card.json)
- [Terms](https://www.shortsintel.com/terms) and [Privacy](https://www.shortsintel.com/privacy)

## Guides

### Getting started

- [ShortsIntel API](https://www.shortsintel.com/docs) — A headless API and hosted MCP server for short-form video on TikTok, Instagram Reels and YouTube Shorts. Prepaid, priced per operation, built for agents.
- [REST quickstart](https://www.shortsintel.com/docs/quickstart) — From no key to a completed Run: create a key, make the first call, read the envelope, poll a Run and price a call before you spend on it.
- [MCP quickstart](https://www.shortsintel.com/docs/mcp) — Connect Claude.ai, ChatGPT, Claude Code, Codex, Cursor or VS Code to the ShortsIntel MCP server. 29 tools for short-form video research, priced per operation.

### Concepts

- [Runs](https://www.shortsintel.com/docs/concepts/runs) — Every charged operation creates a Run; free reads and edits do not. How the four states work, how long a call waits, how to poll one, and why re-reading a finished Run is free.
- [Pricing and estimates](https://www.shortsintel.com/docs/concepts/pricing-and-estimates) — How the prepaid Credit balance works, why a cached result costs the same as a fresh one, and how to ask the price of an operation before you spend anything on it.
- [Analysis](https://www.shortsintel.com/docs/concepts/analysis) — What we derive from a video, why it is computed once and reused, and when asking for a refresh is charged as new work.
- [Scores](https://www.shortsintel.com/docs/concepts/scores) — Outlier and velocity, how a creator baseline is built, what confidence means, and when a score stops being reported.
- [Research](https://www.shortsintel.com/docs/concepts/research) — How an intent becomes a digest, why a research id is a run id, and how to re-slice what you collected for free instead of paying for it twice.
- [Errors](https://www.shortsintel.com/docs/concepts/errors) — The problem document every failure returns, the stable codes to branch on, and what to do about each one.
- [Authentication and limits](https://www.shortsintel.com/docs/concepts/authentication-and-limits) — Bearer keys, OAuth on the MCP endpoint, who owns what, and the request and concurrency limits a key runs under.
- [Trackers](https://www.shortsintel.com/docs/concepts/trackers) — Standing watches on a creator or a Meta or TikTok Advertiser: how a cycle runs, when it reports a change, and how to pause one.
- [Webhooks](https://www.shortsintel.com/docs/concepts/webhooks) — The events we send, how to verify a signature, what happens when your endpoint is down, and how to rotate a secret.
- [Addressing videos and creators](https://www.shortsintel.com/docs/concepts/addressing) — How to name a video, creator, hashtag or sound, whether you hold a URL or a platform id.
- [Pagination](https://www.shortsintel.com/docs/concepts/pagination) — How lists page with items and a cursor, and how to read every page without paying twice.
- [Platforms and coverage](https://www.shortsintel.com/docs/concepts/platforms-and-coverage) — Which platforms we cover, what coverage reports mean, and where results are known to be partial.
- [Data and retention](https://www.shortsintel.com/docs/concepts/data-and-retention) — What public data we process, how long we keep it, what you may do with results, and how to reach us.
- [Ads](https://www.shortsintel.com/docs/concepts/ads) — Searching Meta's Ad Library with its filters, what each Ad carries, the winner Score, Ad analysis, what is stored, and how an ad search is priced.

### Reference

- [Pricing](https://www.shortsintel.com/docs/pricing) — Every operation with its price in Credits, why a cached result costs the same, what is free, and worked examples of a real month.
- [API reference](https://www.shortsintel.com/docs/reference) — Every /v1 endpoint with its parameters, schemas, price and samples, plus the webhook events and error codes.

## REST endpoints

### [Research](https://www.shortsintel.com/docs/reference/research)

- [`POST /v1/research`](https://www.shortsintel.com/docs/reference/research/create-research) — Research a niche. 1,036 credits covering up to 50 enriched videos, then 20 credits each, whether the analysis is fresh or already stored, so at most 4,036 credits at `max_videos` 200. Failed videos are never charged. The 402 pre-check uses that worst case.
- [`GET /v1/research/{id}`](https://www.shortsintel.com/docs/reference/research/get-research) — Get a research. Free, forever. Collection is the only thing charged.
- [`GET /v1/research/{id}/videos`](https://www.shortsintel.com/docs/reference/research/list-research-videos) — List a research's videos. Free, forever, filtered or not. Collection is the only thing charged.
- [`GET /v1/research/{id}/creators`](https://www.shortsintel.com/docs/reference/research/list-research-creators) — List a research's creators. Free, forever, filtered or not. Collection is the only thing charged.
- [`GET /v1/research/{id}/hashtags`](https://www.shortsintel.com/docs/reference/research/list-research-hashtags) — List a research's hashtags. Free, forever, filtered or not. Collection is the only thing charged.
- [`GET /v1/research/{id}/sounds`](https://www.shortsintel.com/docs/reference/research/list-research-sounds) — List a research's sounds. Free, forever, filtered or not. Collection is the only thing charged.
- [`GET /v1/research/{id}/digest`](https://www.shortsintel.com/docs/reference/research/get-research-digest) — Read a research's digest. Free, forever. Collection is the only thing charged.
- [`POST /v1/research/{id}/refresh`](https://www.shortsintel.com/docs/reference/research/refresh-research) — Refresh a research's videos. 3 credits per video that comes back.

### [Videos](https://www.shortsintel.com/docs/reference/videos)

- [`POST /v1/videos/search`](https://www.shortsintel.com/docs/reference/videos/search-videos) — Search videos. 3 credits per platform searched, per page (9 credits for the default three). `intelligence: true` adds 20 credits for each of the top 20 results enriched, whether analysed now or already. `focus`: +3 credits per Video the model judges, +1 credit per Video `must_mention` rules out, nothing for one already judged under the same Focus or one that could not be judged (shown); `estimate` quotes every returned Video judged.
- [`POST /v1/videos/lookup`](https://www.shortsintel.com/docs/reference/videos/lookup-video) — Look up a video by URL. 3 credits, the same when a Snapshot under 24 h old can answer.
- [`GET /v1/videos/{platform}/{id}`](https://www.shortsintel.com/docs/reference/videos/get-video) — Get a video. 3 credits. With `include=intelligence`: 23 credits instead of the lookup price. With `include=transcript` only: a flat 10 credits. With `include=download`: 3 credits alone, else 3 credits on top of the analysis or transcript price. A stored answer (or an existing copy) costs the same as a fresh one.
- [`POST /v1/videos/{platform}/{id}/intelligence`](https://www.shortsintel.com/docs/reference/videos/compute-video-intelligence) — Analyse a video. 23 credits, whether computed now or already stored, and with `refresh: true`.
- [`POST /v1/videos/{platform}/{id}/score`](https://www.shortsintel.com/docs/reference/videos/score-video) — Score a video. 9 credits, always fresh — asking for a score is asking for the fetch.
- [`GET /v1/videos/{platform}/{id}/comments`](https://www.shortsintel.com/docs/reference/videos/get-video-comments) — Get video comments. 3 credits per page, plus 10 credits with `analyze=true`, whether the analysis is computed now or already stored.

### [Creators](https://www.shortsintel.com/docs/reference/creators)

- [`GET /v1/creators/{platform}/{handle}`](https://www.shortsintel.com/docs/reference/creators/get-creator) — Get a creator. 6 credits, the same when a creator Snapshot under 24 h old and a baseline under 7 days old can answer. A next page of videos (`cursor`) is 3 credits.
- [`GET /v1/creators/{platform}/{handle}/videos`](https://www.shortsintel.com/docs/reference/creators/list-creator-videos) — List a creator's videos. Free. Counts toward the per-key request limit. `intelligence=true` costs 20 credits for each of the first 20 videos analysed, whether analysed now or already; the page itself stays free.
- [`GET /v1/creators/{platform}/{handle}/snapshots`](https://www.shortsintel.com/docs/reference/creators/list-creator-snapshots) — List a creator's snapshots. Free.

### [Hashtags](https://www.shortsintel.com/docs/reference/hashtags)

- [`GET /v1/hashtags/{platform}/{tag}`](https://www.shortsintel.com/docs/reference/hashtags/get-hashtag) — Get a hashtag. 3 credits, the same when a Snapshot under 24 h old can answer.
- [`GET /v1/hashtags/{platform}/{tag}/videos`](https://www.shortsintel.com/docs/reference/hashtags/list-hashtag-videos) — List a hashtag's videos. 3 credits per page.

### [Sounds](https://www.shortsintel.com/docs/reference/sounds)

- [`GET /v1/sounds/{platform}/{id}`](https://www.shortsintel.com/docs/reference/sounds/get-sound) — Get a sound. 6 credits, the same when a Snapshot under 24 h old can answer.
- [`GET /v1/sounds/{platform}/{id}/videos`](https://www.shortsintel.com/docs/reference/sounds/list-sound-videos) — List a sound's videos. 6 credits per page.

### [Keywords](https://www.shortsintel.com/docs/reference/keywords)

- [`GET /v1/keywords/{platform}`](https://www.shortsintel.com/docs/reference/keywords/get-keyword) — Get a keyword. 3 credits, the same when a Snapshot under 24 h old can answer. `focus`: +3 credits per Video the model judges, +1 credit per Video `must_mention` rules out, nothing for one already judged under the same Focus or one that could not be judged (shown); `estimate` quotes every returned Video judged.

### [Ads](https://www.shortsintel.com/docs/reference/ads)

- [`POST /v1/ads/search`](https://www.shortsintel.com/docs/reference/ads/search-ads) — Search ad libraries. Meta: 1 credit per Ad delivered, the same when served from a recent advertiser observation, plus 20 credits per Ad analysed with `analyze`, computed or already stored; the estimate quotes `limit` Ads, all analysed up to the cap with `analyze`. TikTok: 3 credits per page.
- [`GET /v1/ads/meta/{library_id}`](https://www.shortsintel.com/docs/reference/ads/get-meta-ad) — Get a Meta Ad. 3 credits, read live or from our stored copy (observed under 6 h ago, or removed from the library). With `analyze=true`, plus 20 credits, whether the analysis is computed or already stored.
- [`GET /v1/ads/tiktok/{ad_id}`](https://www.shortsintel.com/docs/reference/ads/get-tik-tok-ad) — Get a TikTok Ad. 3 credits.
- [`GET /v1/ads/meta/{library_id}/intelligence`](https://www.shortsintel.com/docs/reference/ads/get-meta-ad-intelligence) — Get a Meta Ad's analysis. Free.
- [`GET /v1/ads/meta/{library_id}/snapshots`](https://www.shortsintel.com/docs/reference/ads/list-meta-ad-snapshots) — List a Meta Ad's snapshots. Free.
- [`GET /v1/ads/tiktok/{ad_id}/snapshots`](https://www.shortsintel.com/docs/reference/ads/list-tik-tok-ad-snapshots) — List a TikTok Ad's snapshots. Free.
- [`GET /v1/advertisers/{page_id}`](https://www.shortsintel.com/docs/reference/ads/get-advertiser) — Get an advertiser. 15 credits, the same when served within 6 hours of a complete observation.

### [Trackers](https://www.shortsintel.com/docs/reference/trackers)

- [`POST /v1/trackers`](https://www.shortsintel.com/docs/reference/trackers/create-tracker) — Start tracking a target. The first cycle is charged on create: 6 credits for a creator, 3 credits for a hashtag, 6 credits for a sound, 3 credits for a keyword, 30 credits for an advertiser, plus 20 credits per new video when `intelligence` is on (per new Ad, on its own Run, for an advertiser). A TikTok advertiser cycle includes 10 new Ads' detail reads, then 3 credits each; the estimate and Balance check quote every running Ad new, at most 300, and a cycle never charges for more new Ads' details than that. A first (baseline) cycle reports nothing but reads up to 10 Ads' details, included, so lookups and the first Change Report carry targeting. Each later daily cycle costs the same. Nothing is charged when the target is already tracked.
- [`GET /v1/trackers`](https://www.shortsintel.com/docs/reference/trackers/list-trackers) — List trackers. Free.
- [`GET /v1/trackers/{id}`](https://www.shortsintel.com/docs/reference/trackers/get-tracker) — Get a tracker. Free.
- [`PATCH /v1/trackers/{id}`](https://www.shortsintel.com/docs/reference/trackers/update-tracker) — Update a tracker. Free.
- [`DELETE /v1/trackers/{id}`](https://www.shortsintel.com/docs/reference/trackers/delete-tracker) — Stop tracking. Free.
- [`POST /v1/trackers/{id}/refresh`](https://www.shortsintel.com/docs/reference/trackers/refresh-tracker) — Run a tracker cycle now. 6 credits for a creator, 30 credits for an advertiser, plus 20 credits per new video when the Tracker opted into analysis (per new Ad, on its own Run, for an advertiser); a TikTok advertiser's new Ads' detail reads beyond 10 at 3 credits each, quoted at worst (every running Ad new, at most 300). Same price as a scheduled cycle.
- [`PUT /v1/trackers/{id}/focus`](https://www.shortsintel.com/docs/reference/trackers/set-tracker-focus) — Set or clear a tracker's focus. +3 credits per Video the model judges, +1 credit per Video `must_mention` rules out; nothing for a Video already judged under this Focus (a preview included) or one that could not be judged. Clearing is free.
- [`POST /v1/trackers/{id}/focus/preview`](https://www.shortsintel.com/docs/reference/trackers/preview-tracker-focus) — Preview a focus on a tracker. As setting the Focus: +3 credits per Video the model judges, +1 credit per Video `must_mention` rules out, nothing for a Video already judged under it.
- [`GET /v1/trackers/{id}/snapshots`](https://www.shortsintel.com/docs/reference/trackers/list-tracker-snapshots) — List a tracker's snapshots. Free.
- [`GET /v1/trackers/{id}/changes`](https://www.shortsintel.com/docs/reference/trackers/list-tracker-changes) — List change reports. Free.

### [Collections](https://www.shortsintel.com/docs/reference/collections)

- [`POST /v1/collections`](https://www.shortsintel.com/docs/reference/collections/create-collection) — Create a collection. Free.
- [`GET /v1/collections`](https://www.shortsintel.com/docs/reference/collections/list-collections) — List collections. Free.
- [`GET /v1/collections/{id}`](https://www.shortsintel.com/docs/reference/collections/get-collection) — Get a collection. Free.
- [`PATCH /v1/collections/{id}`](https://www.shortsintel.com/docs/reference/collections/rename-collection) — Rename a collection. Free.
- [`DELETE /v1/collections/{id}`](https://www.shortsintel.com/docs/reference/collections/delete-collection) — Delete a collection. Free.
- [`GET /v1/collections/{id}/members`](https://www.shortsintel.com/docs/reference/collections/list-collection-members) — Rank the members. Free.
- [`GET /v1/collections/{id}/changes`](https://www.shortsintel.com/docs/reference/collections/list-collection-changes) — List a collection's changes. Free.
- [`POST /v1/collections/{id}/members`](https://www.shortsintel.com/docs/reference/collections/add-collection-member) — Add a member. Free, except a target not tracked yet: its first cycle, 6 credits for a creator, 3 credits for a hashtag, 6 credits for a sound, 3 credits for a keyword, 30 credits for an advertiser.
- [`DELETE /v1/collections/{id}/members/{tracker_id}`](https://www.shortsintel.com/docs/reference/collections/remove-collection-member) — Remove a member. Free.
- [`POST /v1/collections/{id}/actions`](https://www.shortsintel.com/docs/reference/collections/act-on-collection) — Act on every member. Free, except `refresh`: one cycle per member refreshed, 6 credits for a creator, 30 credits for an advertiser, plus 20 credits per new video on members with analysis on.

### [Runs](https://www.shortsintel.com/docs/reference/runs)

- [`GET /v1/runs`](https://www.shortsintel.com/docs/reference/runs/list-runs) — List runs. Free.
- [`GET /v1/runs/{id}`](https://www.shortsintel.com/docs/reference/runs/get-run) — Get a run. Free.
- [`GET /v1/runs/{id}/items`](https://www.shortsintel.com/docs/reference/runs/list-run-items) — List run items. Free: the charge happened once, when the work did.

### [Account](https://www.shortsintel.com/docs/reference/account)

- [`GET /v1/account/balance`](https://www.shortsintel.com/docs/reference/account/get-balance) — Get balance. Free.
- [`GET /v1/account/usage`](https://www.shortsintel.com/docs/reference/account/get-usage) — Get usage. Free.

### [Webhooks](https://www.shortsintel.com/docs/reference/webhooks)

- [`POST /v1/webhooks`](https://www.shortsintel.com/docs/reference/webhooks/create-webhook) — Register a webhook endpoint. Free.
- [`GET /v1/webhooks`](https://www.shortsintel.com/docs/reference/webhooks/list-webhooks) — List webhook endpoints. Free.
- [`GET /v1/webhooks/{id}`](https://www.shortsintel.com/docs/reference/webhooks/get-webhook) — Get a webhook endpoint. Free.
- [`DELETE /v1/webhooks/{id}`](https://www.shortsintel.com/docs/reference/webhooks/delete-webhook) — Delete a webhook endpoint. Free.
- [`POST /v1/webhooks/{id}/rotate`](https://www.shortsintel.com/docs/reference/webhooks/rotate-webhook-secret) — Rotate a signing secret. Free.
- [`GET /v1/webhooks/{id}/deliveries`](https://www.shortsintel.com/docs/reference/webhooks/list-webhook-deliveries) — List deliveries. Free.
- [`POST /v1/webhooks/{id}/deliveries/{deliveryId}/replay`](https://www.shortsintel.com/docs/reference/webhooks/replay-webhook-delivery) — Replay a delivery. Free.

## MCP tools

Endpoint: `https://www.shortsintel.com/api/mcp` (streamable HTTP). Bearer API key or OAuth 2.1. Paid tools accept `estimate` and an optional `idempotency_key` (a retry with the same key returns the original Run, not charged again).

- `research` — Research a niche (writes). 1,036 credits for up to 50 enriched videos, then 20 credits each, at most 4,036 credits
- `get_research` — Read a research (read-only). Free
- `search_videos` — Search videos (writes). 3 credits per platform searched, per page; +20 credits per enriched video with intelligence=true (top 20); with focus +3 credits per Video judged, +1 credit per must_mention rejection
- `get_video` — Get a video (writes). 3 credits plain; with include=intelligence 23 credits instead; transcript only 10 credits instead; include=download 3 credits alone, else +3 credits
- `get_comments` — Get a video's comments (writes). 3 credits per page; +10 credits with analyze
- `score_video` — Score a video (writes). 9 credits
- `get_creator` — Get a creator (writes). 6 credits; videos pages 3 credits; with intelligence=true the page is free, +20 credits per analysed video (top 20)
- `get_hashtag_or_sound` — Get a hashtag or sound (writes). hashtag 3 credits, sound 6 credits
- `get_keyword` — Get a keyword (writes). 3 credits; with focus +3 credits per Video judged, +1 credit per must_mention rejection
- `search_ads` — Search ad libraries (writes). Meta 1 credit per Ad delivered, +20 credits per Ad analysed (computed or stored); TikTok 3 credits per page
- `get_ad` — Get an Ad or Advertiser (writes). Ad 3 credits, +20 credits with analyze (Meta); Advertiser 15 credits (Meta or TikTok); TikTok Ad 3 credits
- `track` — Track a target (writes). 6 credits per creator cycle, 3 credits per hashtag cycle, 3 credits per keyword cycle, 6 credits per sound cycle, 30 credits per advertiser cycle, including the first one run on create; +20 credits per new video or Ad with intelligence; with a focus +3 credits per video judged, +1 credit per must_mention rejection; tracking a target you already track is free
- `list_trackers` — List trackers (read-only). Free
- `get_tracker` — Get a tracker (read-only). Free
- `set_tracker_state` — Pause or resume a tracker (writes). Free
- `set_tracker_intelligence` — Switch tracker analysis on or off (writes). Free
- `set_tracker_focus` — Set, clear or preview a tracker's focus (writes). +3 credits per video judged, +1 credit per must_mention rejection; nothing for one already judged; clearing is free
- `delete_tracker` — Delete a tracker (destructive). Free
- `get_changes` — Get change reports (read-only). Free
- `list_collections` — List collections (read-only). Free
- `create_collection` — Create a collection (writes). Free
- `rename_collection` — Rename a collection (writes). Free
- `delete_collection` — Delete a collection (destructive). Free
- `add_to_collection` — Add to a collection (writes). Free for a Tracker you already have; a target not tracked yet runs its first cycle: 6 credits per creator, 3 credits per hashtag, 3 credits per keyword, 6 credits per sound, 30 credits per advertiser, +20 credits per new video with analysis
- `remove_from_collection` — Remove from a collection (writes). Free
- `act_on_collection` — Act on every member (writes). Free for pause, resume and intelligence; refresh is one cycle per member: 6 credits per creator, 3 credits per hashtag, 3 credits per keyword, 6 credits per sound, 30 credits per advertiser, +20 credits per new video with analysis
- `get_run` — Get a run (read-only). Free
- `get_usage` — Get usage (read-only). Free
- `get_balance` — Get balance (read-only). Free

## Terms in one line

Derived works are allowed. Republishing bulk raw records, reselling or mirroring the dataset, and targeting individuals are not.

Contact: support@shortsintel.com