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

Name	In	Type	Description
`from`	query	string	ISO-8601 start (default: 30 days before to)
`to`	query	string	ISO-8601 end (default: now)

Response 200

Field	Type	Description
`data`required	object	-
`revenue`requireddata.revenue	number	US dollars as a JSON number rounded to 6 decimals (a computed figure, not a ledger string)
`cost`requireddata.cost	number	US dollars as a JSON number rounded to 6 decimals (a computed figure, not a ledger string)
`margin`requireddata.margin	number	US dollars as a JSON number rounded to 6 decimals (a computed figure, not a ledger string)
`marginPct`requireddata.marginPct	number \| null	null when there was no revenue
`calls`requireddata.calls	integer	-
`answered`requireddata.answered	integer	-
`minutes`requireddata.minutes	number	-
`asr`requireddata.asr	number \| null	Answer rate in percent; null when there were no calls
`window`requireddata.window	object	-
`from`requireddata.window.from	string (date-time)	ISO-8601 timestamp (UTC)
`to`requireddata.window.to	string (date-time)	ISO-8601 timestamp (UTC)
`label`requireddata.window.label	string	-
`freshness`requireddata.freshness	object	-
`rating`requireddata.rating	object	-
`unratedBilled`requireddata.rating.unratedBilled	integer	-
`billedCalls`requireddata.rating.billedCalls	integer	-
`unratedPct`requireddata.rating.unratedPct	number	-
`unratedRevenue`requireddata.rating.unratedRevenue	number	US dollars as a JSON number rounded to 6 decimals (a computed figure, not a ledger string)
`unratedMinutes`requireddata.rating.unratedMinutes	number	-

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

Name	In	Type	Description
`from`	query	string	ISO-8601 start (default: 30 days before to)
`to`	query	string	ISO-8601 end (default: now)

Response 200

Field	Type	Description
`data`required	object[]	-
`revenue`requireddata[].revenue	number	US dollars as a JSON number rounded to 6 decimals (a computed figure, not a ledger string)
`cost`requireddata[].cost	number	US dollars as a JSON number rounded to 6 decimals (a computed figure, not a ledger string)
`margin`requireddata[].margin	number	US dollars as a JSON number rounded to 6 decimals (a computed figure, not a ledger string)
`marginPct`requireddata[].marginPct	number \| null	null when there was no revenue
`calls`requireddata[].calls	integer	-
`answered`requireddata[].answered	integer	-
`minutes`requireddata[].minutes	number	-
`asr`requireddata[].asr	number \| null	Answer rate in percent; null when there were no calls
`day`requireddata[].day	string	-

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

Name	In	Type	Description
`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

Field	Type	Description
`data`required	object[]	-
`revenue`requireddata[].revenue	number	US dollars as a JSON number rounded to 6 decimals (a computed figure, not a ledger string)
`cost`requireddata[].cost	number	US dollars as a JSON number rounded to 6 decimals (a computed figure, not a ledger string)
`margin`requireddata[].margin	number	US dollars as a JSON number rounded to 6 decimals (a computed figure, not a ledger string)
`marginPct`requireddata[].marginPct	number \| null	null when there was no revenue
`calls`requireddata[].calls	integer	-
`answered`requireddata[].answered	integer	-
`minutes`requireddata[].minutes	number	-
`asr`requireddata[].asr	number \| null	Answer rate in percent; null when there were no calls
`key`requireddata[].key	string	-
`label`requireddata[].label	string	-
`external`data[].external	boolean	-

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

Field	Type	Description
`data`required	object[]	-
`id`requireddata[].id	string (uuid)	-
`phase`requireddata[].phase	string	queued, running, completed or failed
`status`requireddata[].status	string	-
`requestedScope`requireddata[].requestedScope	string \| null	-
`requestedAt`requireddata[].requestedAt	string	-
`recordCount`requireddata[].recordCount	integer \| null	Only set once completed
`numbersMasked`requireddata[].numbersMasked	boolean	-
`addressesMasked`requireddata[].addressesMasked	boolean	-
`truncated`data[].truncated	boolean	-
`error`data[].error	string \| null	-
`completedAt`data[].completedAt	string (date-time) \| null	ISO-8601 timestamp (UTC)
`downloadable`data[].downloadable	boolean	-
`downloadUrl`data[].downloadUrl	string \| null	GET /billing/exports/{id}/download once completed. No server path is ever returned.
`rowCount`data[].rowCount	integer \| null	-
`createdAt`data[].createdAt	string (date-time)	ISO-8601 timestamp (UTC)
`queryId`data[].queryId	string \| null	-

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)

Field	Type	Description
`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

Field	Type	Description
`data`required	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

