| Endpoint essentials | |
|---|---|
| API key access | api/v1/agents/poll_task or Master API key |
| OAuth scopes | agent_task |
| Credit usage | 0 credits |
| Details | Polling only reads the task, so it never consumes credits. Credits are consumed only by the actions the Assistant performs while it works on the task. See API pricing and credits. |
An Apollo AI Assistant task is a conversation in which you give instructions, receive results, and answer follow-up questions.
Use the poll an Assistant task endpoint to check the progress of a task you created with the run an Assistant task endpoint. It returns immediately with the task's status, its messages, and a cursor. It only reads the task: it never waits for the task to finish, and it never starts or continues a task. Any instruction you send to this endpoint is ignored.
## Poll for results
Send the task_id. Omit cursor on your first poll; on later polls, pass the cursor from your previous response:
{
"task_id": "507f1f77bcf86cd799439011",
"cursor": 0
}The response returns only the messages with a sequence number strictly greater than cursor, plus a new cursor. Pass that new cursor on your next poll. An empty messages array means nothing new has been added yet; it does not mean the task has finished, so check status. Omit cursor to receive the full conversation.
While the task is running, the response includes poll_after_ms (10000, or 10 seconds). Wait that long before you poll again.
| Status | What to do |
|---|---|
running | Wait poll_after_ms, then poll again with the new cursor. |
awaiting_input | Read question, then answer by calling the run an Assistant task endpoint with the same task_id and your answer as instruction. The response also includes error_type: "elicitation_required"; this is a request for input, not an HTTP error. |
complete | Read the result. To send a follow-up, call the run an Assistant task endpoint with the same task_id and a new instruction. |
failed | Stop polling and inspect any returned messages. |
question is the latest Assistant message in the returned batch, so it appears in the poll where that message first arrives. If a later poll returns no new messages, question is null; omit cursor to read the full conversation again.
Set a polling deadline in your client and handle a task that remains running. This endpoint does not promise a fixed completion time.
Authentication and access
Use an API key with access to api/v1/agents/poll_task, or an OAuth access token with the agent_task scope. Poll with the same acting user that created the task. A task created by another user returns 403. See which user API requests act as.