Switch API reference

Switch: CDRs and analytics

Call records, exports, saved views, margin, cost and quality analysis.

26 operationsBase URL https://packetexchange.io/api/v1Postman collection

BrowseSwitch: CDRs and analytics

Get margin and quality totals for all traffic

GET/api/v1/switch/analytics/overview

Access: API key. Scoped keys need switch:manage.
Rate limit: 100 requests per second (the default)

Revenue, cost, margin, ASR and minutes across every customer and supplier over the window, plus how much billed traffic carries no supplier cost yet.

Parameters

from
query · string
ISO-8601 start (default: 30 days before to)
to
query · string
ISO-8601 end (default: now)

Response 200

FieldDescription

datarequired
object
revenuerequired
number · data.revenue
US dollars as a JSON number rounded to 6 decimals (a computed figure, not a ledger string)
costrequired
number · data.cost
US dollars as a JSON number rounded to 6 decimals (a computed figure, not a ledger string)
marginrequired
number · data.margin
US dollars as a JSON number rounded to 6 decimals (a computed figure, not a ledger string)
marginPctrequired
number | null · data.marginPct
null when there was no revenue
callsrequired
integer · data.calls
answeredrequired
integer · data.answered
minutesrequired
number · data.minutes
asrrequired
number | null · data.asr
Answer rate in percent; null when there were no calls
windowrequired
object · data.window
fromrequired
string (date-time) · data.window.from
ISO-8601 timestamp (UTC)
torequired
string (date-time) · data.window.to
ISO-8601 timestamp (UTC)
labelrequired
string · data.window.label
freshnessrequired
object · data.freshness
ratingrequired
object · data.rating
unratedBilledrequired
integer · data.rating.unratedBilled
billedCallsrequired
integer · data.rating.billedCalls
unratedPctrequired
number · data.rating.unratedPct
unratedRevenuerequired
number · data.rating.unratedRevenue
US dollars as a JSON number rounded to 6 decimals (a computed figure, not a ledger string)
unratedMinutesrequired
number · data.rating.unratedMinutes

Errors

400VALIDATION_ERROR, INVALID_INPUT or BAD_REQUEST. For VALIDATION_ERROR, error.details is an array of { path, message }.
401UNAUTHORIZED: missing, invalid, expired or revoked credential.
402SWITCH_SUBSCRIPTION_REQUIRED: the account has no active Switch plan or trial.
403FORBIDDEN: not allowed - a scoped key lacks the scope, or the endpoint is session-only.
429RATE_LIMITED: slow down and retry after the Retry-After seconds.
500INTERNAL_ERROR: unexpected failure. Quote X-Request-Id to support.

Get daily margin and quality figures

GET/api/v1/switch/analytics/timeseries

Access: API key. Scoped keys need switch:manage.
Rate limit: 100 requests per second (the default)

Parameters

from
query · string
ISO-8601 start (default: 30 days before to)
to
query · string
ISO-8601 end (default: now)

Response 200

FieldDescription

datarequired
object[]
revenuerequired
number · data[].revenue
US dollars as a JSON number rounded to 6 decimals (a computed figure, not a ledger string)
costrequired
number · data[].cost
US dollars as a JSON number rounded to 6 decimals (a computed figure, not a ledger string)
marginrequired
number · data[].margin
US dollars as a JSON number rounded to 6 decimals (a computed figure, not a ledger string)
marginPctrequired
number | null · data[].marginPct
null when there was no revenue
callsrequired
integer · data[].calls
answeredrequired
integer · data[].answered
minutesrequired
number · data[].minutes
asrrequired
number | null · data[].asr
Answer rate in percent; null when there were no calls
dayrequired
string · data[].day

Errors

400VALIDATION_ERROR, INVALID_INPUT or BAD_REQUEST. For VALIDATION_ERROR, error.details is an array of { path, message }.
401UNAUTHORIZED: missing, invalid, expired or revoked credential.
402SWITCH_SUBSCRIPTION_REQUIRED: the account has no active Switch plan or trial.
403FORBIDDEN: not allowed - a scoped key lacks the scope, or the endpoint is session-only.
429RATE_LIMITED: slow down and retry after the Retry-After seconds.
500INTERNAL_ERROR: unexpected failure. Quote X-Request-Id to support.

Break down margin and quality by customer, supplier or destination

GET/api/v1/switch/analytics/breakdown

Access: API key. Scoped keys need switch:manage.
Rate limit: 100 requests per second (the default)

Parameters

from
query · string
ISO-8601 start (default: 30 days before to)
to
query · string
ISO-8601 end (default: now)
by
query · string
Default customerOne of customer, supplier, destination

Response 200

FieldDescription

datarequired
object[]
revenuerequired
number · data[].revenue
US dollars as a JSON number rounded to 6 decimals (a computed figure, not a ledger string)
costrequired
number · data[].cost
US dollars as a JSON number rounded to 6 decimals (a computed figure, not a ledger string)
marginrequired
number · data[].margin
US dollars as a JSON number rounded to 6 decimals (a computed figure, not a ledger string)
marginPctrequired
number | null · data[].marginPct
null when there was no revenue
callsrequired
integer · data[].calls
answeredrequired
integer · data[].answered
minutesrequired
number · data[].minutes
asrrequired
number | null · data[].asr
Answer rate in percent; null when there were no calls
keyrequired
string · data[].key
labelrequired
string · data[].label
external
boolean · data[].external

Errors

400VALIDATION_ERROR, INVALID_INPUT or BAD_REQUEST. For VALIDATION_ERROR, error.details is an array of { path, message }.
401UNAUTHORIZED: missing, invalid, expired or revoked credential.
402SWITCH_SUBSCRIPTION_REQUIRED: the account has no active Switch plan or trial.
403FORBIDDEN: not allowed - a scoped key lacks the scope, or the endpoint is session-only.
429RATE_LIMITED: slow down and retry after the Retry-After seconds.
500INTERNAL_ERROR: unexpected failure. Quote X-Request-Id to support.

List your recent call-record exports

GET/api/v1/switch/cdr-exports

Access: API key. Scoped keys need switch:manage.
Rate limit: 100 requests per second (the default)

The latest 25 Switch exports.

Response 200

FieldDescription

datarequired
object[]
idrequired
string (uuid) · data[].id
phaserequired
string · data[].phase
queued, running, completed or failed
statusrequired
string · data[].status
requestedScoperequired
string | null · data[].requestedScope
requestedAtrequired
string · data[].requestedAt
recordCountrequired
integer | null · data[].recordCount
Only set once completed
numbersMaskedrequired
boolean · data[].numbersMasked
addressesMaskedrequired
boolean · data[].addressesMasked
truncated
boolean · data[].truncated
error
string | null · data[].error
completedAt
string (date-time) | null · data[].completedAt
ISO-8601 timestamp (UTC)
downloadable
boolean · data[].downloadable
downloadUrl
string | null · data[].downloadUrl
GET /billing/exports/{id}/download once completed. No server path is ever returned.
rowCount
integer | null · data[].rowCount
createdAt
string (date-time) · data[].createdAt
ISO-8601 timestamp (UTC)
queryId
string | null · data[].queryId

