Tasks

Every crawl is a task. This page is the full reference for submitting, polling, and reading one, plus the response schema and error codes.

Submit a task

string

required

The platform, e.g. youtube, tiktok, douyin, weibo, bilibili. See /v1/task-sources for the full list.

string

required

What to do: search, posts, user, detail, comments, hot, recommended, trending, download. Not every platform supports every action.

object

required

Action parameters. The common fields:

Show params fields

string

The keyword (search) or the creator/post ref (posts, user, detail, comments). A ref may be a URL, a handle, or a bare id — Torii resolves it (including short share links).

integer

default:"24"

Max items to return.

string

Pagination token from a previous response’s next_cursor; a cursored request bypasses the cache.

integer

For posts: walk a creator’s back-catalog by item count. -1 = the entire history.

string

default:"default"

Which stored account to crawl as, for platforms that need a login.

string

Filter by media type: video (only posts with a video), image (only image posts), or omit for any.

string

Set to eager to render a hover-to-play preview clip for each new video item at crawl time (see Media & previews).

boolean

Bypass the cache and crawl live.

integer

Serve from cache only if the newest matching result is fresher than this many seconds.

curl -X POST https://api.torii.t.bldr.tw/v1/tasks \
  -H "Authorization: Bearer $TORII_TOKEN" -H "Content-Type: application/json" \
  -d '{"source":"douyin","action":"posts","params":{"query":"9HFAVeIT8VA","limit":5}}'

202 Accepted

{ "task_id": 84213, "status": "queued" }

Write verbs (publishing) are irreversible: they return 409 needs_confirmation until you re-send with confirm: true, run a single attempt (never auto-retried), and accept an idempotency_key so a timed-out retry never double-posts.

Poll a task

Returns the task’s status; a succeeded task also carries result — the Envelope.

status	meaning
`queued`	Accepted, waiting for a worker.
`running`	Being crawled now.
`succeeded`	Done — `result` holds the envelope (including honest `blocked` / `empty` outcomes).
`failed`	The job itself errored (rare; distinct from a `blocked` envelope).
`cancelled`	Cancelled by the caller.

Retry & cancel

Re-run a finished task.

Cancel a queued or running task and release its per-account slot — useful when you’ve stopped waiting on the tail of a fan-out. Both forms do the same thing.

The Envelope

The normalized response every read returns.

boolean

true for a successful crawl (including an honest empty result); false when error is set.

string

Provenance: live (freshly crawled), cache (served from a recent crawl), empty (a real, no-results answer), or blocked (the platform served a bot-check / risk control). empty and blocked are different answers — render them differently.

integer

The number of items.

Item[]

The normalized cards — see Item.

string

Pass back as params.cursor for the next page.

integer

For a cache source: how old the cached result is, in seconds.

integer

How long the crawl took.

object

Set only when ok is false — { code, message, retryable }. See Errors.

The Item

One normalized card — the stable consumer projection. It never ranks or scores; stats are the platform’s own raw numbers.

string

Globally unique and stable: "douyin:7412…".

string

video | image | text.

string

The platform, e.g. youtube.

string

The caption / body.

string

Display name.

string

The platform’s creator id (sec_uid, uid, …).

string

The @handle.

string

Canonical profile URL, derived centrally.

string

The post’s canonical URL.

string

A torii-hosted cover URL (/v1/media?u=…).

ItemMedia[]

{ kind: "video"|"image", url, w, h, duration_s }. URLs are torii-hosted, never a raw CDN URL. A playable stream appears on detail; the flat search/posts harvest is metadata-only for some platforms.

object

On video items — { url, w, h, seconds, status }, a low-res, muted, full-length (≤240s) scrubbable clip. See Media & previews.

integer

Created-at, unix seconds.

number

Video length in seconds (omitted when unknown).

object

{ width, height } of the media.

object

{ likes, comments, shares, views } — verbatim.

string

Per-item origin (live / cache).

Sample responses

