Skip to content

List a studio's call history

GET
/v1/studios/{studio}/calls
curl --request GET \
--url 'https://api.caller9.app/v1/studios/2489E9AD-2EE2-8E00-8EC9-32D5F69181C0/calls?limit=100' \
--header 'Authorization: Bearer <token>'

Returns the studio’s most recent calls (live and ended), newest first by initiated_at. Not paginated; use limit (max 500).

studio
required
string format: uuid

Studio ID (UUID).

limit
integer
default: 100 >= 1 <= 500

Maximum number of calls to return. Values above 500 are clamped to 500. Must be numeric.

Call history for the studio.

Media typeapplication/json
object
calls
required
Array<object>

A call-history record. Different endpoints return different subsets of these fields: the studio call list returns every column; the organization call log adds studio_name, did_number, number_name and trunk_name; a contact’s call history returns guid, direction, status, timestamps, called_number and studio_name. Integer flags are 0/1.

object
guid
required

Call id (use with /v1/calls/{call}/…).

string
studio_guid
string | null
organization_guid
string | null
number_guid

The organization’s number involved (the dialed DID for inbound; the caller ID used for outbound).

string | null
trunk_guid

SIP trunk the call used, if any.

string | null
direction
required
string
Allowed values: inbound outbound
number

The external party in E.164 — the caller for inbound calls, the callee for outbound.

string
caller

Display name of the external party (contact name, or the number).

string
external_id

Carrier call identifier (for support).

string
status
required

queued ringing/unanswered in the queue; screening with the AI screener; hold on hold; browser with an operator’s browser; on-air on an on-air line; ended finished; busy rejected busy; failed could not connect; ringing used only for SIP-trunk calls in history.

string
Allowed values: queued ringing screening hold browser on-air ended busy failed
call_type
string | null
Allowed values: primary hotline
error_code
string | null
billable
integer
Allowed values: 0 1
billed_minutes

Calling minutes reported for billing.

integer | null
screening_billed_minutes

AI screening minutes reported for billing.

integer | null
metered_at
string | null format: date-time
screening_metered_at
string | null format: date-time
screening_started_at
string | null format: date-time
screening_ended_at
string | null format: date-time
went_to_voicemail
integer
Allowed values: 0 1
went_to_forward
integer
Allowed values: 0 1
forward_to

Forwarding destination, if the call was forwarded.

string | null
forward_dest_type
string | null
codec

Audio codec negotiated with the caller.

string | null
queued_at
string | null format: date-time
initiated_at
required
string format: date-time
answered_at
string | null format: date-time
ended_at
string | null format: date-time
studio_name

Organization call log and contact history only.

string | null
did_number

Organization call log only — E.164 of the organization’s number involved.

string | null
number_name

Organization call log only — label of that number.

string | null
trunk_name

Organization call log only.

string | null
called_number

Contact call history only — E.164 of the organization’s number involved.

string | null

Example

{
"calls": [
{
"direction": "inbound",
"status": "queued",
"call_type": "primary",
"billable": 0,
"went_to_voicemail": 0,
"went_to_forward": 0
}
]
}

Missing, invalid, expired or revoked API key.

Media typeapplication/json
object
error
required

Human-readable error message.

string
code

Machine-readable code (authentication failures only, e.g. KEY_EXPIRED, RATE_LIMITED).

string

Example generated

{
"error": "example",
"code": "example"
}

The key isn’t allowed to do this (e.g. a read-only key making a change).

Media typeapplication/json
object
error
required

Human-readable error message.

string
code

Machine-readable code (authentication failures only, e.g. KEY_EXPIRED, RATE_LIMITED).

string

Example generated

{
"error": "example",
"code": "example"
}

Not found, or belongs to another organization.

Media typeapplication/json
object
error
required

Human-readable error message.

string
code

Machine-readable code (authentication failures only, e.g. KEY_EXPIRED, RATE_LIMITED).

string

Example generated

{
"error": "example",
"code": "example"
}

Too many requests for this API key. Retry after Retry-After seconds.

Media typeapplication/json
object
error
required

Human-readable error message.

string
code

Machine-readable code (authentication failures only, e.g. KEY_EXPIRED, RATE_LIMITED).

string

Example generated

{
"error": "example",
"code": "example"
}
Retry-After
integer

Seconds until the rate-limit window resets.