Errors

400VALIDATION_ERROR, INVALID_INPUT or BAD_REQUEST. For VALIDATION_ERROR, error.details is an array of { path, message }.
401UNAUTHORIZED: missing, invalid, expired or revoked credential.
402SWITCH_SUBSCRIPTION_REQUIRED: the account has no active Switch plan or trial.
403FORBIDDEN: not allowed - a scoped key lacks the scope, or the endpoint is session-only.
429RATE_LIMITED: slow down and retry after the Retry-After seconds.
500INTERNAL_ERROR: unexpected failure. Quote X-Request-Id to support.

Start a background call-record export

POST/api/v1/switch/cdr-exports

Access: API key. Scoped keys need switch:manage.
Rate limit: 100 requests per second (the default)

Queues an export of the filtered records (body takes the same filters as GET /switch/cdrs). At most 3 exports may run at once. Numbers: a scoped API key without the cdr:numbers scope receives masked calling and dialled numbers (numbersMasked says so). Full-access keys and dashboard sessions see them in full.

Test keys: refused with 403 TEST_KEY_NOT_ALLOWED. The Switch has no test mode, so a change always applies to your live configuration. Test keys can still read Switch data.

Request body (application/json)

FieldDescription

from
string
ISO-8601 start of the window
to
string
ISO-8601 end of the window
kind
string
One of voice, sms
direction
string
One of inbound, outbound
status
string
subAccountId
string (uuid)
Customer
customerTrunkId
string (uuid)
vendorTrunkId
string (uuid)
Supplier trunk
supplierTrunkMatch
string
How vendorTrunkId matches failover attempts (default selected)One of selected, attempted, either
routeGroupId
string (uuid)
countryPrefix
string
destination
string
destinationName
string
answeredOnly
string
One of true, false
answeredState
string
One of answered, unanswered
mediaMode
string
One of direct, proxy
sipCode
integer
sipCodes
string
Comma-separated SIP codes (max 20)
q850Cause
integer
q850Causes
string
Comma-separated Q.850 causes (max 20)
hangupCause
string
durationMin
number
durationMax
number
pddMinMs
number
pddMaxMs
number
codec
string
releaseParty
string
ip
string
ratingState
string
One of rated, unrated
negativeMarginOnly
string
One of true, false
riskMin
number
attestation
string
One of A, B, C
search
string
Up to 20 values separated by comma, semicolon or newline
searchField
string
searchMatch
string
One of any, all
sortBy
string
sortDir
string
One of asc, desc
includeProbes
string
Include the platform's synthetic reachability probes (hidden by default)One of true, false
limit
integer
1 to 500
offset
integer
min 0

Response 202

FieldDescription

datarequired
object
Same fields as SwitchCdrExport, shown earlier on this page.

Errors

400VALIDATION_ERROR, INVALID_INPUT or BAD_REQUEST. For VALIDATION_ERROR, error.details is an array of { path, message }.
401UNAUTHORIZED: missing, invalid, expired or revoked credential.
402SWITCH_SUBSCRIPTION_REQUIRED: the account has no active Switch plan or trial.
403FORBIDDEN: not allowed - a scoped key lacks the scope, or the endpoint is session-only.
409CONFLICT (or a code-specific 409): the change clashes with existing state.
429RATE_LIMITED: slow down and retry after the Retry-After seconds.
500INTERNAL_ERROR: unexpected failure. Quote X-Request-Id to support.
AlsoTOO_MANY_EXPORTS

HTTP

curl -X POST "https://packetexchange.io/api/v1/switch/cdr-exports" \
  -H "Authorization: Bearer $PACKETEXCHANGE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "from": "+447700900123",
  "to": "+447700900123"
}'

Run it here with a test key.

Get the status of a call-record export

GET/api/v1/switch/cdr-exports/{id}

Access: API key. Scoped keys need switch:manage.
Rate limit: 100 requests per second (the default)

Parameters

idrequired
path · string

Response 200

FieldDescription

datarequired
object
Same fields as SwitchCdrExport, shown earlier on this page.

Errors

400VALIDATION_ERROR, INVALID_INPUT or BAD_REQUEST. For VALIDATION_ERROR, error.details is an array of { path, message }.
401UNAUTHORIZED: missing, invalid, expired or revoked credential.
402SWITCH_SUBSCRIPTION_REQUIRED: the account has no active Switch plan or trial.
403FORBIDDEN: not allowed - a scoped key lacks the scope, or the endpoint is session-only.
404NOT_FOUND: no such resource on your account.
429RATE_LIMITED: slow down and retry after the Retry-After seconds.
500INTERNAL_ERROR: unexpected failure. Quote X-Request-Id to support.

Get traffic usage for one customer

GET/api/v1/switch/usage

Access: API key. Scoped keys need switch:manage.
Rate limit: 100 requests per second (the default)

Totals, per-day figures, live concurrent calls and (optionally) per-destination usage for a customer (sub-account) over a window of up to 92 days (default: the last 24 hours). A longer window is clamped and says so in window.clamped. live.concurrentCalls is null when the live monitor cannot be reached.

Parameters

subAccountIdrequired
query · string (uuid)
The customer to report on (required)
since
query · string
ISO-8601 start (default: 24 hours before until)
until
query · string
ISO-8601 end (default: now)
destinations
query · string
Include the per-destination breakdownOne of true, false, 1, 0

Response 200

FieldDescription

datarequired
object
windowrequired
object · data.window
subAccountIdrequired
string (uuid) · data.window.subAccountId
sincerequired
string (date-time) · data.window.since
ISO-8601 timestamp (UTC)
untilrequired
string (date-time) · data.window.until
ISO-8601 timestamp (UTC)
nextSincerequired
string (date-time) · data.window.nextSince
ISO-8601 timestamp (UTC)
clampedrequired
boolean · data.window.clamped
maxWindowDaysrequired
integer · data.window.maxWindowDays
totalsrequired
object · data.totals
Calls, answered, minutes, revenue, cost and rejectedAtCapacity over the window
dailyrequired
object[] · data.daily
liverequired
object · data.live
concurrentCallsrequired
integer | null · data.live.concurrentCalls
byDestination
object[] · data.byDestination

Errors