A finished task is polled with GET /v1/tasks/{id}; the shape of its result depends on what the action returns, not the platform. There are five return shapes. Each block below is the result value (the poll wrapper { "task_id", "status": "succeeded", "result": … } is omitted for brevity).

Item cards — search · posts · hot · recommended

A normalized Envelope of Item cards. The flat harvest is metadata-only on some platforms (no playable stream until detail); preview appears on video items.

result — youtube.search

{
  "ok": true,
  "source": "live",
  "count": 2,
  "ms": 1840,
  "next_cursor": "20",
  "items": [
    {
      "id": "youtube:jNQXAC9IVRw",
      "type": "video",
      "provider": "youtube",
      "title": "Me at the zoo",
      "text": "The first video on YouTube.",
      "author": "jawed",
      "author_id": "UC4QobU6STFB0P71PMvOGN5A",
      "author_handle": "@jawed",
      "author_url": "https://www.youtube.com/@jawed",
      "url": "https://www.youtube.com/watch?v=jNQXAC9IVRw",
      "thumb": "/v1/media?u=…",
      "media": [{ "kind": "video", "url": "/v1/media?u=…&kind=video&platform=youtube", "w": 640, "h": 480 }],
      "preview": { "url": "/v1/preview?platform=youtube&id=jNQXAC9IVRw", "w": 320, "h": 240, "seconds": 19, "status": "pending" },
      "ts": 1150908000,
      "duration_s": 19,
      "aspect": { "width": 640, "height": 480 },
      "stats": { "likes": 18500000, "comments": 12000000, "shares": 0, "views": 360000000 },
      "provenance": "live"
    },
    { "id": "youtube:…", "type": "video", "provider": "youtube", "…": "…" }
  ]
}

Detail — one post with a playable stream

detail re-resolves a single ref to a full Item including a playable media[].url (and, on video, a preview). Use it when the flat search/posts harvest was metadata-only.

result — douyin.detail

{
  "ok": true,
  "source": "live",
  "count": 1,
  "ms": 920,
  "items": [
    {
      "id": "douyin:7412…",
      "type": "video",
      "provider": "douyin",
      "text": "咖啡拉花教程 ☕️ #手冲",
      "author": "沁瑶学AI",
      "author_id": "MS4wLjABAAAA…",
      "author_handle": "@qinyao",
      "author_url": "https://www.douyin.com/user/MS4wLjABAAAA…",
      "url": "https://www.douyin.com/video/7412…",
      "thumb": "/v1/media?u=…",
      "media": [{ "kind": "video", "url": "/v1/media?u=…&kind=video&platform=douyin&profile=default", "w": 1080, "h": 1920, "duration_s": 43.2 }],
      "preview": { "url": "/v1/preview?platform=douyin&id=7412…", "w": 240, "h": 427, "seconds": 43, "status": "hit" },
      "ts": 1719400000,
      "duration_s": 43.2,
      "aspect": { "width": 1080, "height": 1920 },
      "stats": { "likes": 128000, "comments": 3400, "shares": 9100, "views": 2600000 },
      "provenance": "live"
    }
  ]
}

Comments — items + total

comments returns its own shape: a flat list of normalized Comments plus a total and has_more (page with params.cursor). Note it carries source, not the envelope’s ok.

result — weibo.comments

{
  "source": "live",
  "total": 40,
  "has_more": true,
  "cursor": "138…:0",
  "ms": 610,
  "items": [
    {
      "cid": "4938…",
      "text": "第一 🎉",
      "likes": 212,
      "reply_total": 3,
      "user_id": "1797…",
      "handle": "someuser",
      "user_name": "路人甲",
      "created_at": 1725000000,
      "source": "weibo",
      "url": "https://m.weibo.cn/detail/5337…",
      "parent_id": ""
    },
    { "cid": "4938…b", "text": "同意", "parent_id": "4938…", "…": "…" }
  ]
}

Creator profile — user (Data.author)

user returns a creator, not cards — identity + profile-level stats land in data.author (items is empty). A field the platform doesn’t expose comes back 0/absent — read a 0 as “not reported”, not a hard fact.

