List Calls

Authorizations

Authorization

string

headerrequired

Retrieve your key from Dashboard.

Query Parameters

assistantId

string

This will return calls with the specified assistantId.

limit

number

This is the maximum number of items to return. Defaults to 100.

Required range: 0 < x < 1000

createdAtGt

string

This will return items where the createdAt is greater than the specified value.

createdAtLt

string

This will return items where the createdAt is less than the specified value.

createdAtGe

string

This will return items where the createdAt is greater than or equal to the specified value.

createdAtLe

string

This will return items where the createdAt is less than or equal to the specified value.

updatedAtGt

string

This will return items where the updatedAt is greater than the specified value.

updatedAtLt

string

This will return items where the updatedAt is less than the specified value.

updatedAtGe

string

This will return items where the updatedAt is greater than or equal to the specified value.

updatedAtLe

string

This will return items where the updatedAt is less than or equal to the specified value.

Response

200 - application/json

type

enum<string>

This is the type of call.

Available options:

inboundPhoneCall,

outboundPhoneCall,

webCall

phoneCallProvider

enum<string>

This is the provider of the call.

Only relevant for outboundPhoneCall and inboundPhoneCall type.

Available options:

twilio,

vonage

phoneCallTransport

enum<string>

This is the transport of the phone call.

Only relevant for outboundPhoneCall and inboundPhoneCall type.

Available options:

sip,

pstn

status

enum<string>

This is the status of the call.

Available options:

queued,

ringing,

in-progress,

forwarding,

ended

endedReason

enum<string>

This is the explanation for how the call ended.

Available options:

assistant-error,

assistant-not-found,

db-error,

no-server-available,

pipeline-error-extra-function-failed,

pipeline-error-first-message-failed,

pipeline-error-function-filler-failed,

pipeline-error-function-failed,

pipeline-error-openai-llm-failed,

pipeline-error-azure-openai-llm-failed,

pipeline-error-together-ai-llm-failed,

pipeline-error-anyscale-llm-failed,

pipeline-error-openrouter-llm-failed,

pipeline-error-perplexity-ai-llm-failed,

pipeline-error-deepinfra-llm-failed,

pipeline-error-runpod-llm-failed,

pipeline-error-groq-llm-failed,

pipeline-error-anthropic-llm-failed,

pipeline-error-openai-voice-failed,

pipeline-error-deepgram-transcriber-failed,

pipeline-error-deepgram-voice-failed,

pipeline-error-eleven-labs-voice-failed,

pipeline-error-eleven-labs-voice-not-found,

pipeline-error-eleven-labs-quota-exceeded,

pipeline-error-playht-voice-failed,

pipeline-error-lmnt-voice-failed,

pipeline-error-azure-voice-failed,

pipeline-error-rime-ai-voice-failed,

pipeline-error-neets-voice-failed,

pipeline-no-available-llm-model,

server-shutdown,

twilio-failed-to-connect-call,

unknown-error,

vonage-disconnected,

vonage-failed-to-connect-call,

assistant-not-invalid,

assistant-not-provided,

assistant-request-returned-error,

assistant-request-returned-invalid-assistant,

assistant-request-returned-no-assistant,

assistant-request-returned-forwarding-phone-number,

assistant-ended-call,

assistant-said-end-call-phrase,

assistant-forwarded-call,

assistant-join-timed-out,

customer-busy,

customer-ended-call,

customer-did-not-answer,

customer-did-not-give-microphone-permission,

exceeded-max-duration,

manually-canceled,

phone-call-provider-closed-websocket,

pipeline-error-custom-llm-llm-failed,

silence-timed-out,

voicemail,

vonage-rejected

maxDurationSeconds

number

This is the maximum number of seconds that the call will last. When the call reaches this duration, it will be ended.

Required range: 10 < x < 3600

id

string

required

This is the unique identifier for the call.

orgId

string

required

This is the unique identifier for the org that this call belongs to.

createdAt

string

required