400VALIDATION_ERROR, INVALID_INPUT or BAD_REQUEST. For VALIDATION_ERROR, error.details is an array of { path, message }.
401UNAUTHORIZED: missing, invalid, expired or revoked credential.
402SWITCH_SUBSCRIPTION_REQUIRED: the account has no active Switch plan or trial.
403FORBIDDEN: not allowed - a scoped key lacks the scope, or the endpoint is session-only.
429RATE_LIMITED: slow down and retry after the Retry-After seconds.
500INTERNAL_ERROR: unexpected failure. Quote X-Request-Id to support.

Record that call-record details were copied

POST/api/v1/switch/cdrs/{id}/audit-copy

Access: API key. Scoped keys need switch:manage.
Rate limit: 100 requests per second (the default)

Writes an access entry to your account activity (for example when diagnostics are copied to the clipboard). Answers 202 with { success: true } and no data.

Test keys: refused with 403 TEST_KEY_NOT_ALLOWED. The Switch has no test mode, so a change always applies to your live configuration. Test keys can still read Switch data.

Parameters

idrequired
path · string

Request body (application/json)

FieldDescription

what
string
What was copied (default "diagnostics")max 64 chars

Response 202

FieldDescription

datarequired
any | enum | null
Not sent by this endpoint

Errors

400VALIDATION_ERROR, INVALID_INPUT or BAD_REQUEST. For VALIDATION_ERROR, error.details is an array of { path, message }.
401UNAUTHORIZED: missing, invalid, expired or revoked credential.
402SWITCH_SUBSCRIPTION_REQUIRED: the account has no active Switch plan or trial.
403FORBIDDEN: not allowed - a scoped key lacks the scope, or the endpoint is session-only.
404NOT_FOUND: no such resource on your account.
409CONFLICT (or a code-specific 409): the change clashes with existing state.
429RATE_LIMITED: slow down and retry after the Retry-After seconds.
500INTERNAL_ERROR: unexpected failure. Quote X-Request-Id to support.

HTTP

curl -X POST "https://packetexchange.io/api/v1/switch/cdrs/<id>/audit-copy" \
  -H "Authorization: Bearer $PACKETEXCHANGE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "what": "<what>"
}'

Run it here with a test key.

Get the values available to filter call records by

GET/api/v1/switch/cdr-filter-options

Access: API key. Scoped keys need switch:manage.
Rate limit: 100 requests per second (the default)

Response 200

FieldDescription

datarequired
object
ingressTrunksrequired
object[] · data.ingressTrunks
idrequired
string (uuid) · data.ingressTrunks[].id
labelrequired
string · data.ingressTrunks[].label
ownerrequired
string | null · data.ingressTrunks[].owner
techPrefixrequired
string | null · data.ingressTrunks[].techPrefix
egressTrunksrequired
object[] · data.egressTrunks
idrequired
string (uuid) · data.egressTrunks[].id
labelrequired
string · data.egressTrunks[].label
ownerrequired
string | null · data.egressTrunks[].owner
techPrefixrequired
string | null · data.egressTrunks[].techPrefix
routeGroupsrequired
object[] · data.routeGroups
idrequired
string (uuid) · data.routeGroups[].id
labelrequired
string · data.routeGroups[].label
countryrequired
string | null · data.routeGroups[].country
hasRiskScoresrequired
boolean · data.hasRiskScores
hasAttestationrequired
boolean · data.hasAttestation

Errors

400VALIDATION_ERROR, INVALID_INPUT or BAD_REQUEST. For VALIDATION_ERROR, error.details is an array of { path, message }.
401UNAUTHORIZED: missing, invalid, expired or revoked credential.
402SWITCH_SUBSCRIPTION_REQUIRED: the account has no active Switch plan or trial.
403FORBIDDEN: not allowed - a scoped key lacks the scope, or the endpoint is session-only.
429RATE_LIMITED: slow down and retry after the Retry-After seconds.
500INTERNAL_ERROR: unexpected failure. Quote X-Request-Id to support.

Get your saved call-records layout

GET/api/v1/switch/cdr-workspace

Access: API key. Scoped keys need switch:manage.
Rate limit: 100 requests per second (the default)

Response 200

FieldDescription

datarequired
object | null
null until a layout has been saved
order
string[] · data.order
cols
string[] · data.cols
compact
boolean · data.compact
pageSize
number · data.pageSize
widths
object · data.widths

Errors

400VALIDATION_ERROR, INVALID_INPUT or BAD_REQUEST. For VALIDATION_ERROR, error.details is an array of { path, message }.
401UNAUTHORIZED: missing, invalid, expired or revoked credential.
402SWITCH_SUBSCRIPTION_REQUIRED: the account has no active Switch plan or trial.
403FORBIDDEN: not allowed - a scoped key lacks the scope, or the endpoint is session-only.
429RATE_LIMITED: slow down and retry after the Retry-After seconds.
500INTERNAL_ERROR: unexpected failure. Quote X-Request-Id to support.

Save your call-records layout

PUT/api/v1/switch/cdr-workspace

Access: API key. Scoped keys need switch:manage.
Rate limit: 100 requests per second (the default)

Column order, visible columns, density, page size (50, 100 or 200) and column widths (48-600 px). Invalid values are dropped, not rejected.

Test keys: refused with 403 TEST_KEY_NOT_ALLOWED. The Switch has no test mode, so a change always applies to your live configuration. Test keys can still read Switch data.

Request body (application/json)

FieldDescription

order
string[]
cols
string[]
compact
boolean
pageSize
number
widths
object

Response 200

FieldDescription

datarequired
object
order
string[] · data.order
cols
string[] · data.cols
compact
boolean · data.compact
pageSize
number · data.pageSize
widths
object · data.widths

Response 202

FieldDescription

datarequired
object
approvalRequired
boolean · data.approvalRequired
One of true
approvalRequestId
string (uuid) | null · data.approvalRequestId
permission
string · data.permission
expiresAt
string (date-time) · data.expiresAt
message
string · data.message

Errors

400VALIDATION_ERROR, INVALID_INPUT or BAD_REQUEST. For VALIDATION_ERROR, error.details is an array of { path, message }.
401UNAUTHORIZED: missing, invalid, expired or revoked credential.
402SWITCH_SUBSCRIPTION_REQUIRED: the account has no active Switch plan or trial.
403FORBIDDEN: not allowed - a scoped key lacks the scope, or the endpoint is session-only.
409CONFLICT (or a code-specific 409): the change clashes with existing state.
429RATE_LIMITED: slow down and retry after the Retry-After seconds.
500INTERNAL_ERROR: unexpected failure. Quote X-Request-Id to support.

HTTP

