API Reference

Call

Copy Markdown

Open in Claude

Open in ChatGPT

Open in Cursor

---

Copy Markdown

View as Markdown

Get call by ID

call.retrieve(strid) -> CallRetrieveResponse

GET/call/{id}

Retrieve the full details of a call order by its unique ID. The response includes the call status, call attempts, transcript, recording URL, timestamps, and metadata. Use this endpoint to poll for call completion or inspect results after a call has finished.

ParametersExpand Collapse

id: str

ReturnsExpand Collapse

class CallRetrieveResponse: …

call: Call

This represent a call "order" that was requested by the user. A call order can be resolved over multiple call attempts spanning up to a few days.

id: str

The ID of the call.

assistant: Optional[CallAssistant]

id: str

background_sound: Optional[Literal["audio/office.ogg"]]

The background sound to play during the call. Useful to give the impression that your AI agent is in an office.

calendly: Optional[CallAssistantCalendly]

connection_id: str

The connection ID representing the link between your Calendly account and Revox.

event_type_id: str

The event type ID representing the event type to schedule. (eg: https://api.calendly.com/event_types/b2330295-2a91-4a1d-bb73-99e7707663d5)

call_retry_config: Optional[CallAssistantCallRetryConfig]

Configuration for call retry behavior including time windows, delays, and max iterations. If not provided, defaults will be used.

calling_windows: List[CallAssistantCallRetryConfigCallingWindow]

calling_window_end_time: str

End time for the calling window in the recipient's timezone (or timezone_override if provided). Format: 'HH:mm' (24-hour) or 'H:mma' (12-hour). Examples: '17:00', '6pm'. Default: '18:00'.

calling_window_start_time: str

Start time for the calling window in the recipient's timezone (or timezone_override if provided). Format: 'HH:mm' (24-hour) or 'H:mma' (12-hour). Examples: '09:00', '10am'. Default: '10:00'.

retry_delay_seconds: int

Delay between retry attempts in seconds. Default: 7200 (2 hours).

exclusiveMinimum0

maximum9007199254740991

max_retry_attempts: int

Maximum number of call retry attempts. Default: 3.

exclusiveMinimum0

maximum9007199254740991

timezone: Optional[str]

Optional IANA timezone identifier to override the automatic timezone detection from phone number. If not provided, timezone is determined from the recipient's phone number country code. Examples: 'America/New_York', 'Europe/Paris'.

created_at: object

end_of_call_sentence: Optional[str]

first_sentence: Optional[str]

first_sentence_delay_ms: int

Delay in milliseconds before speaking the first sentence. Default: 400.

minimum-9007199254740991

maximum9007199254740991

first_sentence_mode: Literal["generated", "static", "none"]

One of the following:

"generated"

"static"

"none"

ivr_navigation_enabled: bool

Enable IVR navigation tools. When enabled, the assistant can send DTMF tones and skip turns to navigate phone menus.

llm_model: CallAssistantLlmModel

One of the following:

class CallAssistantLlmModelUnionMember0: …

name: Literal["gpt-4.1", "ministral-3-8b-instruct"]

One of the following:

"gpt-4.1"

"ministral-3-8b-instruct"

type: Literal["dedicated-instance"]

class CallAssistantLlmModelUnionMember1: …

openrouter_model_id: str

The model ID to use from OpenRouter. eg: openai/gpt-4.1

openrouter_provider: str

The provider to use from OpenRouter. eg: nebius, openai, azure, etc.

type: Literal["openrouter"]

Use a model from OpenRouter.

max_call_duration_secs: float

The maximum duration of the call in seconds. This is the maximum time the call will be allowed to run.

name: str

organization_id: str

prompt: str

structured_output_config: Optional[List[CallAssistantStructuredOutputConfig]]

The structured output config to use for the call. This is used to extract the data from the call (like email, name, company name, etc.).

name: str

minLength1

required: bool

type: Literal["string", "number", "boolean", 3 more]

One of the following:

"string"

"number"

"boolean"

"enum"

"date"

"datetime"

description: Optional[str]

enum_options: Optional[List[str]]

transfer_phone_number: Optional[str]

Phone number to transfer calls to when users request to speak to a human agent.

updated_at: object

voice: Optional[CallAssistantVoice]

id: str

The ID of the voice.

minLength1

provider: Literal["cartesia", "elevenlabs"]

The provider of the voice.

One of the following:

"cartesia"

"elevenlabs"

speed: Optional[float]

The speed of the voice. Range depends on provider: Cartesia 0.6–1.5, ElevenLabs 0.7–1.2. Default is 1.0.

minimum0.6

maximum1.5

voicemail_message: Optional[str]

If set, when voicemail is detected the agent will speak this message then hang up; if null, hang up immediately.

webhook_url: Optional[str]

The webhook URL to call when the call is completed.

faq_items: Optional[List[CallAssistantFaqItem]]

answer: str

question: str

id: Optional[str]

needs_human_answer: Optional[bool]

source: Optional[Literal["human", "ai"]]

One of the following:

"human"

"ai"

pending_faq_count: Optional[float]

call_attempts: List[CallCallAttempt]

All call attempts for this call order, ordered by most recent first.

id: str

The ID of the call attempt.

answered_at: object

The time the call was answered.

dial_error: Optional[Literal["number_non_attributed", "too_many_calls", "busy", 5 more]]

The SIP error that occurred.

One of the following:

"number_non_attributed"

"too_many_calls"

"busy"

"temporarily_unavailable"

"no_answer"

"no_international_permission"

"precondition_failed"

"non_classified_error"

ended_at: object

The time the call ended.

phone_number: str

The phone number that was called. Formatted in E.164 format. Example: +1234567890

recording_url: Optional[str]

The URL of the audio recording of the call.

result: Optional[Literal["IVR", "voicemail", "human", 2 more]]

One of the following:

"IVR"

"voicemail"

"human"

"unknown"

"ios-screening-filter"

started_at: object

The time the call started.

status: Literal["queued", "ringing", "ongoing", 2 more]

The status of the call attempt.

One of the following:

"queued"

"ringing"

"ongoing"

"completed"

"error"

end_reason: Optional[str]

Reason for ending the call when ended_by is 'agent'. E.g. 'tool_end_call', 'voicemail', 'transfer', 'ivr_no_navigate'.

ended_by: Optional[Literal["agent", "user", "system"]]

Who ended the call: 'agent' (AI agent), 'user' (caller/callee hung up), or 'system' (e.g. max duration limit).

One of the following:

"agent"

"user"

"system"

structured_output: Optional[Dict[str, object]]

The data extracted from the call, using the structured output config from the parent call object.

transcript: Optional[List[CallCallAttemptTranscript]]

The transcript of the call.

content: str

role: Literal["user", "assistant", "tool"]

One of the following:

"user"

"assistant"

"tool"

tool_arguments: Optional[Union[Dict[str, object], str, null]]

One of the following:

Dict[str, object]

str

tool_is_error: Optional[bool]

tool_name: Optional[str]

call_retry_config: Optional[CallCallRetryConfig]

Configuration for call retry behavior including time windows, delays, and max iterations. If not provided, defaults will be used.

calling_windows: List[CallCallRetryConfigCallingWindow]

calling_window_end_time: str

End time for the calling window in the recipient's timezone (or timezone_override if provided). Format: 'HH:mm' (24-hour) or 'H:mma' (12-hour). Examples: '17:00', '6pm'. Default: '18:00'.

calling_window_start_time: str

Start time for the calling window in the recipient's timezone (or timezone_override if provided). Format: 'HH:mm' (24-hour) or 'H:mma' (12-hour). Examples: '09:00', '10am'. Default: '10:00'.

retry_delay_seconds: int

Delay between retry attempts in seconds. Default: 7200 (2 hours).

exclusiveMinimum0

maximum9007199254740991

max_retry_attempts: int

Maximum number of call retry attempts. Default: 3.

exclusiveMinimum0

maximum9007199254740991

timezone: Optional[str]

Optional IANA timezone identifier to override the automatic timezone detection from phone number. If not provided, timezone is determined from the recipient's phone number country code. Examples: 'America/New_York', 'Europe/Paris'.

calls_count: float

The number of call attempts made.

campaign: Optional[CallCampaign]

id: str

name: str

created_at: object

The time the call order was created.

direction: Literal["inbound", "outbound"]

Whether the call is inbound or outbound.

One of the following:

"inbound"

"outbound"

first_sentence_delay_ms: int

Delay in milliseconds before speaking the first sentence. Default: 400.

minimum-9007199254740991

maximum9007199254740991

from_phone_number: str

The phone number that made the call. Formatted in E.164 format. Example: +1234567890

is_cancelled: bool

DEPRECATED: Whether the call has been cancelled. This is derived from status. Use status instead.

is_completed: bool

DEPRECATED: Whether the call has completed. This is derived from status. Use status instead.

last_call_attempt: Optional[CallLastCallAttempt]

This represent a single call attempt. A call attempt is a single call made to the phone number.

id: str

The ID of the call attempt.

answered_at: object

The time the call was answered.

dial_error: Optional[Literal["number_non_attributed", "too_many_calls", "busy", 5 more]]

The SIP error that occurred.

One of the following:

"number_non_attributed"

"too_many_calls"

"busy"

"temporarily_unavailable"

"no_answer"

"no_international_permission"

"precondition_failed"

"non_classified_error"

ended_at: object

The time the call ended.

phone_number: str

The phone number that was called. Formatted in E.164 format. Example: +1234567890

recording_url: Optional[str]

The URL of the audio recording of the call.

result: Optional[Literal["IVR", "voicemail", "human", 2 more]]

One of the following:

"IVR"

"voicemail"

"human"

"unknown"

"ios-screening-filter"

started_at: object

The time the call started.

status: Literal["queued", "ringing", "ongoing", 2 more]

The status of the call attempt.

One of the following:

"queued"

"ringing"

"ongoing"

"completed"

"error"

end_reason: Optional[str]

Reason for ending the call when ended_by is 'agent'. E.g. 'tool_end_call', 'voicemail', 'transfer', 'ivr_no_navigate'.

ended_by: Optional[Literal["agent", "user", "system"]]

Who ended the call: 'agent' (AI agent), 'user' (caller/callee hung up), or 'system' (e.g. max duration limit).

One of the following:

"agent"

"user"

"system"

structured_output: Optional[Dict[str, object]]

The data extracted from the call, using the structured output config from the parent call object.

transcript: Optional[List[CallLastCallAttemptTranscript]]

The transcript of the call.

content: str

role: Literal["user", "assistant", "tool"]

One of the following:

"user"

"assistant"

"tool"

tool_arguments: Optional[Union[Dict[str, object], str, null]]

One of the following:

Dict[str, object]

str

tool_is_error: Optional[bool]

tool_name: Optional[str]

llm_model: CallLlmModel

One of the following:

class CallLlmModelUnionMember0: …

name: Literal["gpt-4.1", "ministral-3-8b-instruct"]

One of the following:

"gpt-4.1"

"ministral-3-8b-instruct"

type: Literal["dedicated-instance"]

class CallLlmModelUnionMember1: …

openrouter_model_id: str

The model ID to use from OpenRouter. eg: openai/gpt-4.1

openrouter_provider: str

The provider to use from OpenRouter. eg: nebius, openai, azure, etc.

type: Literal["openrouter"]

Use a model from OpenRouter.

metadata: Optional[Dict[str, str]]

Metadata stored with the call.

organization_id: str

The ID of the organization that owns the call.

scheduled_at: object

The time the call order is scheduled to start.

status: Literal["initializing", "queued_for_calling", "calling", 4 more]

The status of the call.

One of the following:

"initializing"

"queued_for_calling"

"calling"

"scheduled"

"completed"

"cancelled"

"errored"

to_phone_number: str

The phone number that received the call. Formatted in E.164 format. Example: +1234567890

Get call by ID

Python

HTTP

TypeScript

Python

Ruby

import os
from revox import Revox

client = Revox(
    api_key=os.environ.get("REVOX_API_KEY"),  # This is the default and can be omitted
)
call = client.call.retrieve(
    "id",
)
print(call.call)

200 example

{
  "call": {
    "id": "id",
    "assistant": {
      "id": "id",
      "background_sound": "audio/office.ogg",
      "calendly": {
        "connection_id": "connection_id",
        "event_type_id": "event_type_id"
      },
      "call_retry_config": {
        "calling_windows": [
          {
            "calling_window_end_time": "calling_window_end_time",
            "calling_window_start_time": "calling_window_start_time",
            "retry_delay_seconds": 1
          }
        ],
        "max_retry_attempts": 1,
        "timezone": "timezone"
      },
      "created_at": {},
      "end_of_call_sentence": "end_of_call_sentence",
      "first_sentence": "first_sentence",
      "first_sentence_delay_ms": -9007199254740991,
      "first_sentence_mode": "generated",
      "ivr_navigation_enabled": true,
      "llm_model": {
        "name": "gpt-4.1",
        "type": "dedicated-instance"
      },
      "max_call_duration_secs": 0,
      "name": "name",
      "organization_id": "organization_id",
      "prompt": "prompt",
      "structured_output_config": [
        {
          "name": "x",
          "required": true,
          "type": "string",
          "description": "description",
          "enum_options": [
            "string"
          ]
        }
      ],
      "transfer_phone_number": "transfer_phone_number",
      "updated_at": {},
      "voice": {
        "id": "x",
        "provider": "cartesia",
        "speed": 0.6
      },
      "voicemail_message": "voicemail_message",
      "webhook_url": "webhook_url",
      "faq_items": [
        {
          "answer": "answer",
          "question": "question",
          "id": "id",
          "needs_human_answer": true,
          "source": "human"
        }
      ],
      "pending_faq_count": 0
    },
    "call_attempts": [
      {
        "id": "id",
        "answered_at": {},
        "dial_error": "number_non_attributed",
        "ended_at": {},
        "phone_number": "phone_number",
        "recording_url": "recording_url",
        "result": "IVR",
        "started_at": {},
        "status": "queued",
        "end_reason": "end_reason",
        "ended_by": "agent",
        "structured_output": {
          "foo": "bar"
        },
        "transcript": [
          {
            "content": "content",
            "role": "user",
            "tool_arguments": {
              "foo": "bar"
            },
            "tool_is_error": true,
            "tool_name": "tool_name"
          }
        ]
      }
    ],
    "call_retry_config": {
      "calling_windows": [
        {
          "calling_window_end_time": "calling_window_end_time",
          "calling_window_start_time": "calling_window_start_time",
          "retry_delay_seconds": 1
        }
      ],
      "max_retry_attempts": 1,
      "timezone": "timezone"
    },
    "calls_count": 0,
    "campaign": {
      "id": "id",
      "name": "name"
    },
    "created_at": {},
    "direction": "inbound",
    "first_sentence_delay_ms": -9007199254740991,
    "from_phone_number": "from_phone_number",
    "is_cancelled": true,
    "is_completed": true,
    "last_call_attempt": {
      "id": "id",
      "answered_at": {},
      "dial_error": "number_non_attributed",
      "ended_at": {},
      "phone_number": "phone_number",
      "recording_url": "recording_url",
      "result": "IVR",
      "started_at": {},
      "status": "queued",
      "end_reason": "end_reason",
      "ended_by": "agent",
      "structured_output": {
        "foo": "bar"
      },
      "transcript": [
        {
          "content": "content",
          "role": "user",
          "tool_arguments": {
            "foo": "bar"
          },
          "tool_is_error": true,
          "tool_name": "tool_name"
        }
      ]
    },
    "llm_model": {
      "name": "gpt-4.1",
      "type": "dedicated-instance"
    },
    "metadata": {
      "foo": "string"
    },
    "organization_id": "organization_id",
    "scheduled_at": {},
    "status": "initializing",
    "to_phone_number": "to_phone_number"
  }
}

Returns Examples

200 example

{
  "call": {
    "id": "id",
    "assistant": {
      "id": "id",
      "background_sound": "audio/office.ogg",
      "calendly": {
        "connection_id": "connection_id",
        "event_type_id": "event_type_id"
      },
      "call_retry_config": {
        "calling_windows": [
          {
            "calling_window_end_time": "calling_window_end_time",
            "calling_window_start_time": "calling_window_start_time",
            "retry_delay_seconds": 1
          }
        ],
        "max_retry_attempts": 1,
        "timezone": "timezone"
      },
      "created_at": {},
      "end_of_call_sentence": "end_of_call_sentence",
      "first_sentence": "first_sentence",
      "first_sentence_delay_ms": -9007199254740991,
      "first_sentence_mode": "generated",
      "ivr_navigation_enabled": true,
      "llm_model": {
        "name": "gpt-4.1",
        "type": "dedicated-instance"
      },
      "max_call_duration_secs": 0,
      "name": "name",
      "organization_id": "organization_id",
      "prompt": "prompt",
      "structured_output_config": [
        {
          "name": "x",
          "required": true,
          "type": "string",
          "description": "description",
          "enum_options": [
            "string"
          ]
        }
      ],
      "transfer_phone_number": "transfer_phone_number",
      "updated_at": {},
      "voice": {
        "id": "x",
        "provider": "cartesia",
        "speed": 0.6
      },
      "voicemail_message": "voicemail_message",
      "webhook_url": "webhook_url",
      "faq_items": [
        {
          "answer": "answer",
          "question": "question",
          "id": "id",
          "needs_human_answer": true,
          "source": "human"
        }
      ],
      "pending_faq_count": 0
    },
    "call_attempts": [
      {
        "id": "id",
        "answered_at": {},
        "dial_error": "number_non_attributed",
        "ended_at": {},
        "phone_number": "phone_number",
        "recording_url": "recording_url",
        "result": "IVR",
        "started_at": {},
        "status": "queued",
        "end_reason": "end_reason",
        "ended_by": "agent",
        "structured_output": {
          "foo": "bar"
        },
        "transcript": [
          {
            "content": "content",
            "role": "user",
            "tool_arguments": {
              "foo": "bar"
            },
            "tool_is_error": true,
            "tool_name": "tool_name"
          }
        ]
      }
    ],
    "call_retry_config": {
      "calling_windows": [
        {
          "calling_window_end_time": "calling_window_end_time",
          "calling_window_start_time": "calling_window_start_time",
          "retry_delay_seconds": 1
        }
      ],
      "max_retry_attempts": 1,
      "timezone": "timezone"
    },
    "calls_count": 0,
    "campaign": {
      "id": "id",
      "name": "name"
    },
    "created_at": {},
    "direction": "inbound",
    "first_sentence_delay_ms": -9007199254740991,
    "from_phone_number": "from_phone_number",
    "is_cancelled": true,
    "is_completed": true,
    "last_call_attempt": {
      "id": "id",
      "answered_at": {},
      "dial_error": "number_non_attributed",
      "ended_at": {},
      "phone_number": "phone_number",
      "recording_url": "recording_url",
      "result": "IVR",
      "started_at": {},
      "status": "queued",
      "end_reason": "end_reason",
      "ended_by": "agent",
      "structured_output": {
        "foo": "bar"
      },
      "transcript": [
        {
          "content": "content",
          "role": "user",
          "tool_arguments": {
            "foo": "bar"
          },
          "tool_is_error": true,
          "tool_name": "tool_name"
        }
      ]
    },
    "llm_model": {
      "name": "gpt-4.1",
      "type": "dedicated-instance"
    },
    "metadata": {
      "foo": "string"
    },
    "organization_id": "organization_id",
    "scheduled_at": {},
    "status": "initializing",
    "to_phone_number": "to_phone_number"
  }
}