Skip to main content
When you call POST /v1/agents/{agent_id}/run, the response returns immediately with a task_id and status: "running". The agent is still working in the background. To get the final result you poll one of the task-read endpoints until status is terminal. If you’d rather not build a polling loop, async=false holds the connection and returns the result on the same call — see Get the result on the same call. Polling is still the better fit for runs that take more than a few minutes.

Pick the right endpoint to poll

A typical production loop looks like: poll /v1/tasks/{task_id} on a backoff schedule; once status hits a terminal value, call /summary once.

Terminal vs non-terminal statuses

A real polling loop

Start your polling interval at 1–2 seconds and back off to ~10 seconds. The status endpoint is cheap, but tight loops still burn through rate limit budget for no benefit. Most tasks take seconds to minutes.

Get the result on the same call

If your caller can afford to wait, add async=false and the API holds the connection until the run finishes, then returns the result. One call, no polling loop.
A finished run comes back like this:
Set your client timeout above X-Sync-Budget-Seconds. Every response carries this header — the longest the API may hold that request. If your client gives up first you lose the result and the task_id you would need to fetch it.

Choose what comes back

result tells the API which payload you want. Set it on the request, or once on the agent in Settings → Synchronous run result so your callers don’t have to repeat it. These are the same payloads the polling endpoints return, just delivered on the original call.
result is required. If you leave it off and the agent has no default set, the request is rejected with 400 rather than guessing which payload you wanted.

Read the response

Check outcome to see how the wait ended. Don’t match on message — it’s human-readable text and may change. Two things to know:
  • A run that failed still returns 200. The HTTP call worked; the run didn’t. Check status for how the run itself went.
  • task_id is on every response, so you can always collect a run however the wait ended.

Keep your polling fallback

async=false can decline to wait and answer with the ordinary 201 plus X-Sync-Budget-Seconds: 0. That happens when synchronous responses aren’t enabled for your agent, when the run is queued behind the agent’s concurrency limit, or when the server is already holding as many requests as it allows.
Treat async=false as a speed-up, not a replacement for polling. Every integration still needs the polling path for the 202 and 201 cases.

Large results

Responses are capped. If the payload is bigger than the cap you still get 200, but with result_status: "too_large", the real size in result_bytes, and no result — fetch it from the matching endpoint in the table above. The full reasoning trail (result=feed) is the likeliest to hit this; summary and tool:<tool_name> rarely do.

Rate limits

/v1 can be rate limited per API key, switched on per environment. Where it’s on, going over returns 429 with Retry-After in seconds. The limit is shared across the whole /v1 surface rather than per endpoint, so the polls in your loop draw on the same budget as your runs — another reason to back off rather than poll tightly.

Cancelling

If you no longer want the result, send POST /v1/tasks/{task_id}/cancel. The task moves to stopped. The step currently executing on the worker is not interrupted; it finishes naturally, but no further steps are scheduled. Cancel is idempotent: calling on an already-terminal task returns the current state with 200.

Tasks that legitimately take a long time

Some agents do work that takes minutes (multi-step research, large document extraction). A few rules of thumb:
  • Keep your client-side timeout generous (≥10 minutes) for those agents.
  • Don’t poll faster than every couple of seconds; you won’t get the answer any sooner.
  • For very long jobs, persist the task_id and poll from a background worker, not a user-facing HTTP request.