curl -X PUT "https://packetexchange.io/api/v1/switch/cdr-workspace" \
  -H "Authorization: Bearer $PACKETEXCHANGE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "order": [
    "<order>"
  ],
  "cols": [
    "<col>"
  ]
}'

Run it here with a test key.

Search call records

GET/api/v1/switch/cdrs

Access: API key. Scoped keys need switch:manage.
Rate limit: 100 requests per second (the default)

Paged call records (one row per attempt) with a summary over the whole filtered window: calls, ASR and ACD (per call, failover collapsed), PDD median and p95, revenue, cost and margin. Long windows are clamped (see window). Numbers: a scoped API key without the cdr:numbers scope receives masked calling and dialled numbers (numbersMasked says so). Full-access keys and dashboard sessions see them in full.

Parameters

from
query · string
ISO-8601 start of the window
to
query · string
ISO-8601 end of the window
kind
query · string
One of voice, sms
direction
query · string
One of inbound, outbound
status
query · string
subAccountId
query · string (uuid)
Customer
customerTrunkId
query · string (uuid)
vendorTrunkId
query · string (uuid)
Supplier trunk
supplierTrunkMatch
query · string
How vendorTrunkId matches failover attempts (default selected)One of selected, attempted, either
routeGroupId
query · string (uuid)
countryPrefix
query · string
destination
query · string
destinationName
query · string
answeredOnly
query · string
One of true, false
answeredState
query · string
One of answered, unanswered
mediaMode
query · string
One of direct, proxy
sipCode
query · integer
sipCodes
query · string
Comma-separated SIP codes (max 20)
q850Cause
query · integer
q850Causes
query · string
Comma-separated Q.850 causes (max 20)
hangupCause
query · string
durationMin
query · number
durationMax
query · number
pddMinMs
query · number
pddMaxMs
query · number
codec
query · string
releaseParty
query · string
ip
query · string
ratingState
query · string
One of rated, unrated
negativeMarginOnly
query · string
One of true, false
riskMin
query · number
attestation
query · string
One of A, B, C
search
query · string
Up to 20 values separated by comma, semicolon or newline
searchField
query · string
searchMatch
query · string
One of any, all
sortBy
query · string
sortDir
query · string
One of asc, desc
includeProbes
query · string
Include the platform's synthetic reachability probes (hidden by default)One of true, false
limit
query · integer
offset
query · integer

Response 200

FieldDescription

datarequired
object
rowsrequired
object[] · data.rows
idrequired
string (uuid) · data.rows[].id
createdAtrequired
string (date-time) · data.rows[].createdAt
ISO-8601 timestamp (UTC)
kindrequired
string · data.rows[].kind
One of voice, sms
directionrequired
string · data.rows[].direction
fromrequired
string | null · data.rows[].from
torequired
string | null · data.rows[].to
clirequired
string | null · data.rows[].cli
statusrequired
string · data.rows[].status
sipCoderequired
integer | null · data.rows[].sipCode
hangupCauserequired
string | null · data.rows[].hangupCause
durationSecondsrequired
integer | null · data.rows[].durationSeconds
billedSecondsrequired
integer | null · data.rows[].billedSeconds
segmentsrequired
integer | null · data.rows[].segments
pddMsrequired
integer | null · data.rows[].pddMs
callGroupIdrequired
string | null · data.rows[].callGroupId
Shared by every failover attempt of one call
customerrequired
string | null · data.rows[].customer
supplierrequired
string | null · data.rows[].supplier
revenuerequired
number · data.rows[].revenue
US dollars as a JSON number rounded to 6 decimals (a computed figure, not a ledger string)
costrequired
number · data.rows[].cost
US dollars as a JSON number rounded to 6 decimals (a computed figure, not a ledger string)
marginrequired
number · data.rows[].margin
US dollars as a JSON number rounded to 6 decimals (a computed figure, not a ledger string)
sellRatePerUnitrequired
number | null · data.rows[].sellRatePerUnit
null when the call could not be rated (distinct from a real 0)
buyRatePerUnitrequired
number | null · data.rows[].buyRatePerUnit
US dollars as a JSON number rounded to 6 decimals (a computed figure, not a ledger string)
ratingStaterequired
string | null · data.rows[].ratingState
mosrequired
number | null · data.rows[].mos
jitterMsrequired
number | null · data.rows[].jitterMs
packetLossPctrequired
number | null · data.rows[].packetLossPct
mediaModerequired
string | null · data.rows[].mediaMode
codecrequired
string | null · data.rows[].codec
q850Causerequired
integer | null · data.rows[].q850Cause
destinationNamerequired
string | null · data.rows[].destinationName
riskScore
number | null · data.rows[].riskScore
attestation
string | null · data.rows[].attestation
customerTrunkId
string (uuid) | null · data.rows[].customerTrunkId
attemptCount
integer · data.rows[].attemptCount
invoiceId
string (uuid) | null · data.rows[].invoiceId
totalrequired
integer · data.total
limitrequired
integer · data.limit
offsetrequired
integer · data.offset
summaryrequired
object · data.summary
Window totals: calls, answeredCalls, asrPercent, acdSeconds, talkSeconds, billableSeconds, pddMedianMs, pddP95Ms, revenue, cost, margin, ingestionLagSeconds...
numbersMaskedrequired
boolean · data.numbersMasked
addressesMaskedrequired
boolean · data.addressesMasked
fieldVisibilityrequired
object · data.fieldVisibility
generatedAtrequired
string (date-time) · data.generatedAt
ISO-8601 timestamp (UTC)
windowrequired
object · data.window
fromrequired
string (date-time) | null · data.window.from
ISO-8601 timestamp (UTC)
torequired
string (date-time) | null · data.window.to
ISO-8601 timestamp (UTC)
clampedrequired
boolean · data.window.clamped
maxWindowDaysrequired
integer · data.window.maxWindowDays
queryIdrequired
string · data.queryId
Stable id of the question asked, shared with exports of the same filters

Errors

400VALIDATION_ERROR, INVALID_INPUT or BAD_REQUEST. For VALIDATION_ERROR, error.details is an array of { path, message }.
401UNAUTHORIZED: missing, invalid, expired or revoked credential.
402SWITCH_SUBSCRIPTION_REQUIRED: the account has no active Switch plan or trial.
403FORBIDDEN: not allowed - a scoped key lacks the scope, or the endpoint is session-only.
429RATE_LIMITED: slow down and retry after the Retry-After seconds.
500INTERNAL_ERROR: unexpected failure. Quote X-Request-Id to support.

Count call records by filter value

GET/api/v1/switch/cdrs/facets

Access: API key. Scoped keys need switch:manage.
Rate limit: 100 requests per second (the default)

For the filtered window, how many records carry each status, SIP code, customer, supplier and so on.

