Skip to content

Quickstart

Get your first reel analyzed in under 5 minutes.

Step 1: Get an API token

  1. Sign in at app.instatollm.com
  2. Go to API Tokens in the sidebar
  3. Click Create, enter a name (e.g. my-script), click Create
  4. Copy the token — it's shown once only

Your token looks like: ist_aBcDeFgHiJkLmNoPqRsTuVwX

Step 2: Submit a Reel

curl -X POST https://api.instatollm.com/api/v1/reels/analyze \
  -H "Authorization: Bearer ist_your_token_here" \
  -H "Content-Type: application/json" \
  -d '{"url": "https://www.instagram.com/reel/DYa0IXPgnP5/"}'

import httpx

BASE = "https://api.instatollm.com"
TOKEN = "ist_your_token_here"
HEADERS = {"Authorization": f"Bearer {TOKEN}"}

resp = httpx.post(
    f"{BASE}/api/v1/reels/analyze",
    headers=HEADERS,
    json={"url": "https://www.instagram.com/reel/DYa0IXPgnP5/"},
)
data = resp.json()
job_id = data["id"]
print(f"Job started: {job_id}")

const BASE = "https://api.instatollm.com";
const TOKEN = "ist_your_token_here";

const resp = await fetch(`${BASE}/api/v1/reels/analyze`, {
  method: "POST",
  headers: {
    Authorization: `Bearer ${TOKEN}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({ url: "https://www.instagram.com/reel/DYa0IXPgnP5/" }),
});

const { id } = await resp.json();
console.log("Job started:", id);

Response: 

{ "id": 42, "status": "pending" }

Step 3: Poll for the result

curl https://api.instatollm.com/api/v1/reels/42 \
  -H "Authorization: Bearer ist_your_token_here"

import time

def wait_for_result(job_id: int, timeout: int = 120) -> dict:
    deadline = time.time() + timeout
    while time.time() < deadline:
        resp = httpx.get(f"{BASE}/api/v1/reels/{job_id}", headers=HEADERS)
        data = resp.json()
        if data["status"] == "done":
            return data["result"]
        if data["status"] == "error":
            raise RuntimeError(data.get("error", "analysis failed"))
        time.sleep(5)
    raise TimeoutError("analysis timed out")

result = wait_for_result(job_id)
print(result["summary"])
print("Text on screen:", result["visual"]["text_on_screen"])

async function waitForResult(id, timeoutMs = 120_000) {
  const deadline = Date.now() + timeoutMs;
  while (Date.now() < deadline) {
    const r = await fetch(`${BASE}/api/v1/reels/${id}`, {
      headers: { Authorization: `Bearer ${TOKEN}` },
    });
    const data = await r.json();
    if (data.status === "done") return data.result;
    if (data.status === "error") throw new Error(data.error);
    await new Promise((res) => setTimeout(res, 5000));
  }
  throw new Error("timeout");
}

const result = await waitForResult(id);
console.log(result.summary);
console.log("OCR:", result.visual.text_on_screen);

Step 4: Use the result

The result object contains everything extracted from the Reel. See the full schema →

# Extract what you need
summary      = result["summary"]
transcript   = result["audio"]["transcript"]
text_ocr     = result["visual"]["text_on_screen"]   # menus, signs, links, etc.
topics       = result["content"]["topics"]
key_moments  = result["content"]["key_moments"]
duration     = result["metadata"]["estimated_duration_s"]
uploader     = result["platform_meta"]["uploader"]
views        = result["platform_meta"]["view_count"]

Complete example (Python)

import time
import httpx

BASE = "https://api.instatollm.com"
TOKEN = "ist_your_token_here"
HEADERS = {"Authorization": f"Bearer {TOKEN}"}

def analyze_reel(url: str) -> dict:
    # Submit
    r = httpx.post(
        f"{BASE}/api/v1/reels/analyze",
        headers=HEADERS,
        json={"url": url},
    )
    r.raise_for_status()
    job_id = r.json()["id"]

    # Poll
    for _ in range(24):  # max 2 minutes
        time.sleep(5)
        r = httpx.get(f"{BASE}/api/v1/reels/{job_id}", headers=HEADERS)
        data = r.json()
        if data["status"] == "done":
            return data["result"]
        if data["status"] == "error":
            raise RuntimeError(f"Analysis failed: {data.get('error')}")

    raise TimeoutError("Timed out waiting for analysis")


result = analyze_reel("https://www.instagram.com/reel/DYa0IXPgnP5/")

print("Summary:", result["summary"])
print("Language:", result["audio"]["language"])
print("Text on screen:", ", ".join(result["visual"]["text_on_screen"]))
print("Topics:", ", ".join(result["content"]["topics"]))
print(f"Duration: {result['metadata']['estimated_duration_s']}s")
print(f"Views: {result['platform_meta'].get('view_count', 'N/A')}")