Name	In	Type	Description
`id`required	path	string	-

Response 200

Field	Type	Description
`data`required	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

Name	In	Type	Description
`subAccountId`required	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

Field	Type	Description
`data`required	object	-
`window`requireddata.window	object	-
`subAccountId`requireddata.window.subAccountId	string (uuid)	-
`since`requireddata.window.since	string (date-time)	ISO-8601 timestamp (UTC)
`until`requireddata.window.until	string (date-time)	ISO-8601 timestamp (UTC)
`nextSince`requireddata.window.nextSince	string (date-time)	ISO-8601 timestamp (UTC)
`clamped`requireddata.window.clamped	boolean	-
`maxWindowDays`requireddata.window.maxWindowDays	integer	-
`totals`requireddata.totals	object	Calls, answered, minutes, revenue, cost and rejectedAtCapacity over the window
`daily`requireddata.daily	object[]	-
`live`requireddata.live	object	-
`concurrentCalls`requireddata.live.concurrentCalls	integer \| null	-
`byDestination`data.byDestination	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.

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

Name	In	Type	Description
`id`required	path	string	-

Request body (application/json)

Field	Type	Description
`what`	string	What was copied (default "diagnostics")max 64 chars

Response 202

Field	Type	Description
`data`required	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

Field	Type	Description
`data`required	object	-
`ingressTrunks`requireddata.ingressTrunks	object[]	-
`id`requireddata.ingressTrunks[].id	string (uuid)	-
`label`requireddata.ingressTrunks[].label	string	-
`owner`requireddata.ingressTrunks[].owner	string \| null	-
`techPrefix`requireddata.ingressTrunks[].techPrefix	string \| null	-
`egressTrunks`requireddata.egressTrunks	object[]	-
`id`requireddata.egressTrunks[].id	string (uuid)	-
`label`requireddata.egressTrunks[].label	string	-
`owner`requireddata.egressTrunks[].owner	string \| null	-
`techPrefix`requireddata.egressTrunks[].techPrefix	string \| null	-
`routeGroups`requireddata.routeGroups	object[]	-
`id`requireddata.routeGroups[].id	string (uuid)	-
`label`requireddata.routeGroups[].label	string	-
`country`requireddata.routeGroups[].country	string \| null	-
`hasRiskScores`requireddata.hasRiskScores	boolean	-
`hasAttestation`requireddata.hasAttestation	boolean	-

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

Field	Type	Description
`data`required	object \| null	null until a layout has been saved
`order`data.order	string[]	-
`cols`data.cols	string[]	-
`compact`data.compact	boolean	-
`pageSize`data.pageSize	number	-
`widths`data.widths	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.

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)

Field	Type	Description
`order`	string[]	-
`cols`	string[]	-
`compact`	boolean	-
`pageSize`	number	-
`widths`	object	-

Response 200

Field	Type	Description
`data`required	object	-
`order`data.order	string[]	-
`cols`data.cols	string[]	-
`compact`data.compact	boolean	-
`pageSize`data.pageSize	number	-
`widths`data.widths	object	-

Response 202

Field	Type	Description
`data`required	object	-
`approvalRequired`data.approvalRequired	boolean	-One of `true`
`approvalRequestId`data.approvalRequestId	string (uuid) \| null	-
`permission`data.permission	string	-
`expiresAt`data.expiresAt	string (date-time)	-
`message`data.message	string	-

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