Parameters

from
query · string
ISO-8601 start of the window
to
query · string
ISO-8601 end of the window
kind
query · string
One of voice, sms
direction
query · string
One of inbound, outbound
status
query · string
subAccountId
query · string (uuid)
Customer
customerTrunkId
query · string (uuid)
vendorTrunkId
query · string (uuid)
Supplier trunk
supplierTrunkMatch
query · string
How vendorTrunkId matches failover attempts (default selected)One of selected, attempted, either
routeGroupId
query · string (uuid)
countryPrefix
query · string
destination
query · string
destinationName
query · string
answeredOnly
query · string
One of true, false
answeredState
query · string
One of answered, unanswered
mediaMode
query · string
One of direct, proxy
sipCode
query · integer
sipCodes
query · string
Comma-separated SIP codes (max 20)
q850Cause
query · integer
q850Causes
query · string
Comma-separated Q.850 causes (max 20)
hangupCause
query · string
durationMin
query · number
durationMax
query · number
pddMinMs
query · number
pddMaxMs
query · number
codec
query · string
releaseParty
query · string
ip
query · string
ratingState
query · string
One of rated, unrated
negativeMarginOnly
query · string
One of true, false
riskMin
query · number
attestation
query · string
One of A, B, C
search
query · string
Up to 20 values separated by comma, semicolon or newline
searchField
query · string
searchMatch
query · string
One of any, all
sortBy
query · string
sortDir
query · string
One of asc, desc
includeProbes
query · string
Include the platform's synthetic reachability probes (hidden by default)One of true, false
limit
query · integer
offset
query · integer

Response 200

FieldDescription

datarequired
object
queryIdrequired
string · data.queryId
Stable id of the question asked, shared with exports of the same filters

Errors

400VALIDATION_ERROR, INVALID_INPUT or BAD_REQUEST. For VALIDATION_ERROR, error.details is an array of { path, message }.
401UNAUTHORIZED: missing, invalid, expired or revoked credential.
402SWITCH_SUBSCRIPTION_REQUIRED: the account has no active Switch plan or trial.
403FORBIDDEN: not allowed - a scoped key lacks the scope, or the endpoint is session-only.
429RATE_LIMITED: slow down and retry after the Retry-After seconds.
500INTERNAL_ERROR: unexpected failure. Quote X-Request-Id to support.

Get charts for the filtered call records

GET/api/v1/switch/cdrs/analytics

Access: API key. Scoped keys need switch:manage.
Rate limit: 100 requests per second (the default)

Parameters

from
query · string
ISO-8601 start of the window
to
query · string
ISO-8601 end of the window
kind
query · string
One of voice, sms
direction
query · string
One of inbound, outbound
status
query · string
subAccountId
query · string (uuid)
Customer
customerTrunkId
query · string (uuid)
vendorTrunkId
query · string (uuid)
Supplier trunk
supplierTrunkMatch
query · string
How vendorTrunkId matches failover attempts (default selected)One of selected, attempted, either
routeGroupId
query · string (uuid)
countryPrefix
query · string
destination
query · string
destinationName
query · string
answeredOnly
query · string
One of true, false
answeredState
query · string
One of answered, unanswered
mediaMode
query · string
One of direct, proxy
sipCode
query · integer
sipCodes
query · string
Comma-separated SIP codes (max 20)
q850Cause
query · integer
q850Causes
query · string
Comma-separated Q.850 causes (max 20)
hangupCause
query · string
durationMin
query · number
durationMax
query · number
pddMinMs
query · number
pddMaxMs
query · number
codec
query · string
releaseParty
query · string
ip
query · string
ratingState
query · string
One of rated, unrated
negativeMarginOnly
query · string
One of true, false
riskMin
query · number
attestation
query · string
One of A, B, C
search
query · string
Up to 20 values separated by comma, semicolon or newline
searchField
query · string
searchMatch
query · string
One of any, all
sortBy
query · string
sortDir
query · string
One of asc, desc
includeProbes
query · string
Include the platform's synthetic reachability probes (hidden by default)One of true, false
limit
query · integer
offset
query · integer

Response 200

FieldDescription

datarequired
object
queryIdrequired
string · data.queryId
Stable id of the question asked, shared with exports of the same filters

Errors

400VALIDATION_ERROR, INVALID_INPUT or BAD_REQUEST. For VALIDATION_ERROR, error.details is an array of { path, message }.
401UNAUTHORIZED: missing, invalid, expired or revoked credential.
402SWITCH_SUBSCRIPTION_REQUIRED: the account has no active Switch plan or trial.
403FORBIDDEN: not allowed - a scoped key lacks the scope, or the endpoint is session-only.
429RATE_LIMITED: slow down and retry after the Retry-After seconds.
500INTERNAL_ERROR: unexpected failure. Quote X-Request-Id to support.

Break down failed calls by stage and reason

GET/api/v1/switch/cdrs/failure-summary

Access: API key. Scoped keys need switch:manage.
Rate limit: 100 requests per second (the default)

Parameters

from
query · string
ISO-8601 start of the window
to
query · string
ISO-8601 end of the window
kind
query · string
One of voice, sms
direction
query · string
One of inbound, outbound
status
query · string
subAccountId
query · string (uuid)
Customer
customerTrunkId
query · string (uuid)
vendorTrunkId
query · string (uuid)
Supplier trunk
supplierTrunkMatch
query · string
How vendorTrunkId matches failover attempts (default selected)One of selected, attempted, either
routeGroupId
query · string (uuid)
countryPrefix
query · string
destination
query · string
destinationName
query · string
answeredOnly
query · string
One of true, false
answeredState
query · string
One of answered, unanswered
mediaMode
query · string
One of direct, proxy
sipCode
query · integer
sipCodes
query · string
Comma-separated SIP codes (max 20)
q850Cause
query · integer
q850Causes
query · string
Comma-separated Q.850 causes (max 20)
hangupCause
query · string
durationMin
query · number
durationMax
query · number
pddMinMs
query · number
pddMaxMs
query · number
codec
query · string
releaseParty
query · string
ip
query · string
ratingState
query · string
One of rated, unrated
negativeMarginOnly
query · string
One of true, false
riskMin
query · number
attestation
query · string
One of A, B, C
search
query · string
Up to 20 values separated by comma, semicolon or newline
searchField
query · string
searchMatch
query · string
One of any, all
sortBy
query · string
sortDir
query · string
One of asc, desc
includeProbes
query · string
Include the platform's synthetic reachability probes (hidden by default)One of true, false
limit
query · integer
offset
query · integer

Response 200

FieldDescription

datarequired
object
queryIdrequired
string · data.queryId
Stable id of the question asked, shared with exports of the same filters