result — douyin.user

{
  "ok": true,
  "source": "live",
  "count": 0,
  "ms": 540,
  "items": [],
  "data": {
    "platform": "douyin",
    "author": {
      "id": "MS4wLjABAAAA…",
      "source": "douyin",
      "handle": "qinyao",
      "name": "沁瑶学AI",
      "bio": "每天一个AI小技巧",
      "avatar": "/v1/media?u=…",
      "url": "https://www.douyin.com/user/MS4wLjABAAAA…",
      "followers": 512000,
      "following": 43,
      "posts": 218,
      "likes": 8900000,
      "verified": true
    }
  }
}

trending returns ranked words, not posts — a board of terms in data.trends, each with a rank and (where the platform reports it) a hot_value and a search url.

result — weibo.trending

{
  "ok": true,
  "source": "live",
  "count": 0,
  "ms": 300,
  "items": [],
  "data": {
    "platform": "weibo",
    "trends": [
      { "word": "秋天的第一杯奶茶", "source": "weibo", "rank": 1, "hot_value": 1284000, "url": "https://m.weibo.cn/search?containerid=…" },
      { "word": "国庆档电影", "source": "weibo", "rank": 2, "hot_value": 987000, "url": "https://m.weibo.cn/search?containerid=…" }
    ]
  }
}

`empty` ≠ `blocked` (the honesty contract)

A no-results answer and a bot-check are different, and both are succeeded tasks — branch on source, never on an empty items.

empty — a real, honest

{ "ok": true, "source": "empty", "count": 0, "items": [] }

blocked — a captcha / risk control (retryable; do NOT prompt re-login)

{ "ok": false, "source": "blocked", "count": 0, "items": [],
  "error": { "code": "blocked", "message": "risk control", "retryable": true } }

Write verbs

A publish/delete returns a WriteResult — state is the outcome; a dry_run returns state: "planned" without posting. Send idempotency_key so a timed-out retry replays instead of double-posting.

result — weibo.comment.create (confirm:true)

{
  "ok": true,
  "state": "published",
  "target": "5337…",
  "url": "https://m.weibo.cn/detail/5337…",
  "source": "live",
  "ms": 780
}

state is one of planned (dry-run) · published · deleted · session_expired · blocked · rejected · duplicate. A duplicate means an in-flight retry of the same idempotency_key — poll the original.

Errors

When ok is false, error.code is machine-readable. Branch on it — never parse the message.

code	HTTP	meaning	what to do
`invalid_request`	400	Malformed params	Fix the request
`auth_required`	401	Missing/invalid token	Attach a valid bearer
`forbidden_scope`	403	Token lacks the scope	Use a token with the scope
`unsupported`	404	The platform lacks this action	Stop asking
`not_found`	404	The post is gone (deleted/never existed)	Stop asking — terminal
`rate_limited`	—	The platform throttled (429/418)	Back off, retry later
`blocked`	—	A bot-check / captcha / risk control	Retryable; do not prompt re-login
`session_expired`	—	The stored login lapsed	Re-login the profile, then retry
`timeout`	—	A slow upstream	Back off, retry
`duplicate`	—	A write’s `idempotency_key` is in flight	Poll the original / retry the same key
`upstream_error`	—	An unclassified upstream failure	Retry

blocked and session_expired are deliberately distinct. A blocked task is a transient challenge — retry it. Only session_expired (surfaced on /v1/profiles) means the account needs a human re-login.

Getting Started

API Reference

Submit a task

Poll a task

Retry & cancel

The Envelope

The Item

Sample responses

`empty` ≠ `blocked` (the honesty contract)

Write verbs

Errors

​Submit a task

​Poll a task

​Retry & cancel

​The Envelope

​The Item

​Sample responses

​empty ≠ blocked (the honesty contract)

​Write verbs

​Errors

Submit a task

Poll a task

Retry & cancel

The Envelope

The Item

Sample responses

`empty` ≠ `blocked` (the honesty contract)

Write verbs

Errors