Runs

Every operation you call creates a Run: one record of one piece of work, what it produced, and what it cost. Reads of a Run are free forever, so the id you get back is a receipt as much as a handle. Understanding the four states and the wait budget is the whole of handling this API correctly.

The four states

running

The work is still going. You have a Run id and nothing else yet. Poll it, or wait for the webhook.

completed

Everything asked for arrived. The result is on the Run and stays there.

partial

Some of the work landed and some did not — one platform timed out, one video could not be fetched. You are charged for what arrived and nothing else.

failed

Nothing usable came back. Nothing is charged. The Run carries a problem body saying why.

A Run only ever moves out of running once. It never goes back, and a finished Run is never re-run by reading it.

Waiting inline

Most calls finish fast enough to answer in the request. Paid operations take a wait parameter: the number of seconds to hold the response open before giving up and handing you the Run to poll. It defaults to 30 seconds and caps at 120.

Finish inside the budget and you get 200 with { run, result }. Run out of budget and you get 202 with { run } — same work, still happening, just no longer in this response. Both are success. Code that treats 202 as an error will break on the first slow call.

curl "{BASE}/v1/videos/tiktok/7300000000000000000" \
  -H "Authorization: Bearer sk_live_YOUR_KEY" \
  -G --data-urlencode "wait=120"

Polling

GET /v1/runs/{id} returns the Run in the same envelope the original call would have. Poll it every couple of seconds until status leaves running.

curl "{BASE}/v1/runs/run_123" \
  -H "Authorization: Bearer sk_live_YOUR_KEY"

Long operations are better served by a webhook than by a loop, but polling is always available and always free.

Re-reads are free

Free. Reading a Run does not repeat the work and does not charge again — the charge happened once, when the work did. Store the Run id and you can fetch the same result tomorrow without paying for it twice. Someone else’s Run id is a 404, not a 403: you cannot learn that a Run exists unless it is yours.

Partial results and what you pay for

Operations that fan out — a search across three platforms, a research pass over fifty videos — deliver one item at a time. When some items fail, the Run ends partial rather than throwing away the ones that worked.

GET /v1/runs/{id}/items lists them, each with its own status, its own charge and, where it failed, the problem body explaining why. Charging follows the same line: an item that arrived is charged, up to what the Balance covers, and an item that failed is not. A failed Run costs nothing at all.

curl "https://www.shortsintel.com/v1/runs/run_123/items?type=videos" \
  -H "Authorization: Bearer sk_live_YOUR_KEY"

A shape that works

1. Call the operation with a wait you are happy to block for.
2. On 200, use the result. On 202, keep the Run id.
3. Poll GET /v1/runs/{id} until the status settles.
4. On partial, read the items to see what is missing before deciding whether to ask again.

Want the price before any of that happens? Almost every paid operation accepts estimate, which returns what the call would cost and creates no Run. 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. See the reference for the operations that take it.