This is the ISO 8601 date-time string of when the call was created.

updatedAt

string

required

This is the ISO 8601 date-time string of when the call was last updated.

startedAt

string

This is the ISO 8601 date-time string of when the call was started.

endedAt

string

This is the ISO 8601 date-time string of when the call was ended.

cost

number

This is the cost of the call in USD.

costBreakdown

object

This is the cost of the call in USD.

Show child attributes

costBreakdown.transport

number

This is the cost of the transport provider, like Twilio or Vonage.

costBreakdown.stt

number

This is the cost of the speech-to-text service.

costBreakdown.llm

number

This is the cost of the language model.

costBreakdown.tts

number

This is the cost of the text-to-speech service.

costBreakdown.vapi

number

This is the cost of Vapi.

costBreakdown.total

number

This is the total cost of the call.

costBreakdown.llmPromptTokens

number

This is the LLM prompt tokens used for the call.

costBreakdown.llmCompletionTokens

number

This is the LLM completion tokens used for the call.

costBreakdown.ttsCharacters

number

This is the TTS characters used for the call.

transcript

string

This is the transcript of the call.

recordingUrl

string

This is the URL of the recording of the call.

stereoRecordingUrl

string

This is the URL of the recording of the call in two channels.

summary

string

This is the summary of the call.

messages

object[]

These are the messages that were spoken during the call.

phoneCallProviderId

string

The ID of the call as provided by the phone number service. callSid in Twilio. conversationUuid in Vonage.

Only relevant for outboundPhoneCall and inboundPhoneCall type.

phoneCallProviderBypassEnabled

boolean

If enabled, prevents Vapi from initiating calls directly. Defaults to disabled. Suitable for external call handling, such as with Twilio Studio Flow, with integration details provided in phoneCallProviderDetails.

Only relevant for outboundPhoneCall and inboundPhoneCall types.

phoneCallProviderDetails

object

This is the phone call provider details to bridge the assistant into the external call. Only filled if phoneCallProviderBypassEnabled is true.

Only relevant for outboundPhoneCall and inboundPhoneCall types.

Show child attributes

phoneCallProviderDetails.to

string

required

This is the phone number, SIP address, or client identifier to call.

phoneCallProviderDetails.from

string

required

This is the phone number or client identifier to use as the caller id.

phoneCallProviderDetails.statusCallbackEvent

enum<string>

This is the status events to subscribe to

Available options:

initiated,

ringing,

answered,

completed

phoneCallProviderDetails.machineDetection

enum<string>

This is whether to detect if a human, answering machine, or fax has picked up the call.

Available options:

Enable,

DetectMessageEnd

phoneCallProviderDetails.twiml

string

This is TwiML instructions for the call

phoneCallProviderDetails.statusCallback

string

This is the URL to send status events to

phoneCallProviderDetails.asyncAmd

string

This is whether to do the machine detection asyncronously or synchronously

phoneCallProviderDetails.asyncAmdStatusCallback

string

This is the URL to send the asyncronous machine detection status events to

phoneCallProviderDetails.record

boolean

This is whether to record the call

webCallUrl

string

This is the URL of the call that the assistant will join.

Only relevant for webCall type.

webCallSipUri

string

This is the SIP URI of the call that the assistant will join.

Only relevant for webCall type.

forwardedPhoneNumber

string

This is the phone number that the call was forwarded to.

assistantId

string | null

This is the assistant that will be used for the call. To use a transient assistant, use assistant instead.

assistant

object

This is the assistant that will be used for the call. To use an existing assistant, use assistantId instead.

Show child attributes

assistant.transcriber

object

These are the options for the assistant's transcriber.

• DeepgramTranscriber
• TalkscriberTranscriber

Show child attributes

assistant.transcriber.provider

enum<string>

required

This is the transcription provider that will be used.

Available options:

deepgram

assistant.transcriber.model

This is the Deepgram model that will be used. A list of models can be found here: https://developers.deepgram.com/docs/models-languages-overview