Errors

400VALIDATION_ERROR, INVALID_INPUT or BAD_REQUEST. For VALIDATION_ERROR, error.details is an array of { path, message }.
401UNAUTHORIZED: missing, invalid, expired or revoked credential.
402SWITCH_SUBSCRIPTION_REQUIRED: the account has no active Switch plan or trial.
403FORBIDDEN: not allowed - a scoped key lacks the scope, or the endpoint is session-only.
429RATE_LIMITED: slow down and retry after the Retry-After seconds.
500INTERNAL_ERROR: unexpected failure. Quote X-Request-Id to support.

Group failed calls by the dimensions they share

GET/api/v1/switch/cdrs/failure-groups

Access: API key. Scoped keys need switch:manage.
Rate limit: 100 requests per second (the default)

Clusters failures (for example one supplier, one destination, one SIP code) so a pattern reads as one problem.

Parameters

from
query · string
ISO-8601 start of the window
to
query · string
ISO-8601 end of the window
kind
query · string
One of voice, sms
direction
query · string
One of inbound, outbound
status
query · string
subAccountId
query · string (uuid)
Customer
customerTrunkId
query · string (uuid)
vendorTrunkId
query · string (uuid)
Supplier trunk
supplierTrunkMatch
query · string
How vendorTrunkId matches failover attempts (default selected)One of selected, attempted, either
routeGroupId
query · string (uuid)
countryPrefix
query · string
destination
query · string
destinationName
query · string
answeredOnly
query · string
One of true, false
answeredState
query · string
One of answered, unanswered
mediaMode
query · string
One of direct, proxy
sipCode
query · integer
sipCodes
query · string
Comma-separated SIP codes (max 20)
q850Cause
query · integer
q850Causes
query · string
Comma-separated Q.850 causes (max 20)
hangupCause
query · string
durationMin
query · number
durationMax
query · number
pddMinMs
query · number
pddMaxMs
query · number
codec
query · string
releaseParty
query · string
ip
query · string
ratingState
query · string
One of rated, unrated
negativeMarginOnly
query · string
One of true, false
riskMin
query · number
attestation
query · string
One of A, B, C
search
query · string
Up to 20 values separated by comma, semicolon or newline
searchField
query · string
searchMatch
query · string
One of any, all
sortBy
query · string
sortDir
query · string
One of asc, desc
includeProbes
query · string
Include the platform's synthetic reachability probes (hidden by default)One of true, false
limit
query · integer
offset
query · integer
dims
query · string
Comma-separated grouping dimensions
destinationDigits
query · integer
bucket
query · string
One of day, hour
minSessions
query · integer

Response 200

FieldDescription

datarequired
object
queryIdrequired
string · data.queryId
Stable id of the question asked, shared with exports of the same filters

Errors

400VALIDATION_ERROR, INVALID_INPUT or BAD_REQUEST. For VALIDATION_ERROR, error.details is an array of { path, message }.
401UNAUTHORIZED: missing, invalid, expired or revoked credential.
402SWITCH_SUBSCRIPTION_REQUIRED: the account has no active Switch plan or trial.
403FORBIDDEN: not allowed - a scoped key lacks the scope, or the endpoint is session-only.
429RATE_LIMITED: slow down and retry after the Retry-After seconds.
500INTERNAL_ERROR: unexpected failure. Quote X-Request-Id to support.

Get the call-filter vocabulary

GET/api/v1/switch/call-filters

Access: API key. Scoped keys need switch:manage.
Rate limit: 100 requests per second (the default)

The shared filter names and closed value sets used by call records, quality and live calls.

Response 200

FieldDescription

datarequired
object

Errors

400VALIDATION_ERROR, INVALID_INPUT or BAD_REQUEST. For VALIDATION_ERROR, error.details is an array of { path, message }.
401UNAUTHORIZED: missing, invalid, expired or revoked credential.
402SWITCH_SUBSCRIPTION_REQUIRED: the account has no active Switch plan or trial.
403FORBIDDEN: not allowed - a scoped key lacks the scope, or the endpoint is session-only.
429RATE_LIMITED: slow down and retry after the Retry-After seconds.
500INTERNAL_ERROR: unexpected failure. Quote X-Request-Id to support.

Get the list-filter vocabulary

GET/api/v1/switch/list-filters

Access: API key. Scoped keys need switch:manage.
Rate limit: 100 requests per second (the default)

Filter names and value sets for the customer, supplier and trunk lists.

Response 200

FieldDescription

datarequired
object

Errors

400VALIDATION_ERROR, INVALID_INPUT or BAD_REQUEST. For VALIDATION_ERROR, error.details is an array of { path, message }.
401UNAUTHORIZED: missing, invalid, expired or revoked credential.
402SWITCH_SUBSCRIPTION_REQUIRED: the account has no active Switch plan or trial.
403FORBIDDEN: not allowed - a scoped key lacks the scope, or the endpoint is session-only.
429RATE_LIMITED: slow down and retry after the Retry-After seconds.
500INTERNAL_ERROR: unexpected failure. Quote X-Request-Id to support.

Get one call record with attempts, SIP trace and timeline

GET/api/v1/switch/cdrs/{id}

Access: API key. Scoped keys need switch:manage.
Rate limit: 100 requests per second (the default)

Numbers: a scoped API key without the cdr:numbers scope receives masked calling and dialled numbers (numbersMasked says so). Full-access keys and dashboard sessions see them in full. A record that is not yours answers 404 NOT_FOUND.

Parameters

idrequired
path · string

Response 200

FieldDescription

