# 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 operation creates a **Run**. `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.

## 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)
- [Rendered reference with try-it](https://www.shortsintel.com/docs/reference)
- [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, Claude Code, Cursor or VS Code to the ShortsIntel MCP server. 17 tools for short-form video research, priced per operation.

### Concepts

- [Runs](https://www.shortsintel.com/docs/concepts/runs) — Every operation creates a Run. 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 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, responses and price, and a box to paste your key and try one from the page.

## REST endpoints

### Research

- `POST /v1/research` — Research a niche. 536 credits covering up to 50 enriched videos, then 10 credits each, whether the analysis is fresh or already stored, so at most 2,036 credits at `max_videos` 200. Failed videos are never charged. The 402 pre-check uses that worst case.
- `GET /v1/research/{id}` — Get a research. Free, forever. Collection is the only thing charged.
- `GET /v1/research/{id}/videos` — List a research's videos. Free, forever, filtered or not. Collection is the only thing charged.
- `GET /v1/research/{id}/creators` — List a research's creators. Free, forever, filtered or not. Collection is the only thing charged.
- `GET /v1/research/{id}/hashtags` — List a research's hashtags. Free, forever, filtered or not. Collection is the only thing charged.
- `GET /v1/research/{id}/sounds` — List a research's sounds. Free, forever, filtered or not. Collection is the only thing charged.
- `GET /v1/research/{id}/digest` — Read a research's digest. Free, forever. Collection is the only thing charged.
- `POST /v1/research/{id}/refresh` — Refresh a research's videos. 3 credits per video that comes back.

### Videos

- `POST /v1/videos/search` — Search videos. 3 credits per platform searched, per page (9 credits for the default three). `intelligence: true` adds 10 credits for each of the top 20 results enriched, whether analysed now or already.
- `POST /v1/videos/lookup` — Look up a video by URL. 3 credits, the same when a Snapshot under 24 h old can answer.
- `GET /v1/videos/{platform}/{id}` — Get a video. 3 credits. With `include=intelligence`: 13 credits instead of the lookup price. With `include=transcript` only: a flat 10 credits. A stored answer costs the same as a fresh one.
- `POST /v1/videos/{platform}/{id}/intelligence` — Analyse a video. 13 credits, whether computed now or already stored, and with `refresh: true`.
- `POST /v1/videos/{platform}/{id}/score` — Score a video. 9 credits, always fresh — asking for a score is asking for the fetch.
- `GET /v1/videos/{platform}/{id}/comments` — Get video comments. 3 credits per page, plus 10 credits with `analyze=true`, whether the analysis is computed now or already stored.

### Creators

- `GET /v1/creators/{platform}/{handle}` — Get a creator. 6 credits, the same when a creator Snapshot under 24 h old and a baseline under 7 days old can answer.
- `GET /v1/creators/{platform}/{handle}/videos` — List a creator's videos. Free. Counts toward the per-key request limit.
- `GET /v1/creators/{platform}/{handle}/snapshots` — List a creator's snapshots. Free.

### Hashtags

- `GET /v1/hashtags/{platform}/{tag}` — Get a hashtag. 3 credits, the same when a Snapshot under 24 h old can answer.
- `GET /v1/hashtags/{platform}/{tag}/videos` — List a hashtag's videos. 3 credits per page.

### Sounds

- `GET /v1/sounds/{platform}/{id}` — Get a sound. 6 credits, the same when a Snapshot under 24 h old can answer.
- `GET /v1/sounds/{platform}/{id}/videos` — List a sound's videos. 6 credits per page.

### Ads

- `POST /v1/ads/search` — Search ad libraries. Meta: 1 credit per Ad delivered, the same when served from a recent advertiser observation, plus 10 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}` — 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 10 credits, whether the analysis is computed or already stored.
- `GET /v1/ads/meta/{library_id}/intelligence` — Get a Meta Ad's analysis. Free.
- `GET /v1/ads/meta/{library_id}/snapshots` — List a Meta Ad's snapshots. Free.
- `GET /v1/advertisers/{page_id}` — Get a Meta advertiser. 15 credits, the same when served within 6 hours of a complete observation.

### Trackers

- `POST /v1/trackers` — Start tracking a target. The first cycle is charged on create: 6 credits for a creator, 30 credits for an advertiser, plus 10 credits per new video when `intelligence` is on (per new Ad, on its own Run, for an advertiser). Each later daily cycle costs the same. Nothing is charged when the target is already tracked.
- `GET /v1/trackers` — List trackers. Free.
- `GET /v1/trackers/{id}` — Get a tracker. Free.
- `PATCH /v1/trackers/{id}` — Pause or resume a tracker. Free.
- `DELETE /v1/trackers/{id}` — Stop tracking. Free.
- `POST /v1/trackers/{id}/refresh` — Run a tracker cycle now. 6 credits for a creator, 30 credits for an advertiser, plus 10 credits per new video when the Tracker opted into analysis (per new Ad, on its own Run, for an advertiser). Same price as a scheduled cycle.
- `GET /v1/trackers/{id}/snapshots` — List a tracker's snapshots. Free.
- `GET /v1/trackers/{id}/changes` — List change reports. Free.

### Collections

- `POST /v1/collections` — Create a collection. Free.
- `GET /v1/collections` — List collections. Free.
- `GET /v1/collections/{id}` — Get a collection. Free.
- `PATCH /v1/collections/{id}` — Rename a collection. Free.
- `DELETE /v1/collections/{id}` — Delete a collection. Free.
- `GET /v1/collections/{id}/members` — Rank the members. Free.
- `GET /v1/collections/{id}/changes` — List a collection's changes. Free.
- `POST /v1/collections/{id}/members` — Add a member. Free, except a target not tracked yet: its first cycle, 6 credits for a creator, 30 credits for an advertiser.
- `DELETE /v1/collections/{id}/members/{tracker_id}` — Remove a member. Free.
- `POST /v1/collections/{id}/actions` — Act on every member. Free, except `refresh`: one cycle per member refreshed, 6 credits for a creator, 30 credits for an advertiser, plus 10 credits per new video on members with analysis on.

### Runs

- `GET /v1/runs` — List runs. Free.
- `GET /v1/runs/{id}` — Get a run. Free.
- `GET /v1/runs/{id}/items` — List run items. Free: the charge happened once, when the work did.

### Account

- `GET /v1/account/balance` — Get balance. Free.
- `GET /v1/account/usage` — Get usage. Free.

### Webhooks

- `POST /v1/webhooks` — Register a webhook endpoint. Free.
- `GET /v1/webhooks` — List webhook endpoints. Free.
- `GET /v1/webhooks/{id}` — Get a webhook endpoint. Free.
- `DELETE /v1/webhooks/{id}` — Delete a webhook endpoint. Free.
- `POST /v1/webhooks/{id}/rotate` — Rotate a signing secret. Free.
- `GET /v1/webhooks/{id}/deliveries` — List deliveries. Free.
- `POST /v1/webhooks/{id}/deliveries/{deliveryId}/replay` — 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. 536 credits for up to 50 enriched videos, then 10 credits each, at most 2,036 credits
- `get_research` — Read a research. Free
- `search_videos` — Search videos. 3 credits per platform searched, per page; +10 credits per enriched video with intelligence=true (top 20)
- `get_video` — Get a video. 3 credits plain; with include=intelligence 13 credits instead; transcript only 10 credits instead
- `score_video` — Score a video. 9 credits
- `get_creator` — Get a creator. 6 credits
- `get_hashtag_or_sound` — Get a hashtag or sound. hashtag 3 credits, sound 6 credits
- `search_ads` — Search ad libraries. Meta 1 credit per Ad delivered, +10 credits per Ad analysed (computed or stored); TikTok 3 credits per page
- `get_ad` — Get a Meta Ad. Ad 3 credits, +10 credits with analyze; Advertiser 15 credits
- `track` — Track a target. 6 credits per creator cycle, 30 credits per advertiser cycle, including the first one run on create; +10 credits per new video or Ad with intelligence; tracking a target you already track is free
- `list_trackers` — List trackers. Free
- `get_changes` — Get change reports. Free
- `list_collections` — List collections. Free
- `manage_collection` — Manage a collection. Free, except add on a target not tracked yet (its first cycle) and refresh (one cycle per member): 6 credits per creator, 30 credits per advertiser, +10 credits per new video with analysis
- `get_run` — Get a run. Free
- `get_usage` — Get usage. Free
- `get_balance` — Get balance. 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