Documentation Index
Fetch the complete documentation index at: https://docs.awaithumans.dev/llms.txt
Use this file to discover all available pages before exploring further.
GET /api/tasks/{id}/poll?timeout=25
Authorization: Bearer <ADMIN_API_TOKEN>
timeout seconds (default 25, max 30). Returns immediately when the task transitions to a terminal status. If still pending after the timeout, returns the current status and the client reconnects.
Why long-polling
Plain GET /api/tasks/{id} works for one-shot reads, but agents waiting on tasks need either polling (every second → DB load + latency) or long-polling (one connection, server pushes when state changes). awaithumans uses long-polling because:
- One connection per task, parked at the server
- Server-side detection of terminal transitions (no polling cost)
- Any HTTP client works (no WebSockets / SSE complexity)
The SDK reconnects every ~25 seconds, well under typical gateway timeouts (60s).
Query params
| Param | Type | Default | Description |
|---|
timeout | int | 25 | Max seconds to hold the connection (1–30). |
Response
HTTP/1.1 200 OK
Content-Type: application/json
{
"status": "completed",
"response": { "approved": true, "notes": "Duplicate charge confirmed." },
"completed_at": "2026-05-12T08:05:23.456Z",
"timed_out_at": null
}
| Field | Type | Description |
|---|
status | string | One of created, notified, assigned, in_progress, submitted, verified, rejected, completed, timed_out, cancelled, verification_exhausted. |
response | object | null | Set when status is completed. The validated response per response_schema. |
completed_at | timestamp | null | Set on completed. |
timed_out_at | timestamp | null | Set on timed_out. |
Statuses your client cares about
| Status | Meaning | Client action |
|---|
completed | Human submitted, verifier (if any) passed | Use response; you’re done. |
timed_out | Scheduler hit timeout_at | Raise TaskTimeoutError. |
cancelled | Agent or operator cancelled | Raise TaskCancelledError. |
verification_exhausted | Verifier rejected max_attempts times | Raise VerificationExhaustedError. |
| (anything else) | Still pending | Reconnect after the response; loop. |
Errors
| Status | error_code | Cause |
|---|
| 401 | — | Missing or wrong auth. |
| 403 | — | Caller isn’t operator / admin / assignee. |
| 404 | TASK_NOT_FOUND | Task ID doesn’t exist. |
Polling vs webhooks
For agents that block on await_human() long enough that polling cost matters, use the Temporal or LangGraph adapters — they replace polling with workflow signals via the callback_url mechanism.
For everything else (Flask handlers, scripts, simple async loops), polling is fine. The cost: one HTTP connection per pending task, held for ~25s at a time.
SDK equivalent
# Python — happens automatically inside await_human()
from awaithumans import await_human_sync
decision = await_human_sync(...) # internal polling loop
// TypeScript
import { awaitHuman } from "awaithumans";
const decision = await awaitHuman({ ... }); // internal polling loop