Available options:

nova-2,

nova-2-general,

nova-2-meeting,

nova-2-phonecall,

nova-2-finance,

nova-2-conversationalai,

nova-2-voicemail,

nova-2-video,

nova-2-medical,

nova-2-drivethru,

nova-2-automotive

assistant.transcriber.language

enum<string>

This is the language that will be set for the transcription. The list of languages Deepgram supports can be found here: https://developers.deepgram.com/docs/models-languages-overview

Available options:

cs,

da,

da-DK,

de-CH,

nl,

en,

en-US,

en-AU,

en-GB,

en-NZ,

en-IN,

nl-BE,

fr,

fr-CA,

de,

el,

hi,

hi-Latn,

id,

it,

ja,

ko,

ko-KR,

no,

pl,

pt,

pt-BR,

ru,

es,

es-419,

sv,

sv-SE,

tr,

uk,

ja,

zh,

zh-CN,

zh-TW

assistant.transcriber.keywords

string[]

These keywords are passed to the transcription model to help it pick up use-case specific words. Anything that may not be a common word, like your company name, should be added here.

assistant.model

object

These are the options for the assistant's LLM.

• OpenAIModel
• TogetherAIModel
• AnyscaleModel
• OpenRouterModel
• PerplexityAIModel
• DeepInfraModel
• GroqModel
• AnthropicModel
• CustomLLMModel

Show child attributes

assistant.model.provider

enum<string>

required

This is the provider that will be used for the model.

Available options:

openai

assistant.model.model

enum<string>

required

This is the OpenAI model that will be used.

Available options:

gpt-4-1106-preview,

gpt-4-0125-preview,

gpt-4-0613,

gpt-3.5-turbo-1106,

gpt-3.5-turbo-16k,

gpt-3.5-turbo-0613,

gpt-3.5-turbo-0125,

gpt-4,

gpt-3.5-turbo

assistant.model.messages

object[]

This is the starting state for the conversation.

Show child attributes

assistant.model.messages.content

string | null

required

assistant.model.messages.role

enum<string>

required

Available options:

assistant,

function,

user,

system

assistant.model.messages.function_call

object

assistant.model.messages.tool_calls

object[]

assistant.model.fallbackModels

enum<string>[]

Available options:

gpt-4-1106-preview,

gpt-4-0125-preview,

gpt-4-0613,

gpt-3.5-turbo-1106,

gpt-3.5-turbo-16k,

gpt-3.5-turbo-0613,

gpt-3.5-turbo-0125,

gpt-4,

gpt-3.5-turbo

assistant.model.semanticCachingEnabled

boolean

assistant.model.temperature

number

This is the temperature that will be used for calls. Default is 0 to leverage caching for lower latency.

Required range: 0 < x < 2

assistant.model.functions

object[]

These are the functions that the assistant can execute during the call.

Show child attributes

assistant.model.functions.name

string

required

This is the the name of the function to be called.

Must be a-z, A-Z, 0-9, or contain underscores and dashes, with a maximum length of 64.

Maximum length: 64

assistant.model.functions.async

boolean

Setting async: true will cause the function to be called asynchronously, meaning that the Assistant will not wait for the function to return before continuing.

assistant.model.functions.description

string

This is the description of what the function does, used by the AI to choose when and how to call the function.

Maximum length: 1000

assistant.model.functions.parameters

object

These are the parameters the functions accepts, described as a JSON Schema object.

See the OpenAI guide for examples, and the JSON Schema reference for documentation about the format.

Omitting parameters defines a function with an empty parameter list.

Show child attributes

assistant.model.functions.parameters.type

enum<string>

required

This must be set to 'object'. It instructs the model to return a JSON object containing the function call properties.

Available options:

object

assistant.model.functions.parameters.properties

object

required

This provides a description of the properties required by the function. JSON Schema can be used to specify expectations for each property. Refer to this doc for a comprehensive guide on JSON Schema.

Show child attributes

assistant.model.functions.parameters.required

