Task and call lifecycle
Follow a call from acceptance to its final outcome.
Content reviewed · Maintained by Cleo Powered · Report a documentation issue · Verification basis
Call states
The call state describes observed telephony progress. Not every intermediate state appears between polls.
- State
- queued
- Terminal
- No
- Meaning
- Work is durably admitted; dialing is not yet confirmed.
- State
- dialing
- Terminal
- No
- Meaning
- The calling service is dialing.
- State
- ringing
- Terminal
- No
- Meaning
- The destination is ringing.
- State
- in_progress
- Terminal
- No
- Meaning
- The call is active.
- State
- completed
- Terminal
- Yes
- Meaning
- The call ended. Read its outcome and evidence.
- State
- failed
- Terminal
- Yes
- Meaning
- Execution could not start or finish; inspect the saved details.
- State
- cancelled
- Terminal
- Yes
- Meaning
- Queued work was cancelled locally or the external stop was confirmed.
| State | Terminal | Meaning |
|---|---|---|
| queued | No | Work is durably admitted; dialing is not yet confirmed. |
| dialing | No | The calling service is dialing. |
| ringing | No | The destination is ringing. |
| in_progress | No | The call is active. |
| completed | Yes | The call ended. Read its outcome and evidence. |
| failed | Yes | Execution could not start or finish; inspect the saved details. |
| cancelled | Yes | Queued work was cancelled locally or the external stop was confirmed. |
Execution stages
execution.stage explains dispatch and cancellation independently of call state. A call can still show queued while its submission is uncertain.
- Stage
- queued
- Meaning
- Persisted and waiting for dispatch capacity.
- Client action
- Follow the same call ID; cancel if no longer wanted.
- Stage
- submitting
- Meaning
- The executor has claimed dispatch and may be contacting telephony.
- Client action
- Keep polling; do not submit a replacement.
- Stage
- reconciling
- Meaning
- Gateway acceptance or status needs confirmation.
- Client action
- Keep the same task, call, payload, and idempotency key.
- Stage
- running
- Meaning
- Telephony accepted the call.
- Client action
- Read call state for dialing, ringing, or conversation progress.
- Stage
- cancel_requested
- Meaning
- A stop is requested; external confirmation is pending.
- Client action
- Continue following the same call until a terminal outcome.
- Stage
- cancelled
- Meaning
- Cancellation is complete.
- Client action
- Stop active-call polling.
- Stage
- failed
- Meaning
- Execution ended without successful completion.
- Client action
- Review the error and outcome; a new call needs deliberate approval.
- Stage
- completed
- Meaning
- The call ended and execution is complete.
- Client action
- Inspect summary, extraction status, and evidence.
| Stage | Meaning | Client action |
|---|---|---|
| queued | Persisted and waiting for dispatch capacity. | Follow the same call ID; cancel if no longer wanted. |
| submitting | The executor has claimed dispatch and may be contacting telephony. | Keep polling; do not submit a replacement. |
| reconciling | Gateway acceptance or status needs confirmation. | Keep the same task, call, payload, and idempotency key. |
| running | Telephony accepted the call. | Read call state for dialing, ringing, or conversation progress. |
| cancel_requested | A stop is requested; external confirmation is pending. | Continue following the same call until a terminal outcome. |
| cancelled | Cancellation is complete. | Stop active-call polling. |
| failed | Execution ended without successful completion. | Review the error and outcome; a new call needs deliberate approval. |
| completed | The call ended and execution is complete. | Inspect summary, extraction status, and evidence. |
execution.error_code can explain uncertainty, such as submission_unconfirmed or cancellation_unconfirmed, or a permission failure before dispatch. It is null when no execution error is recorded. A historical call may have execution: null.
If bounded recovery reaches reconciliation_required, automatic recovery has paused for operator review. Keep the same ID and contact the service operator; repeated syncs do not restart recovery or authorize another call. The call remains nonterminal until its outcome is resolved.
Queued cancellation finishes locally before dispatch. If dispatch may have started, cancellation remains pending until the gateway confirms a terminal outcome. The call may finish naturally first; inspect the returned terminal state rather than assuming every request ends as cancelled.
Keep state current
Save both id and task_id. Use the call id with GET /v1/calls/{call_id} for saved state or POST /v1/calls/{call_id}/sync for a refresh. Sync returns local state for undispatched or recovering jobs; it does not submit a second call. Poll every few seconds within a bounded budget and honor rate limits.
HTTP 202 means durable acceptance, not confirmed dialing or a successful errand. If a create response is lost, recover the unchanged request with the same idempotency key. If the ID is known, keep polling it. Neither a timeout nor a failed refresh authorizes a new task or call.
See calls in the platform
API and platform submissions use the same task executor and workspace-owned task/call records. The platform shows progress and results for that workspace. A terminal call can still have pending result preparation; check the same record later if needed. A queue is not an automatic retry schedule, callback workflow, or permission to place additional calls.