Task Lifecycle

Every call to Submit a Task creates a new task and immediately returns its task_id. The task is then dispatched, queued, and executed on the server, and eventually settles in a final status. You read its latest state with Retrieve a Task.

Statuses at a glance

`status`	Meaning	Final	`credits`
`queued`	Accepted and stored, waiting to be dispatched		Reserved
`dispatching`	Being dispatched, or the dispatch outcome is being confirmed		Reserved
`pending`	Dispatched and waiting in the platform queue		Reserved
`running`	Asking the AI platform and capturing the answer		Reserved
`succeeded`	An answer was captured	✓	Charged
`failed`	Failed; see `error_code` for the reason	✓	0 (released)
`canceled`	The task was canceled	✓	0 (released)

Only succeeded, failed, and canceled are final — once a task reaches one of them, it normally doesn’t change again (in rare cases an operator rerun can replace a final result with a newer one — reconcile against the latest read). For how credits work, see Billing & Credits.

submit ──▶ queued ──▶ dispatching ──▶ pending ⇄ running ──▶ succeeded
                                                        ──▶ failed
                                                        ──▶ canceled

A few things to keep in mind:

A task can fail at several stages. The API key became invalid before dispatch (queued → failed), the dispatch was rejected (dispatching → failed), or the platform crawl failed (running → failed). Queued or running tasks can also be canceled (→ canceled).
pending and running can alternate. When a P2 task hits a retryable failure (network issue, temporary platform error), it goes back to the queue and runs once more. started_at is reset to 0 and recorded again when execution restarts.
dispatching is not a failure. When the dispatch outcome needs confirming, the task stays in dispatching with error_code set to dispatch_uncertain. The server confirms it on its own and never dispatches twice. Decide success or failure from status only — a non-empty error_code doesn’t mean the task failed.
A successful answer can be short. succeeded only means the platform returned an answer. An empty source list or a very short answer can be perfectly normal (some questions don’t trigger a web search on the platform).

Timing expectations

The crawl itself usually takes anywhere from tens of seconds to two minutes, depending on the platform and the length of the answer; with thinking mode on, it’s usually noticeably slower. Platforms differ a lot; use p50_duration_seconds from List Platforms as a reference (the median time from submission to completion for successful tasks over the last 24 hours, queueing included).
Queueing has no upper bound and no SLA. When a platform is busy or its accounts are temporarily unavailable, P2 tasks stay in the queue until it recovers, which can take a while. P1 tasks are dequeued first, but there’s still no guarantee they start within seconds. See Platforms, Priority & Country for how the two tiers differ.
There’s no server-side execution deadline. A task is never marked as failed just because it waited too long, and it doesn’t expire once its monitor_date has passed.

Polling: how often to check

The server syncs the progress of unfinished tasks roughly every 15 seconds, and Retrieve a Task returns that synced, stored state. So:

Poll about every 15 seconds. Polling more often usually just returns the same status.
With many tasks in flight, run a single scheduled loop that checks every unfinished task_id in a batch, rather than blocking a thread per task.
Feel free to set your own business timeout (say, stop waiting after 30 minutes), but don’t treat a timeout as a failure: the task keeps running, and you can fetch the result with its task_id at any time later.
Retrieving a task doesn’t cost credits.

Synchronous wait: `wait_seconds`

If you’d rather not write a polling loop, pass wait_seconds (0–120) when submitting. The server checks the task every 2 seconds during that window and returns as soon as the task reaches a final status, or when the time is up.

0 (default): don’t wait — return the queued task immediately.
If time runs out before the task finishes, you get a non-final task back and still need to keep polling by task_id.
Set your HTTP client timeout longer than wait_seconds (for example, 15 extra seconds). How long you can actually wait is also capped by proxy timeouts along the network path. If the connection drops mid-wait, the task isn’t affected — recover its task_id as described in the next section and keep polling.
The synchronous wait only changes when this HTTP request returns. It doesn’t make the task run faster or slower, and it doesn’t affect billing.

Avoiding duplicate submissions

Every call to the submit endpoint creates a new task, and each one is billed if it succeeds. The server doesn’t deduplicate by question. So when you’re not sure whether a previous submission went through (the request timed out, the connection dropped, your process crashed), don’t just retry the submission. Instead:

Call List Tasks with the question text as keyword (up to 256 characters — for a longer question, pass its first 256), or narrow it down with start_time / end_time, to find the task_id of that submission.
If you find it, keep polling it. Only if you’ve confirmed it isn’t there should you submit again.

In your own system, write a “to submit” record first and save the task_id as soon as you get it back, so you can always reconcile.

What `monitor_date` means

monitor_date is the task’s business date (YYYY-MM-DD, Beijing time, UTC+8), defaulting to the day of submission. It labels which day’s monitoring the task belongs to, so you can file and reconcile results by day:

It’s not a scheduled run time: tasks enter the queue as soon as they’re submitted, not on that date.
It’s not a deadline: tasks still run after that date has passed.
Systems in other time zones can pass an RFC 3339 timestamp with an offset (such as 2026-10-26T09:30:00-07:00); the server converts it to the corresponding Beijing-time date.

No callbacks

Webhook callbacks aren’t available yet — poll to get task results.

Retrieve a TaskRead a task's status and result by task_id.

Error HandlingWhat each error_code on a failed task means and what to do about it.