string[]

This specifies the properties that are required by the function.

assistant.model.functions.serverUrl

string

This is the URL Vapi will communicate with via HTTP GET and POST Requests. This is used for retrieving context, function calling, and end-of-call reports.

All requests will be sent with the call object among other things relevant to that message. You can find more details in the Server URL documentation.

This overrides the serverUrl set on the org and the phoneNumber. Order of precedence: function.serverUrl > assistant.serverUrl > phoneNumber.serverUrl > org.serverUrl

assistant.model.functions.serverUrlSecret

string

This is the secret you can set that Vapi will send with every request to your server. Will be sent as a header called x-vapi-secret.

Same precendence logic as serverUrl.

assistant.model.maxTokens

number

This is the max number of tokens that the assistant will be allowed to generate in each turn of the conversation. Default is 250.

Required range: 50 < x < 1000

assistant.voice

object

These are the options for the assistant's voice.

• AzureVoice
• ElevenLabsVoice
• PlayHTVoice
• RimeAIVoice
• DeepgramVoice
• OpenAIVoice
• LMNTVoice
• NeetsVoice

Show child attributes

assistant.voice.provider

enum<string>

required

This is the voice provider that will be used.

Available options:

azure

assistant.voice.voiceId

required

This is the provider-specific ID that will be used.

Available options:

andrew,

brian,

emma

assistant.voice.speed

number

This is the speed multiplier that will be used.

Required range: 0.5 < x < 2

assistant.forwardingPhoneNumber

string

This is the number to forward to if assistant runs into issues.

assistant.recordingEnabled

boolean

This sets whether the assistant's calls are recorded. Defaults to true.

assistant.endCallFunctionEnabled

boolean

This sets whether the assistant will be able to hang up the call. Defaults to false.

assistant.dialKeypadFunctionEnabled

boolean

This sets whether the assistant can dial digits on the keypad. Defaults to false.

assistant.hipaaEnabled

boolean

When this is enabled, no logs, recordings, or transcriptions will be stored. At the end of the call, you will still receive an end-of-call-report message to store on your server. Defaults to false.

assistant.clientMessages

enum<string>[]

These are the messages that will be sent to the Client SDKs. Default is ['transcript', 'hang', 'function-call', 'speech-update', 'metadata', 'conversation-update']

Available options:

status-update,

speech-update,

transcript,

hang,

function-call,

metadata,

conversation-update

assistant.serverMessages

enum<string>[]

These are the messages that will be sent to your Server URL. Default is ['end-of-call-report', 'status-update', 'hang', 'function-call']

Available options:

status-update,

transcript,

hang,

function-call,

end-of-call-report,

conversation-update,

phone-call-control

assistant.silenceTimeoutSeconds

number

How many seconds of silence to wait before ending the call. Defaults to 30.

Required range: 10 < x < 600

assistant.responseDelaySeconds

number

The minimum number of seconds after user speech to wait before the assistant starts speaking. Defaults to 0.4.

Required range: 0 < x < 2

assistant.llmRequestDelaySeconds

number

The minimum number of seconds to wait after punctuation before sending a request to the LLM. Defaults to 0.1.

Required range: 0 < x < 3

assistant.numWordsToInterruptAssistant

number

The number of words to wait for before interrupting the assistant. Words like "stop", "actually", "no", etc. will always interrupt immediately regardless of this value. Words like "okay", "yeah", "right" will never interrupt. Defaults to 2.

Required range: 1 < x < 10

assistant.maxDurationSeconds

number

This is the maximum number of seconds that the call will last. When the call reaches this duration, it will be ended.

Required range: 10 < x < 3600

assistant.backgroundSound

enum<string>

This is the background sound in the call. Default for phone calls is 'office' and default for web calls is 'off'.

Available options:

off,

office

assistant.name

string

This is the name of the assistant. This is just for your own reference.

Maximum length: 100

assistant.forwardingPhoneNumbers

object[]

