API

Three on-ramps. Same data.

Subscribers hit REST endpoints with a bearer token. AI assistants connect via MCP and get a native tool surface. One-off scripts can skip the account and pay per call via x402 in USDC. All three return the same normalized post rows.

POST/api/scrape

auth: Bearer

Start a scrape job

Returns a job_id immediately. The actual run completes async (1–3 minutes); poll /api/jobs/{id} or wait on the webhook.

Body

{
  "mode": "hashtag",                  // hashtag | profile | search | url | music
  "targets": ["fyp", "booktok"],
  "max_items": 1000,
  "oldest_post_date": "2026-04-01",   // optional ISO date
  "newest_post_date": "2026-05-20",   // optional ISO date
  "sort_type": "LIKES",               // optional: RELEVANCE | LIKES | DATE
  "proxy_country_code": "US",         // optional
  "download_videos": false,
  "download_comments": false,
  "download_followers": false,        // profile mode only
  "download_following": false,        // profile mode only
  "webhook_url": "https://your-host.com/hook"   // optional
}

Response

{ "ok": true, "job_id": "job_01HX...", "credits_reserved": 1000 }

GET/api/jobs/{id}

auth: Bearer

Check job status

Returns the job row plus a 10-minute signed download URL once succeeded.

Response

{
  "job": { "status": "succeeded", "results_count": 1248, "mode": "hashtag", "targets": ["fyp"], ... },
  "preview_url": "https://...presigned..."
}

GET/api/jobs/{id}/export?format=csv|json

auth: Bearer

Download the dataset

Streams the file directly. CSV is the default; JSON returns the full normalized shape with nested author + music + video objects.

POST/api/x402/scrape

auth: none · x402

Pay-per-call (agents)

No account, no API key. Returns 402 with payment terms; sign and retry with X-Payment header. Synchronous; capped at 500 results per call.

Body

{
  "mode": "hashtag",
  "targets": ["runtok"],
  "max_items": 50,
  "download_comments": false,
  "sort_type": "LIKES"
}

Response

// 402 Payment Required (initial)
{ "x402Version": 1, "accepts": [{ "scheme":"exact", "network":"eip155:8453", "maxAmountRequired": "1250000", ... }] }

// 200 OK (after settled X-Payment header)
{ "ok": true, "count": 47, "posts": [...], "payment": { "tx_hash": "0x..." } }

HTTP/api/mcp

MCP · Streamable HTTP + SSE

Model Context Protocol server

Drop our tool surface into any MCP host (Cursor, Claude desktop, ChatGPT GPTs, the AI SDK). Seven tools: scrape_tiktok, get_job_status, export_job_results, list_jobs, get_credit_balance, list_plans, whoami. Auth: Bearer API key minted in the dashboard (Scale plan).

Body

// .cursor/mcp.json (Cursor / any Streamable HTTP host)
{
  "mcpServers": {
    "tiktok-scout": {
      "url": "https://tiktok-scout.0p.studio/api/mcp",
      "headers": { "Authorization": "Bearer tks_live_..." }
    }
  }
}

Response

// Tool call: scrape_tiktok
{
  "mode": "hashtag",
  "targets": ["fyp", "booktok"],
  "max_items": 250
}
→ { "ok": true, "job_id": "...", "credits_reserved": 250, "poll_with": { ... } }

// One request. Streaming results.
const res = await fetch("https://tiktok-scout.0p.studio/api/scrape", {
  method: "POST",
  headers: {
    "Authorization": "Bearer ${API_KEY}",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    mode: "hashtag",
    targets: ["fyp", "booktok"],
    max_items: 1000,
    download_comments: true,
  }),
});

const { job_id } = await res.json();
// → poll /api/jobs/${job_id} or wait on the webhook

Schema

Every post row.

{
  "id": "7421...",
  "url": "https://www.tiktok.com/@user/video/...",
  "createdAt": "2026-05-19T10:42:00Z",
  "text": "post caption...",
  "author": {
    "username": "cookwithbri",
    "nickname": "Bri",
    "verified": true,
    "followers": 482000,
    "hearts": 12400000,
    "videos": 312,
    "region": "US"
  },
  "music": {
    "title": "Original Sound · @cookwithbri",
    "author": "cookwithbri",
    "original": true,
    "id": "7012..."
  },
  "video": {
    "url": "https://...mp4",
    "urlNoWatermark": "https://...mp4",
    "cover": "https://...jpg",
    "duration": 28,
    "subtitles": [{"language":"en","url":"https://..."}]
  },
  "stats": {
    "plays": 1281429,
    "hearts": 182403,
    "shares": 8421,
    "comments": 4192,
    "saves": 2104
  },
  "hashtags": ["cooking", "recipe"],
  "mentions": ["@friend"]
}

Rate limits

· REST: 60 jobs / min / key
· x402: 5 req / sec / payer address
· Max results per job: 50,000 (REST) · 500 (x402)