Name	In	Type	Description
`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

Field	Type	Description
`data`required	object	-
`rows`requireddata.rows	object[]	-
`id`requireddata.rows[].id	string (uuid)	-
`createdAt`requireddata.rows[].createdAt	string (date-time)	ISO-8601 timestamp (UTC)
`kind`requireddata.rows[].kind	string	-One of `voice`, `sms`
`direction`requireddata.rows[].direction	string	-
`from`requireddata.rows[].from	string \| null	-
`to`requireddata.rows[].to	string \| null	-
`cli`requireddata.rows[].cli	string \| null	-
`status`requireddata.rows[].status	string	-
`sipCode`requireddata.rows[].sipCode	integer \| null	-
`hangupCause`requireddata.rows[].hangupCause	string \| null	-
`durationSeconds`requireddata.rows[].durationSeconds	integer \| null	-
`billedSeconds`requireddata.rows[].billedSeconds	integer \| null	-
`segments`requireddata.rows[].segments	integer \| null	-
`pddMs`requireddata.rows[].pddMs	integer \| null	-
`callGroupId`requireddata.rows[].callGroupId	string \| null	Shared by every failover attempt of one call
`customer`requireddata.rows[].customer	string \| null	-
`supplier`requireddata.rows[].supplier	string \| null	-
`revenue`requireddata.rows[].revenue	number	US dollars as a JSON number rounded to 6 decimals (a computed figure, not a ledger string)
`cost`requireddata.rows[].cost	number	US dollars as a JSON number rounded to 6 decimals (a computed figure, not a ledger string)
`margin`requireddata.rows[].margin	number	US dollars as a JSON number rounded to 6 decimals (a computed figure, not a ledger string)
`sellRatePerUnit`requireddata.rows[].sellRatePerUnit	number \| null	null when the call could not be rated (distinct from a real 0)
`buyRatePerUnit`requireddata.rows[].buyRatePerUnit	number \| null	US dollars as a JSON number rounded to 6 decimals (a computed figure, not a ledger string)
`ratingState`requireddata.rows[].ratingState	string \| null	-
`mos`requireddata.rows[].mos	number \| null	-
`jitterMs`requireddata.rows[].jitterMs	number \| null	-
`packetLossPct`requireddata.rows[].packetLossPct	number \| null	-
`mediaMode`requireddata.rows[].mediaMode	string \| null	-
`codec`requireddata.rows[].codec	string \| null	-
`q850Cause`requireddata.rows[].q850Cause	integer \| null	-
`destinationName`requireddata.rows[].destinationName	string \| null	-
`riskScore`data.rows[].riskScore	number \| null	-
`attestation`data.rows[].attestation	string \| null	-
`customerTrunkId`data.rows[].customerTrunkId	string (uuid) \| null	-
`attemptCount`data.rows[].attemptCount	integer	-
`invoiceId`data.rows[].invoiceId	string (uuid) \| null	-
`total`requireddata.total	integer	-
`limit`requireddata.limit	integer	-
`offset`requireddata.offset	integer	-
`summary`requireddata.summary	object	Window totals: calls, answeredCalls, asrPercent, acdSeconds, talkSeconds, billableSeconds, pddMedianMs, pddP95Ms, revenue, cost, margin, ingestionLagSeconds...
`numbersMasked`requireddata.numbersMasked	boolean	-
`addressesMasked`requireddata.addressesMasked	boolean	-
`fieldVisibility`requireddata.fieldVisibility	object	-
`generatedAt`requireddata.generatedAt	string (date-time)	ISO-8601 timestamp (UTC)
`window`requireddata.window	object	-
`from`requireddata.window.from	string (date-time) \| null	ISO-8601 timestamp (UTC)
`to`requireddata.window.to	string (date-time) \| null	ISO-8601 timestamp (UTC)
`clamped`requireddata.window.clamped	boolean	-
`maxWindowDays`requireddata.window.maxWindowDays	integer	-
`queryId`requireddata.queryId	string	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

Name	In	Type	Description
`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

Field	Type	Description
`data`required	object	-
`queryId`requireddata.queryId	string	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

Name	In	Type	Description
`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

Field	Type	Description
`data`required	object	-
`queryId`requireddata.queryId	string	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

Name	In	Type	Description
`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

Field	Type	Description
`data`required	object	-
`queryId`requireddata.queryId	string	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