You can provide a set of phone numbers to forward to. You'll want to tell the assistant when to use each of these numbers in the system prompt.

Show child attributes

assistant.forwardingPhoneNumbers.number

string

This is the number to forward to. Pass one of number or sipUri.

assistant.forwardingPhoneNumbers.sipUri

string

This is the SIP URI to forward to. Pass one of number or sipUri.

assistant.forwardingPhoneNumbers.message

string

This is the message that the assistant will say when the call is forwarded to this number.

assistant.firstMessage

string

This is the first message that the assistant will say. This can also be a URL to a containerized audio file (mp3, wav, etc.).

If unspecified, it will wait for the user to speak.

Maximum length: 1000

assistant.voicemailDetectionEnabled

boolean

This sets whether the assistant should detect voicemail. Defaults to true.

assistant.voicemailMessage

string

This is the message that the assistant will say if the call is forwarded to voicemail.

If unspecified, it will hang up.

Maximum length: 1000

assistant.endCallMessage

string

This is the message that the assistant will say if it ends the call.

If unspecified, it will hang up without saying anything.

Maximum length: 400

assistant.endCallPhrases

string[]

This list contains phrases that, if spoken by the assistant, will trigger the call to be hung up. Case insensitive.

assistant.metadata

object

This is the metadata associated with the call.

assistant.serverUrl

string

This is the URL Vapi will communicate with via HTTP GET and POST Requests. This is used for retrieving context, function calling, and end-of-call reports.

All requests will be sent with the call object among other things relevant to that message. You can find more details in the Server URL documentation.

This overrides the serverUrl set on the org and the phoneNumber. Order of precedence: function.serverUrl > assistant.serverUrl > phoneNumber.serverUrl > org.serverUrl

assistant.serverUrlSecret

string

This is the secret you can set that Vapi will send with every request to your server. Will be sent as a header called x-vapi-secret.

Same precendence logic as serverUrl.

customerId

string

This is the customer that will be called. To call a transient customer , use customer instead.

Only relevant for outboundPhoneCall and inboundPhoneCall type.

customer

object

This is the customer that will be called. To call an existing customer, use customerId instead.

Only relevant for outboundPhoneCall and inboundPhoneCall type.

Show child attributes

customer.number

string

This is the number of the customer.

customer.name

string

This is the name of the customer. This is just for your own reference.

Maximum length: 40

customer.extension

string

This is the extension that will be dialed after the call is answered.

Maximum length: 30

phoneNumberId

string

This is the phone number that will be used for the call. To use a transient number, use phoneNumber instead.

Only relevant for outboundPhoneCall and inboundPhoneCall type.

phoneNumber

object

This is the phone number that will be used for the call. To use an existing number, use phoneNumberId instead.

Only relevant for outboundPhoneCall and inboundPhoneCall type.

Show child attributes

phoneNumber.twilioPhoneNumber

string

required

These are the digits of the phone number you own on your Twilio.

phoneNumber.twilioAccountSid

string

required

This is your Twilio Account SID that will be used to handle this phone number.

phoneNumber.twilioAuthToken

string

required

This is the Twilio Auth Token that will be used to handle this phone number.

phoneNumber.name

string

This is the name of the phone number. This is just for your own reference.

Maximum length: 40

phoneNumber.assistantId

string | null

This is the assistant that will be used for incoming calls to this phone number.

If this is not set, then the phone number will not handle incoming calls.

phoneNumber.serverUrl

string

This is the server URL that will be used to handle this phone number.

All requests will be sent with the call object among other things relevant to that message. You can find more details in the Server URL documentation.

This overrides the serverUrl set on the org. Order of precedence: function.serverUrl > assistant.serverUrl > phoneNumber.serverUrl > org.serverUrl.

phoneNumber.serverUrlSecret

string

This is the secret you can set that Vapi will send with every request to your server. Will be sent as a header called x-vapi-secret.

Same precendence logic as serverUrl.

metadata

object

This is the metadata associated with the call.