This walkthrough kicks off an agent, polls its status, and fetches the final answer —
the minimum end-to-end flow.
Prerequisites
- A Nanonets workspace with at least one agent.
- A workspace API key. See Authentication for how to mint one.
- The agent’s UUID — visible in the dashboard URL when you open the agent.
1. Start a task
curl -X POST https://agents.nanonets.com/api/v1/agents/$AGENT_ID/run \
-H "Authorization: Bearer $NANONETS_API_KEY" \
-H "Content-Type: application/json" \
-d '{"query": "Summarize the attached document."}'
task_id immediately — the agent runs asynchronously.
{
"task_id": "f1c2a3b4-...",
"agent_id": "...",
"status": "running",
"message": "Task created successfully. Use GET /v1/tasks/{task_id} to check status.",
"created_at": "2026-05-11T10:15:00Z"
}
2. Attach files (optional)
For agents that take documents as input, send multipart/form-data instead:
curl -X POST https://agents.nanonets.com/api/v1/agents/$AGENT_ID/run \
-H "Authorization: Bearer $NANONETS_API_KEY" \
-F "query=Extract line items from this invoice." \
-F "files=@invoice.pdf" \
-F 'output_config={"output_schema":"{\"line_items\":[{\"sku\":\"string\",\"qty\":\"number\"}]}"}'
files once per file.
3. Poll for the result
Lightweight status check:
curl https://agents.nanonets.com/api/v1/tasks/$TASK_ID \
-H "Authorization: Bearer $NANONETS_API_KEY"
status becomes completed, fetch the answer:
curl https://agents.nanonets.com/api/v1/tasks/$TASK_ID/summary \
-H "Authorization: Bearer $NANONETS_API_KEY"
Use /summary for production polling — it returns just the final result. Use /result
during development to see the full reasoning trace.
4. Reply when the agent asks
If the agent needs more input mid-task, the status becomes waiting_for_input. Continue
the conversation with:
curl -X POST https://agents.nanonets.com/api/v1/tasks/$TASK_ID/message \
-H "Authorization: Bearer $NANONETS_API_KEY" \
-H "Content-Type: application/json" \
-d '{"message": "Use the second invoice line, not the first."}'
status is terminal.
Terminal vs non-terminal status
| Status | Meaning | Next action |
|---|
pending, queued, running | Still working | Keep polling |
waiting_for_input | Agent called ask_user | Send a message |
awaiting_review | Human approval needed | Approve in the dashboard |
completed | Done — answer is ready | Fetch /summary |
failed, stopped | Terminal, no answer | Inspect /result for details |
