Skip to content
cleo.Developers
API reference/Sync a call
API reference · v1

Sync a call

Refresh a call from the calling service and retrieve its latest saved state.

Content reviewed · Maintained by Cleo Powered · Report a documentation issue · Verification basis

POST/v1/calls/{call_id}/sync

Parameters

Name
call_id
Location
Path · required
Description
The UUID returned when the call was created.
Name
Authorization
Location
Header · required
Description
Bearer <API_KEY>, from the same Agent Project as the call.

No request body or idempotency key is needed for this operation.

Example request

For cURL, use Bash and set these variables in the same terminal. CALL_ID is the call UUID returned by create, not the idempotency key. The Python tab prompts for both inputs itself.

Bash setup
read -rsp "Cleo API key: " CLEO_API_KEY; echo
export CLEO_API_KEY
read -rp "Call ID returned by create: " CALL_ID
export CALL_ID
curl --fail-with-body -X POST \
  "https://api.cleolabs.com/v1/calls/$CALL_ID/sync" \
  -H "Authorization: Bearer $CLEO_API_KEY" \
  -H "User-Agent: CleoDocs/1.0"

Polling

Call this endpoint every few seconds while a call is active. The Python test script waits three seconds between requests. Refreshing also saves the latest call progress and results for the platform.

Stop when the state is completed, failed, or cancelled. On 429, wait at least the Retry-After number of seconds before another request.

A polling error does not mean the call ended. Keep its call ID and resume syncing, or request cancellation. Do not create a replacement call just because a status refresh failed.

Response

Returns 200 OK with the call object. If the call does not exist or belongs to a different Agent Project, the API returns 404 call_not_found.

NextCancel a call
Documentation
Get an API key

Explore the docs

IntroductionSubmit a phone errand, follow the call, and inspect its outcome.Bot account onboardingRegister from Muse or another bot, verify your phone, receive an API key, and set your dashboard password by email.API overviewWhich endpoints are available, how they authenticate, and what is supported today.Make your first callCall your own phone, refresh its status, and inspect the returned call data.AuthenticationCreate a key in Cleo and authenticate requests with a bearer token.Create a callQueue one bounded phone task and receive durable task and call IDs.Get a callRead the most recently saved state of a call.Sync a callRefresh a call from the calling service and retrieve its latest saved state.Cancel a callCancel queued work or request a stop, then follow confirmation.The call objectThe shared response returned by create, get, sync, and cancel.Health checksCheck API liveness and readiness without an API key or placing a call.Results & schemasUnderstand result_schema, returned metadata, and what result_schema_valid does and does not establish.Task and call lifecycleFollow a call from acceptance to its final outcome.Idempotency & retriesRecover from an interrupted request without accidentally placing a second call.Safety & permissionsHow Cleo evaluates a call task before it can dial.Errors & troubleshootingUnderstand API errors and choose a safe next step.LimitsKeep call tasks bounded and leave room for API rate limits.Verification & limitationsReproduce our public health and schema checks and understand what has not been tested.Bot integrationsChoose a route for connecting your assistant to Cleo's public API.ChatGPTConfigure a private GPT Action with Cleo OpenAPI and bearer authentication.ClaudeConnect Claude client tools or a Claude Code shell workflow.Grok & Grok BotConnect xAI function tools and check Grok Bot execution requirements.OpenClawInstall a local skill for an approved Cleo calling workflow.GeminiMap Gemini function declarations to Cleo REST operations.Copilot StudioAdd Cleo through a REST API tool, custom connector, or flow.n8nBuild an authenticated HTTP workflow with durable call recovery.ZapierBuild a private Zapier integration for approved Cleo calls.