Getting started
REST 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.
Five minutes, five steps: get a key, spend a fraction of a cent on one video, read what comes back, learn how to wait for the slow calls, and find out what a call costs before you make it. Every sample below is generated from the same registry the API is served from, in curl, TypeScript and Python — pick a language once and the whole site follows.
1. Create a key
Keys are made in the console. A key is shown once, at creation, and stored only as a hash afterwards, so copy it then; if you lose it, make another and revoke the old one. Every request carries it as a bearer token:
Authorization: Bearer sk_live_YOUR_KEYSpending is prepaid: you top a Balance up and each operation draws from it. Check it any time — reading the Balance is free.
GET /v1/account/balance·Free.
curl "https://www.shortsintel.com/v1/account/balance" \
-H "Authorization: Bearer sk_live_YOUR_KEY"const response = await fetch(
"https://www.shortsintel.com/v1/account/balance",
{
method: "GET",
headers: {
"Authorization": "Bearer sk_live_YOUR_KEY",
},
},
);
if (!response.ok) {
throw new Error(`ShortsIntel ${response.status}`);
}
const data = await response.json();import requests
response = requests.get(
"https://www.shortsintel.com/v1/account/balance",
headers={
"Authorization": "Bearer sk_live_YOUR_KEY",
},
)
response.raise_for_status()
data = response.json()GET /v1/account/balance · Free.
2. Make the first call
The cheapest call that returns something worth reading looks one video up by platform and id. Swap the placeholder for your key and run it.
GET /v1/videos/{platform}/{id}·$0.005 fresh, $0.00125 cached. With `include=intelligence`: $0.02 fresh, $0.005 cached, instead of the lookup price (`refresh=true` is always fresh). With `include=transcript` only: a flat $0.005, cached or not.
curl "https://www.shortsintel.com/v1/videos/tiktok/7300000000000000000" \
-H "Authorization: Bearer sk_live_YOUR_KEY"const response = await fetch(
"https://www.shortsintel.com/v1/videos/tiktok/7300000000000000000",
{
method: "GET",
headers: {
"Authorization": "Bearer sk_live_YOUR_KEY",
},
},
);
if (!response.ok) {
throw new Error(`ShortsIntel ${response.status}`);
}
const data = await response.json();import requests
response = requests.get(
"https://www.shortsintel.com/v1/videos/tiktok/7300000000000000000",
headers={
"Authorization": "Bearer sk_live_YOUR_KEY",
},
)
response.raise_for_status()
data = response.json()200 · The Run finished inside the wait budget: `{ run, result }`. With `estimate=true`, `{ estimate_usd, cached }` instead.
{
"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_usd": 0.005,
"list_price_usd": 0.005,
"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"
},
"creator": {
"id": "cre_9d4b2a7f1c",
"handle": "someone",
"name": "Someone",
"follower_count": 184300
},
"snapshot": {
"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"
},
"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
}
}
}
}3. Read the envelope
Every operation answers in the same two-part shape: a run describing the work — its id, its status, what it charged — and a result holding what the work produced. The id is a receipt: reading a Run again is free, forever, so you never pay twice for an answer you already have.
$0.005 fresh, $0.00125 cached. With `include=intelligence`: $0.02 fresh, $0.005 cached, instead of the lookup price (`refresh=true` is always fresh). With `include=transcript` only: a flat $0.005, cached or not. A cached answer costs less than a fresh one, and the Run says which you got.
4. Poll a Run
Slow work does not block the request. Paid operations take a wait parameter — seconds to hold the response open, 30 by default and 120 at most. Finish inside the budget and you get 200 with the result. Run out of it and you get 202 with the Run on its own:
202 · Still running: `{ run }`. Poll `GET /v1/runs/{id}`.
{
"run": {
"id": "run_8f2c1ad04b",
"kind": "video_lookup",
"status": "running",
"created_at": "2026-09-08T09:14:02.418Z",
"completed_at": null,
"charge_usd": 0,
"list_price_usd": 0,
"cached": false
}
}Both are success. Code that treats 202 as an error breaks on the first slow call. Take the id, poll GET /v1/runs/{id} every couple of seconds, and stop when status leaves running:
GET /v1/runs/{id}·Free.
curl "https://www.shortsintel.com/v1/runs/run_8f2c1ad04b" \
-H "Authorization: Bearer sk_live_YOUR_KEY"const response = await fetch(
"https://www.shortsintel.com/v1/runs/run_8f2c1ad04b",
{
method: "GET",
headers: {
"Authorization": "Bearer sk_live_YOUR_KEY",
},
},
);
if (!response.ok) {
throw new Error(`ShortsIntel ${response.status}`);
}
const data = await response.json();import requests
response = requests.get(
"https://www.shortsintel.com/v1/runs/run_8f2c1ad04b",
headers={
"Authorization": "Bearer sk_live_YOUR_KEY",
},
)
response.raise_for_status()
data = response.json()200 · `{ run, result }` for a completed or partial Run.
{
"run": {
"id": "run_123",
"kind": "video_lookup",
"status": "completed",
"created_at": "2026-09-08T09:14:02.418Z",
"completed_at": "2026-09-08T09:14:04.930Z",
"charge_usd": 0.005,
"list_price_usd": 0.005,
"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"
},
"creator": {
"id": "cre_9d4b2a7f1c",
"handle": "someone",
"name": "Someone",
"follower_count": 184300
},
"snapshot": {
"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"
},
"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
}
}
}
}Polling is always free. The Runs guide covers the other two states — partial and failed — and what each one charges.
5. Price a call before you make it
Almost every paid operation accepts estimate=true: it answers with what the call would cost from what is already stored, creates no Run and charges nothing. The exceptions are POST /v1/trackers and POST /v1/trackers/{id}/refresh: they take no estimate and charge when called, so read the price on their reference entry first. Ask first when a call is expensive or when an agent is deciding whether to make it at all.
GET /v1/videos/{platform}/{id}·$0.005 fresh, $0.00125 cached. With `include=intelligence`: $0.02 fresh, $0.005 cached, instead of the lookup price (`refresh=true` is always fresh). With `include=transcript` only: a flat $0.005, cached or not.
curl "https://www.shortsintel.com/v1/videos/tiktok/7300000000000000000?estimate=true" \
-H "Authorization: Bearer sk_live_YOUR_KEY"const response = await fetch(
"https://www.shortsintel.com/v1/videos/tiktok/7300000000000000000?estimate=true",
{
method: "GET",
headers: {
"Authorization": "Bearer sk_live_YOUR_KEY",
},
},
);
if (!response.ok) {
throw new Error(`ShortsIntel ${response.status}`);
}
const data = await response.json();import requests
response = requests.get(
"https://www.shortsintel.com/v1/videos/tiktok/7300000000000000000?estimate=true",
headers={
"Authorization": "Bearer sk_live_YOUR_KEY",
},
)
response.raise_for_status()
data = response.json()200 · With `estimate=true`: the price, no Run, no charge.
{
"estimate_usd": 0.005,
"cached": false
}cached tells you whether the answer is already stored, which is the difference between the cached price and the fresh one.
Where to go next
- Runs — the four states, partial results, and what each one costs.
- API reference — every endpoint with its parameters, responses and price.
- MCP quickstart — the same operations as tools, for an assistant rather than your own code.