Skip to main content
GET /api/tasks/{id}/poll?timeout=25
Authorization: Bearer <ADMIN_API_TOKEN>
Holds the connection open for up to 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

ParamTypeDefaultDescription
timeoutint25Max 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
}
FieldTypeDescription
statusstringOne of created, notified, assigned, in_progress, submitted, verified, rejected, completed, timed_out, cancelled, verification_exhausted.
responseobject | nullSet when status is completed. The validated response per response_schema.
completed_attimestamp | nullSet on completed.
timed_out_attimestamp | nullSet on timed_out.

​
Statuses your client cares about

StatusMeaningClient action
completedHuman submitted, verifier (if any) passedUse response; you’re done.
timed_outScheduler hit timeout_atRaise TaskTimeoutError.
cancelledAgent or operator cancelledRaise TaskCancelledError.
verification_exhaustedVerifier rejected max_attempts timesRaise VerificationExhaustedError.
(anything else)Still pendingReconnect after the response; loop.

​
Errors

Statuserror_codeCause
401—Missing or wrong auth.
403—Caller isn’t operator / admin / assignee.
404TASK_NOT_FOUNDTask 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