# ShortsIntel API

> For the complete documentation index, see [llms.txt](https://www.shortsintel.com/llms.txt). Every docs page is also available as markdown: add .md to its URL. To connect, read [agents.md](https://www.shortsintel.com/agents.md).

> 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.

- What it is: A REST API at `/v1` and a hosted MCP server over the same operations.
- Platforms: TikTok, Instagram Reels, YouTube Shorts and Facebook videos, plus the TikTok, Meta and Google ad libraries.
- Pricing: Prepaid Credits, priced per operation. A video lookup is 3 credits.
- Free to start: Every new account gets a Starter Grant of 1,000 credits, spendable for 90 days.

ShortsIntel is an HTTPS API and a hosted MCP server for short-form video. It tells you what is working on TikTok, Instagram Reels and YouTube Shorts, who makes it, and how one video compares to its creator’s normal. Answers come back as compact JSON sized for a model’s context.

You prepay a Balance in Credits. Each operation, meaning one endpoint or MCP tool, draws its price from it. There are no seats, no contract and nothing to cancel.

## About the API

These rules hold on every charged call.

- Base URL: `https://www.shortsintel.com/v1`
- Auth header: `Authorization: Bearer sk_live_YOUR_KEY`, with a key from the console.
- Response envelope: A charged call answers with two keys, `run` and `result`. The Run records the work and its cost. `result` holds the answer. Free reads answer directly.
- Pricing model: Each charged operation draws Credits from your Balance (1,000 credits per US dollar). A cached result costs the same as a fresh one. Free reads cost nothing.
- Waiting: A charged call waits up to `wait` seconds for its result (default 30, maximum 120).
- Polling: Unfinished work answers `202` with the Run. Poll `GET /v1/runs/{id}` every 5 seconds. Polls are free.
- Limits: 60 requests a minute per key, free reads included, and 10 Runs at once per Customer.

## Find the page for your goal

| I want to | Read |
| --- | --- |
| Use ShortsIntel from Claude, Cursor or VS Code | [MCP quickstart](https://www.shortsintel.com/docs/mcp) |
| Make your first REST call | [Quickstart](https://www.shortsintel.com/docs/quickstart) |
| Wait for a slow call or read a result again | [Runs](https://www.shortsintel.com/docs/concepts/runs) |
| Know what a call costs before you spend | [Pricing and estimates](https://www.shortsintel.com/docs/concepts/pricing-and-estimates) |
| Ask one open question across a niche | [Research](https://www.shortsintel.com/docs/concepts/research) |
| Watch a creator, hashtag, sound, keyword or Advertiser over time | [Trackers](https://www.shortsintel.com/docs/concepts/trackers) |
| Get told when a Run finishes | [Webhooks](https://www.shortsintel.com/docs/concepts/webhooks) |
| Handle an error code | [Errors](https://www.shortsintel.com/docs/concepts/errors) |
| Look up an endpoint's parameters and response | [API reference](https://www.shortsintel.com/docs/reference) |
| See every TikTok operation and its price | [TikTok API](https://www.shortsintel.com/tiktok-api) |
| See every Instagram operation and its price | [Instagram API](https://www.shortsintel.com/instagram-api) |
| See every YouTube Shorts operation and its price | [YouTube Shorts API](https://www.shortsintel.com/youtube-shorts-api) |
| See every Meta Ad Library operation and its price | [Meta Ad Library API](https://www.shortsintel.com/meta-ad-library-api) |

## Make your first call

Look up one video by platform and id. Replace the placeholder with a key from the [console](https://www.shortsintel.com/console/keys) and run it.

`GET /v1/videos/{platform}/{id}` · 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.

```bash
curl "{BASE}/v1/videos/tiktok/7300000000000000000" \
  -H "Authorization: Bearer sk_live_YOUR_KEY"

# A link to the file, valid until download_expires_at
curl "{BASE}/v1/videos/tiktok/7300000000000000000?include=download" \
  -H "Authorization: Bearer sk_live_YOUR_KEY"

# Facebook: the numeric video or reel id
curl "{BASE}/v1/videos/facebook/4007941182848761" \
  -H "Authorization: Bearer sk_live_YOUR_KEY"
```

What comes back:

```json
{
  "run": {
    "id": "run_8f2c1ad04b",
    "kind": "video_lookup",
    "status": "completed",
    "created_at": "2026-09-08T09:14:02.418Z",
    "completed_at": "2026-09-08T09:14:04.930Z",
    "charge_credits": 3,
    "list_price_credits": 3,
    "cached": false
  },
  "result": {
    "platform": "tiktok",
    "id": "7300000000000000000",
    "url": "https://www.tiktok.com/@someone/video/7300000000000000000",
    "description": "3 minutes at 4°C every morning for 30 days. Here is what actually changed. #coldplunge #recovery",
    "posted_at": "2026-09-05T06:32:11.000Z",
    "duration_seconds": 41,
    "thumbnail_url": "https://p16-sign.tiktokcdn.com/obj/tos-cover-7300000000000000000.jpeg",
    "hashtags": [
      "coldplunge",
      "recovery",
      "morningroutine"
    ],
    "sound": {
      "id": "7180000000000000000",
      "title": "original sound - someone",
      "author": "someone",
      "is_original": true
    },
    "creator": {
      "id": "cre_9d4b2a7f1c",
      "handle": "someone",
      "name": "Someone",
      "follower_count": 184300,
      "avatar_url": "https://p16-sign.tiktokcdn.com/obj/tos-avatar-someone.jpeg",
      "verified": false
    },
    "region": "US",
    "language": "en",
    "title": null,
    "commerce": {
      "is_ad": false,
      "paid_partnership": null,
      "affiliate": null,
      "shop_url": null,
      "anchors": [
        {
          "kind": "54",
          "label": "CapCut · Editing made easy"
        }
      ]
    },
    "people": {
      "mentions": [
        "coldplungeco"
      ],
      "collaborators": []
    },
    "location": null,
    "topics": {
      "keywords": [],
      "genre": null,
      "labels": [
        "Fitness",
        "Health"
      ]
    },
    "chapters": null,
    "ai_generated": false,
    "is_pinned": null,
    "is_sponsored": null,
    "sponsor": null,
    "snapshot": {
      "at": "2026-09-08T09:14:04.219Z",
      "views": 1284000,
      "likes": 143200,
      "comments": 2810,
      "shares": 9040,
      "saves": 21600
    },
    "engagement": {
      "at": "2026-09-08T09:14:04.219Z",
      "views": 1284000,
      "likes": 143200,
      "comments": 2810,
      "shares": 9040,
      "saves": 21600
    },
    "scores": {
      "outlier": 4.21,
      "outlier_p90": 1.6,
      "percentile": 95,
      "velocity": {
        "views_per_hour": 6698.6,
        "window": "snapshot",
        "since": "2026-10-03T08:00:00.000Z"
      },
      "engagement_rate": 0.1376,
      "anomaly": false,
      "reason": null,
      "baseline": {
        "median_views": 305000,
        "p90_views": 802000,
        "engagement_rate": 0.1342,
        "posts_per_week": 4.1,
        "sample": 20,
        "confidence": "high",
        "source": "videos",
        "computed_at": "2026-09-08T09:14:03.902Z",
        "stale": false
      }
    }
  }
}
```

## Every charged response is a Run and its result

A Run is the record of one charged operation: its status, what it cost and whether the answer was cached. The `result` beside it is the answer itself.

When the work takes longer than the call waits, you get `202` and the Run alone. Read the Run again until it settles. The [Runs guide](https://www.shortsintel.com/docs/concepts/runs) covers the states and polling.

> **Tip:** Reading a Run again is free, as often as you like. A result you paid for stays readable from its Run.