Name	In	Type	Description
`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

Field	Type	Description
`data`required	object	-
`queryId`requireddata.queryId	string	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

Field	Type	Description
`data`required	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

Field	Type	Description
`data`required	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

Name	In	Type	Description
`id`required	path	string	-

Response 200

Field	Type	Description
`data`required	object	-
`id`requireddata.id	string (uuid)	-
`createdAt`requireddata.createdAt	string (date-time)	ISO-8601 timestamp (UTC)
`kind`requireddata.kind	string	-One of `voice`, `sms`
`direction`requireddata.direction	string	-
`from`requireddata.from	string \| null	-
`to`requireddata.to	string \| null	-
`cli`requireddata.cli	string \| null	-
`status`requireddata.status	string	-
`sipCode`requireddata.sipCode	integer \| null	-
`hangupCause`requireddata.hangupCause	string \| null	-
`durationSeconds`requireddata.durationSeconds	integer \| null	-
`billedSeconds`requireddata.billedSeconds	integer \| null	-
`segments`requireddata.segments	integer \| null	-
`pddMs`requireddata.pddMs	integer \| null	-
`callGroupId`requireddata.callGroupId	string \| null	Shared by every failover attempt of one call
`customer`requireddata.customer	string \| null	-
`supplier`requireddata.supplier	string \| null	-
`revenue`requireddata.revenue	number	US dollars as a JSON number rounded to 6 decimals (a computed figure, not a ledger string)
`cost`requireddata.cost	number	US dollars as a JSON number rounded to 6 decimals (a computed figure, not a ledger string)
`margin`requireddata.margin	number	US dollars as a JSON number rounded to 6 decimals (a computed figure, not a ledger string)
`sellRatePerUnit`requireddata.sellRatePerUnit	number \| null	null when the call could not be rated (distinct from a real 0)
`buyRatePerUnit`requireddata.buyRatePerUnit	number \| null	US dollars as a JSON number rounded to 6 decimals (a computed figure, not a ledger string)
`ratingState`requireddata.ratingState	string \| null	-
`mos`requireddata.mos	number \| null	-
`jitterMs`requireddata.jitterMs	number \| null	-
`packetLossPct`requireddata.packetLossPct	number \| null	-
`mediaMode`requireddata.mediaMode	string \| null	-
`codec`requireddata.codec	string \| null	-
`q850Cause`requireddata.q850Cause	integer \| null	-
`destinationName`requireddata.destinationName	string \| null	-
`riskScore`data.riskScore	number \| null	-
`attestation`data.attestation	string \| null	-
`customerTrunkId`data.customerTrunkId	string (uuid) \| null	-
`attemptCount`data.attemptCount	integer	-
`invoiceId`data.invoiceId	string (uuid) \| null	-
`attempts`requireddata.attempts	object[]	Every supplier attempt of this call, including skipped candidates
`trace`requireddata.trace	object \| null	The captured SIP messages, when available
`timeline`requireddata.timeline	object	-
`startedAt`requireddata.timeline.startedAt	string (date-time) \| null	ISO-8601 timestamp (UTC)
`startedFrom`requireddata.timeline.startedFrom	string \| null	-One of `first_sip_message`, `first_supplier_attempt`
`answeredAt`requireddata.timeline.answeredAt	string (date-time) \| null	ISO-8601 timestamp (UTC)
`endedAt`requireddata.timeline.endedAt	string (date-time) \| null	ISO-8601 timestamp (UTC)
`recordedAt`requireddata.timeline.recordedAt	string (date-time) \| null	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

Name	In	Type	Description
`id`required	path	string	-

Response 200

Field	Type	Description
`data`required	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

Field	Type	Description
`data`required	object[]	-
`id`requireddata[].id	string (uuid)	-
`name`requireddata[].name	string	-
`service`requireddata[].service	string	-One of `voice`, `sms`
`filters`requireddata[].filters	object	-
`columns`requireddata[].columns	string[]	-
`sort`requireddata[].sort	object[]	-
`field`requireddata[].sort[].field	string	-
`direction`requireddata[].sort[].direction	string	-One of `asc`, `desc`
`isDefault`requireddata[].isDefault	boolean	-
`createdAt`requireddata[].createdAt	string (date-time)	ISO-8601 timestamp (UTC)
`updatedAt`requireddata[].updatedAt	string (date-time)	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)

Field	Type	Description
`name`required	string	-max 120 chars
`service`	string	-One of `voice`, `sms`
`filters`	object	-
`columns`	string[]	-
`sort`	object[]	-
`field`requiredsort[].field	string	-max 64 chars
`direction`requiredsort[].direction	string	-One of `asc`, `desc`
`isDefault`	boolean	-

Response 201

Field	Type	Description
`data`required	object	Same fields as SwitchCdrView, shown earlier on this page.

Response 202

Field	Type	Description
`data`required	object	-
`approvalRequired`data.approvalRequired	boolean	-One of `true`
`approvalRequestId`data.approvalRequestId	string (uuid) \| null	-
`permission`data.permission	string	-
`expiresAt`data.expiresAt	string (date-time)	-
`message`data.message	string	-

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

Name	In	Type	Description
`viewId`required	path	string	-

Response 200

Field	Type	Description
`data`required	any \| enum \| null	Not sent by this endpoint

Response 202

Field	Type	Description
`data`required	object	-
`approvalRequired`data.approvalRequired	boolean	-One of `true`
`approvalRequestId`data.approvalRequestId	string (uuid) \| null	-
`permission`data.permission	string	-
`expiresAt`data.expiresAt	string (date-time)	-
`message`data.message	string	-

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

Name	In	Type	Description
`id`required	path	string	-

Response 200

Field	Type	Description
`data`required	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

Name	In	Type	Description
`id`required	path	string	-

Response 200

Field	Type	Description
`data`required	object	-

Response 202

Field	Type	Description
`data`required	object	-
`approvalRequired`data.approvalRequired	boolean	-One of `true`
`approvalRequestId`data.approvalRequestId	string (uuid) \| null	-
`permission`data.permission	string	-
`expiresAt`data.expiresAt	string (date-time)	-
`message`data.message	string	-

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

Name	In	Type	Description
`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.