Use these endpoints to give Apollo natural-language instructions for prospecting, research, and other sales activities. You can start a task, retrieve progress and results, answer clarification questions, and send follow-up instructions in a conversation.
Key concepts
| Tasks and conversations | An AI assistant task is a conversation that includes your instructions and the assistant's responses. It's separate from a sequence task, such as a call reminder or manual email task. |
| Identifying a task | Starting a task returns a task_id. Use that ID to retrieve results and continue the conversation. Each request without a task_id starts a new conversation. |
| Running and polling | Running a task submits an instruction for the assistant to work on. Polling retrieves its progress and messages. A task can be running, awaiting_input, complete, or failed. |
| Conversation history | Poll responses include a cursor that marks your place in the conversation. Pass it with the next poll to retrieve only new messages, or omit it to retrieve the full conversation. |
| Permissions and credits | The assistant uses the acting user's permissions, and the same user must start and continue the task. Restricting the API key to specific endpoints doesn't restrict which actions the assistant can perform. Submitting instructions and polling do not themselves consume credits; actions such as enrichment can. See API pricing and credits. |
Choose an endpoint
| I want to . . . | Use this |
|---|---|
| Start a conversation with a natural-language instruction | Run an assistant task |
| Check progress and retrieve the assistant's messages | Poll an assistant task |
| Answer a clarification question or send a follow-up instruction | Run an assistant task with the existing task ID |
Example workflows
Find prospects and retrieve results
Ask Apollo to find prospects who match your criteria, then retrieve the assistant's findings.
- Call run an assistant task with your request as
instruction, such as "Find marketing leaders at fintech companies in New York." Omittask_idto start a new conversation and retain the returnedtask_id. - Wait for the interval returned in
poll_after_ms, then pass the task ID to poll an assistant task. Omitcursoron this first poll. Read the returned messages and retain thecursor. - Wait for the interval returned in
poll_after_ms, then resume calling poll an assistant task with the same task ID and the cursor from your last poll. Continue checking the status and retaining the latest cursor as you retrieve new messages. - When the status is
complete, review the findings. If the assistant needs clarification, follow the workflow below. If the status isfailed, stop polling and review the returned messages.
Learn more: Use the run an assistant task and poll an assistant task references for request details and response examples.
Continue a conversation
Answer the assistant's question or refine a request while keeping the conversation's context.
- Retain the
task_idfrom the original request. If the status isawaiting_input, read the assistant's question. If the status iscomplete, review the results to decide what to ask next. - Call run an assistant task with the same
task_idand your answer or follow-up asinstruction. Wait until the task isawaiting_inputorcomplete; instructions sent while it isrunningare ignored. - Resume calling poll an assistant task with the task ID and your latest cursor to retrieve new messages and results.
Learn more: Use the run an assistant task reference to explore follow-up instructions and task behavior.