datarequired
object
idrequired
string (uuid) · data.id
createdAtrequired
string (date-time) · data.createdAt
ISO-8601 timestamp (UTC)
kindrequired
string · data.kind
One of voice, sms
directionrequired
string · data.direction
fromrequired
string | null · data.from
torequired
string | null · data.to
clirequired
string | null · data.cli
statusrequired
string · data.status
sipCoderequired
integer | null · data.sipCode
hangupCauserequired
string | null · data.hangupCause
durationSecondsrequired
integer | null · data.durationSeconds
billedSecondsrequired
integer | null · data.billedSeconds
segmentsrequired
integer | null · data.segments
pddMsrequired
integer | null · data.pddMs
callGroupIdrequired
string | null · data.callGroupId
Shared by every failover attempt of one call
customerrequired
string | null · data.customer
supplierrequired
string | null · data.supplier
revenuerequired
number · data.revenue
US dollars as a JSON number rounded to 6 decimals (a computed figure, not a ledger string)
costrequired
number · data.cost
US dollars as a JSON number rounded to 6 decimals (a computed figure, not a ledger string)
marginrequired
number · data.margin
US dollars as a JSON number rounded to 6 decimals (a computed figure, not a ledger string)
sellRatePerUnitrequired
number | null · data.sellRatePerUnit
null when the call could not be rated (distinct from a real 0)
buyRatePerUnitrequired
number | null · data.buyRatePerUnit
US dollars as a JSON number rounded to 6 decimals (a computed figure, not a ledger string)
ratingStaterequired
string | null · data.ratingState
mosrequired
number | null · data.mos
jitterMsrequired
number | null · data.jitterMs
packetLossPctrequired
number | null · data.packetLossPct
mediaModerequired
string | null · data.mediaMode
codecrequired
string | null · data.codec
q850Causerequired
integer | null · data.q850Cause
destinationNamerequired
string | null · data.destinationName
riskScore
number | null · data.riskScore
attestation
string | null · data.attestation
customerTrunkId
string (uuid) | null · data.customerTrunkId
attemptCount
integer · data.attemptCount
invoiceId
string (uuid) | null · data.invoiceId
attemptsrequired
object[] · data.attempts
Every supplier attempt of this call, including skipped candidates
tracerequired
object | null · data.trace
The captured SIP messages, when available
timelinerequired
object · data.timeline
startedAtrequired
string (date-time) | null · data.timeline.startedAt
ISO-8601 timestamp (UTC)
startedFromrequired
string | null · data.timeline.startedFrom
One of first_sip_message, first_supplier_attempt
answeredAtrequired
string (date-time) | null · data.timeline.answeredAt
ISO-8601 timestamp (UTC)
endedAtrequired
string (date-time) | null · data.timeline.endedAt
ISO-8601 timestamp (UTC)
recordedAtrequired
string (date-time) | null · data.timeline.recordedAt
ISO-8601 timestamp (UTC)

Errors

400VALIDATION_ERROR, INVALID_INPUT or BAD_REQUEST. For VALIDATION_ERROR, error.details is an array of { path, message }.
401UNAUTHORIZED: missing, invalid, expired or revoked credential.
402SWITCH_SUBSCRIPTION_REQUIRED: the account has no active Switch plan or trial.
403FORBIDDEN: not allowed - a scoped key lacks the scope, or the endpoint is session-only.
404NOT_FOUND: no such resource on your account.
429RATE_LIMITED: slow down and retry after the Retry-After seconds.
500INTERNAL_ERROR: unexpected failure. Quote X-Request-Id to support.

List the supplier attempts of a call

GET/api/v1/switch/cdrs/{id}/attempts

Access: API key. Scoped keys need switch:manage.
Rate limit: 100 requests per second (the default)

A record that is not yours answers 404 NOT_FOUND.

Parameters

idrequired
path · string

Response 200

FieldDescription

datarequired
object[]

Errors

400VALIDATION_ERROR, INVALID_INPUT or BAD_REQUEST. For VALIDATION_ERROR, error.details is an array of { path, message }.
401UNAUTHORIZED: missing, invalid, expired or revoked credential.
402SWITCH_SUBSCRIPTION_REQUIRED: the account has no active Switch plan or trial.
403FORBIDDEN: not allowed - a scoped key lacks the scope, or the endpoint is session-only.
404NOT_FOUND: no such resource on your account.
429RATE_LIMITED: slow down and retry after the Retry-After seconds.
500INTERNAL_ERROR: unexpected failure. Quote X-Request-Id to support.

List saved call-record views

GET/api/v1/switch/cdr-views

Access: API key. Scoped keys need switch:manage.
Rate limit: 100 requests per second (the default)

Response 200

FieldDescription

datarequired
object[]
idrequired
string (uuid) · data[].id
namerequired
string · data[].name
servicerequired
string · data[].service
One of voice, sms
filtersrequired
object · data[].filters
columnsrequired
string[] · data[].columns
sortrequired
object[] · data[].sort
fieldrequired
string · data[].sort[].field
directionrequired
string · data[].sort[].direction
One of asc, desc
isDefaultrequired
boolean · data[].isDefault
createdAtrequired
string (date-time) · data[].createdAt
ISO-8601 timestamp (UTC)
updatedAtrequired
string (date-time) · data[].updatedAt
ISO-8601 timestamp (UTC)

Errors

400VALIDATION_ERROR, INVALID_INPUT or BAD_REQUEST. For VALIDATION_ERROR, error.details is an array of { path, message }.
401UNAUTHORIZED: missing, invalid, expired or revoked credential.
402SWITCH_SUBSCRIPTION_REQUIRED: the account has no active Switch plan or trial.
403FORBIDDEN: not allowed - a scoped key lacks the scope, or the endpoint is session-only.
429RATE_LIMITED: slow down and retry after the Retry-After seconds.
500INTERNAL_ERROR: unexpected failure. Quote X-Request-Id to support.

Save a call-record view

POST/api/v1/switch/cdr-views

Access: API key. Scoped keys need switch:manage.
Rate limit: 100 requests per second (the default)

Creates the view, or replaces the one with the same name.

Test keys: refused with 403 TEST_KEY_NOT_ALLOWED. The Switch has no test mode, so a change always applies to your live configuration. Test keys can still read Switch data.

Request body (application/json)

FieldDescription

namerequired
string
max 120 chars
service
string
One of voice, sms
filters
object
columns
string[]
sort
object[]
fieldrequired
string · sort[].field
max 64 chars
directionrequired
string · sort[].direction
One of asc, desc
isDefault
boolean

Response 201

FieldDescription

datarequired
object
Same fields as SwitchCdrView, shown earlier on this page.

Response 202

FieldDescription

datarequired
object
approvalRequired
boolean · data.approvalRequired
One of true
approvalRequestId
string (uuid) | null · data.approvalRequestId
permission
string · data.permission
expiresAt
string (date-time) · data.expiresAt
message
string · data.message

Errors

400VALIDATION_ERROR, INVALID_INPUT or BAD_REQUEST. For VALIDATION_ERROR, error.details is an array of { path, message }.
401UNAUTHORIZED: missing, invalid, expired or revoked credential.
402SWITCH_SUBSCRIPTION_REQUIRED: the account has no active Switch plan or trial.
403FORBIDDEN: not allowed - a scoped key lacks the scope, or the endpoint is session-only.
409CONFLICT (or a code-specific 409): the change clashes with existing state.
429RATE_LIMITED: slow down and retry after the Retry-After seconds.
500INTERNAL_ERROR: unexpected failure. Quote X-Request-Id to support.

HTTP

curl -X POST "https://packetexchange.io/api/v1/switch/cdr-views" \
  -H "Authorization: Bearer $PACKETEXCHANGE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "name": "Acme"
}'

Run it here with a test key.

Delete a saved call-record view

DELETE/api/v1/switch/cdr-views/{viewId}

