| Endpoint essentials | |
|---|---|
| API key access | api/v1/agents/task or Master API key |
| OAuth scopes | agent_task |
| Credit usage | Variable, based on the actions the Assistant performs. Polling consumes 0 credits. |
| Details | Submitting a message does not itself charge credits. Actions such as enrichment can consume credits according to your plan, the action, and the data returned. There is no fixed per-task price. 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. It is separate from a CRM task created with the create a task endpoint.
Use POST /api/v1/agents/task to create, poll, and continue an Assistant task. All three operations return HTTP 200 on success. A successful submission means the instruction was accepted, not that the Assistant has completed it.
Create a task
Send an instruction without a task_id:
{
"instruction": "Find companies matching my ideal customer profile."
}Save the returned task_id. The response also includes status: "running" and a next_action polling hint. Although the hint names apollo_agent_task, API clients poll this same HTTP endpoint.
Poll for results
Wait about 10 seconds between polls. Send the task_id and omit instruction:
{
"task_id": "507f1f77bcf86cd799439011"
}The response includes status, messages, and latest_seq_num. Messages contain seq_num, role, and flattened text. Hidden messages and non-text content are excluded.
| Status | What to do |
|---|---|
running | Continue polling. |
awaiting_input | Read question and the conversation, then submit your answer with the same task_id. The response also includes error_type: "elicitation_required"; this is a request for input, not an HTTP error. |
complete | Read the result. You can submit another instruction with the same task_id. |
failed | Stop polling and inspect any returned messages. |
For incremental polling, pass since_seq_num to receive only messages with a strictly greater sequence number:
{
"task_id": "507f1f77bcf86cd799439011",
"since_seq_num": 0
}The first poll should omit the cursor. Full polling is the simplest option. If you use a cursor, omit it when reading the final result or answering a question: question is derived from the returned message batch and can be null when that batch contains no assistant message. An empty messages array does not mean the task has finished; check status.
Set a polling deadline in your client and handle a task that remains running. This endpoint does not promise a fixed completion time or accept a webhook URL. Repeating a create request without a task_id creates another task.
Continue a task
When the status is awaiting_input or complete, send another instruction with the existing ID:
{
"task_id": "507f1f77bcf86cd799439011",
"instruction": "Yes, continue."
}The response retains the same task_id. If you submit an instruction while the task is running, it is ignored: the endpoint returns the current polling result and a note explaining that you should wait. It does not queue that instruction for later.
Authentication and access
Use an API key with access to api/v1/agents/task, or an OAuth access token with the agent_task scope. Use the same acting user for the task's lifetime. See which user API requests act as.
The Assistant can perform actions using that user's permissions. Restricting the API key to specific endpoints does not restrict which actions the Assistant can perform.