Access: API key. Scoped keys need switch:manage.
Rate limit: 100 requests per second (the default)

Answers { success: true } with no data, whether or not the view existed.

Test keys: refused with 403 TEST_KEY_NOT_ALLOWED. The Switch has no test mode, so a change always applies to your live configuration. Test keys can still read Switch data.

Parameters

viewIdrequired
path · string

Response 200

FieldDescription

datarequired
any | enum | null
Not sent by this endpoint

Response 202

FieldDescription

datarequired
object
approvalRequired
boolean · data.approvalRequired
One of true
approvalRequestId
string (uuid) | null · data.approvalRequestId
permission
string · data.permission
expiresAt
string (date-time) · data.expiresAt
message
string · data.message

Errors

400VALIDATION_ERROR, INVALID_INPUT or BAD_REQUEST. For VALIDATION_ERROR, error.details is an array of { path, message }.
401UNAUTHORIZED: missing, invalid, expired or revoked credential.
402SWITCH_SUBSCRIPTION_REQUIRED: the account has no active Switch plan or trial.
403FORBIDDEN: not allowed - a scoped key lacks the scope, or the endpoint is session-only.
404NOT_FOUND: no such resource on your account.
409CONFLICT (or a code-specific 409): the change clashes with existing state.
429RATE_LIMITED: slow down and retry after the Retry-After seconds.
500INTERNAL_ERROR: unexpected failure. Quote X-Request-Id to support.

Get the SIP trace of a call

GET/api/v1/switch/cdrs/{id}/trace

Access: API key. Scoped keys need switch:manage.
Rate limit: 100 requests per second (the default)

The signalling ladder for the call. Access is recorded in your account activity. A record that is not yours answers 404 NOT_FOUND.

Parameters

idrequired
path · string

Response 200

FieldDescription

datarequired
object

Errors

400VALIDATION_ERROR, INVALID_INPUT or BAD_REQUEST. For VALIDATION_ERROR, error.details is an array of { path, message }.
401UNAUTHORIZED: missing, invalid, expired or revoked credential.
402SWITCH_SUBSCRIPTION_REQUIRED: the account has no active Switch plan or trial.
403FORBIDDEN: not allowed - a scoped key lacks the scope, or the endpoint is session-only.
404NOT_FOUND: no such resource on your account.
429RATE_LIMITED: slow down and retry after the Retry-After seconds.
500INTERNAL_ERROR: unexpected failure. Quote X-Request-Id to support.

Re-run routing for a call record

POST/api/v1/switch/cdrs/{id}/retest

Access: API key. Scoped keys need switch:manage.
Rate limit: 10 requests per minute

Resolves the route this call would take now, without placing a call, so a fix can be checked against the original failure.

Test keys: refused with 403 TEST_KEY_NOT_ALLOWED. The Switch has no test mode, so a change always applies to your live configuration. Test keys can still read Switch data.

Parameters

idrequired
path · string

Response 200

FieldDescription

datarequired
object

Response 202

FieldDescription

datarequired
object
approvalRequired
boolean · data.approvalRequired
One of true
approvalRequestId
string (uuid) | null · data.approvalRequestId
permission
string · data.permission
expiresAt
string (date-time) · data.expiresAt
message
string · data.message

Errors

400VALIDATION_ERROR, INVALID_INPUT or BAD_REQUEST. For VALIDATION_ERROR, error.details is an array of { path, message }.
401UNAUTHORIZED: missing, invalid, expired or revoked credential.
402SWITCH_SUBSCRIPTION_REQUIRED: the account has no active Switch plan or trial.
403FORBIDDEN: not allowed - a scoped key lacks the scope, or the endpoint is session-only.
404NOT_FOUND: no such resource on your account.
409CONFLICT (or a code-specific 409): the change clashes with existing state.
429RATE_LIMITED: slow down and retry after the Retry-After seconds.
500INTERNAL_ERROR: unexpected failure. Quote X-Request-Id to support.

Download filtered call records as CSV

GET/api/v1/switch/cdrs.csv

Access: API key. Scoped keys need switch:manage.
Rate limit: 100 requests per second (the default)

Synchronous export, capped at a row ceiling; X-PKX-Row-Count, X-PKX-Truncated and X-PKX-Query-Id headers describe the file. For large windows use POST /switch/cdr-exports. Numbers: a scoped API key without the cdr:numbers scope receives masked calling and dialled numbers (numbersMasked says so). Full-access keys and dashboard sessions see them in full.

Parameters

from
query · string
ISO-8601 start of the window
to
query · string
ISO-8601 end of the window
kind
query · string
One of voice, sms
direction
query · string
One of inbound, outbound
status
query · string
subAccountId
query · string (uuid)
Customer
customerTrunkId
query · string (uuid)
vendorTrunkId
query · string (uuid)
Supplier trunk
supplierTrunkMatch
query · string
How vendorTrunkId matches failover attempts (default selected)One of selected, attempted, either
routeGroupId
query · string (uuid)
countryPrefix
query · string
destination
query · string
destinationName
query · string
answeredOnly
query · string
One of true, false
answeredState
query · string
One of answered, unanswered
mediaMode
query · string
One of direct, proxy
sipCode
query · integer
sipCodes
query · string
Comma-separated SIP codes (max 20)
q850Cause
query · integer
q850Causes
query · string
Comma-separated Q.850 causes (max 20)
hangupCause
query · string
durationMin
query · number
durationMax
query · number
pddMinMs
query · number
pddMaxMs
query · number
codec
query · string
releaseParty
query · string
ip
query · string
ratingState
query · string
One of rated, unrated
negativeMarginOnly
query · string
One of true, false
riskMin
query · number
attestation
query · string
One of A, B, C
search
query · string
Up to 20 values separated by comma, semicolon or newline
searchField
query · string
searchMatch
query · string
One of any, all
sortBy
query · string
sortDir
query · string
One of asc, desc
includeProbes
query · string
Include the platform's synthetic reachability probes (hidden by default)One of true, false
limit
query · integer
offset
query · integer

Response 200 (text/csv)

CSV of the filtered call records, as an attachment.

Errors

400VALIDATION_ERROR, INVALID_INPUT or BAD_REQUEST. For VALIDATION_ERROR, error.details is an array of { path, message }.
401UNAUTHORIZED: missing, invalid, expired or revoked credential.
402SWITCH_SUBSCRIPTION_REQUIRED: the account has no active Switch plan or trial.
403FORBIDDEN: not allowed - a scoped key lacks the scope, or the endpoint is session-only.
429RATE_LIMITED: slow down and retry after the Retry-After seconds.
500INTERNAL_ERROR: unexpected failure. Quote X-Request-Id to support.