--- title: "List calls" method: GET path: "/v3/voice/calls" tags: ["Voice"] --- # List calls `GET /v3/voice/calls` ## Request - Base URL: `https://api.sent.dm` - URL: `https://api.sent.dm/v3/voice/calls` - Auth: one of: - API key in header `x-api-key` - HTTP bearer Retrieves a paginated list of your calls, most recent first. Filter by direction, status, the owning number, the mode (inapp, or agent for calls your voice agents answered), the agent that answered, and the time the call started (from and to are inclusive). Each call carries the phone number it was connected to, the caller id it showed, and the billed legs with what each cost. Use the call webhooks for real-time updates; this list is for looking calls up afterwards. ## Query parameters - `page` integer, required - `page_size` integer, required - `direction` string, nullable - `status` string, nullable - `number` string, nullable - `mode` string, nullable - `agent_id` string, nullable - `from` string, date-time, nullable - `to` string, date-time, nullable ## Headers - `x-profile-id` string, uuid ## Response `200` Calls retrieved successfully - SentDmServicesEndpointsCustomerAPIv3SharedApiResponseOfCallsListResponse: Standard API response envelope for all v3 endpoints - `success` boolean: Indicates whether the request was successful - `data` SentDmServicesEndpointsCustomerAPIv3VoiceCallsResponsesCallsListResponse: Paginated list of calls - `calls` SentDmServicesEndpointsCustomerAPIv3VoiceCallsResponsesCallResponse[]: The calls on this page, most recent first - `id` string: The call id, the same one carried by the call.request question and every call webhook - `mode` string: The calling mode: inapp for a call between people in your app and phone numbers, routed by your number's callback URL; agent for a call one of your voice agents answered - `agent_id` string, nullable: The voice agent that answered the call, such as agent_9f2ab000-0000-4000-8000-000000000001. Null for an inapp call - `direction` string: outbound for a call placed from your app, inbound for a call to one of your numbers - `from` SentDmServicesEndpointsCustomerAPIv3VoiceCallsResponsesCallParty: One end of a call - `kind` string: user for one of your app users, number for a phone number, conference for a room, anonymous for a caller who withheld their number - `value` string, nullable: The app user's identity, the phone number in E.164 format, or the room name. Null when the kind is anonymous - `to` SentDmServicesEndpointsCustomerAPIv3VoiceCallsResponsesCallParty: One end of a call - `kind` string: user for one of your app users, number for a phone number, conference for a room, anonymous for a caller who withheld their number - `value` string, nullable: The app user's identity, the phone number in E.164 format, or the room name. Null when the kind is anonymous - `number` string: Your number that owns the call, in E.164 format: the dialed number for an inbound call, the caller's bound number for a call placed from your app - `connected_number` string, nullable: The phone number the call was connected to, in E.164 format: the number your answer dialed, or the fallback number a call to one of your voice agents reached. Null when the call was not connected to a phone number - `caller_id_used` string, nullable: The caller id shown on the phone leg, in E.164 format: the one your answer chose, or the owning number when it chose none. Null for a call with no phone leg - `status` string: INITIATED, RINGING, ANSWERED, COMPLETED, FAILED, NO_ANSWER or REJECTED - `failure_reason` string, nullable: Why the call did not complete: callback_timeout, invalid_answer, insufficient_balance, destination_blocked, callback_not_configured, rejected, no_answer, or for an agent call agent_busy or agent_unreachable. Null while the call is live, when it completed, and when it failed without a recorded reason - `started_at` string, date-time: When the call was placed (UTC) - `answered_at` string, date-time, nullable: When the call was answered (UTC). Null until then, and always null for a call between two of your app users - `ended_at` string, date-time, nullable: When the call ended (UTC). Null while the call is live - `duration_seconds` integer, nullable: Billable duration in seconds. Null while the call is live - `price` number, nullable: What the call cost. Null until it has been priced - `legs` SentDmServicesEndpointsCustomerAPIv3VoiceCallsResponsesCallLegResponse[], nullable: The legs the price covers, one entry per billed leg, each with its own cost: a call your answer connected to a phone number ran the caller's leg to your number and the leg to the connected number at once, and both are billed. Null until the call has been priced - `direction` string: inbound for the caller's leg to your number, outbound for a leg placed on your behalf - `number` string, nullable: The phone number the leg reached, in E.164 format: your number for the inbound leg, the number dialed for an outbound one. Null for a leg to one of your app users or a room - `billed_minutes` integer: The whole minutes the leg was billed for - `cost` number: What the leg cost, in the same unit as the call's price - `currency` string: The currency of the cost: USD - `recording_available` boolean: True once a recording of the call is available - `timeline` SentDmServicesEndpointsCustomerAPIv3VoiceCallsResponsesCallTimelineEntry[], nullable: When the call entered each status, oldest first. Only returned when reading one call - `status` string: INITIATED, RINGING, ANSWERED, COMPLETED, FAILED, NO_ANSWER or REJECTED - `timestamp` string, date-time: When the call entered this status (UTC) - `pagination` SentDmServicesEndpointsCustomerAPIv3SharedPaginationMeta: Pagination metadata for list responses - `page` integer: Current page number (1-indexed) - `page_size` integer: Number of items per page - `total_count` integer: Total number of items across all pages - `total_pages` integer: Total number of pages - `has_more` boolean: Whether there are more pages after this one - `cursors` SentDmServicesEndpointsCustomerAPIv3SharedPaginationCursors: Cursor-based pagination. Never populated — see Cursors. - `after` string, nullable: Cursor to fetch the next page. - `before` string, nullable: Cursor to fetch the previous page. - `error` SentDmServicesEndpointsCustomerAPIv3SharedApiError: Error information - `code` string: Machine-readable error code (e.g., "RESOURCE_001") - `message` string: Human-readable error message - `details` object, nullable: Additional validation error details (field-level errors) - `doc_url` string, nullable: URL to documentation about this error - `meta` SentDmServicesEndpointsCustomerAPIv3SharedApiMeta: Request and response metadata - `request_id` string: Unique identifier for this request (for tracing and support) - `timestamp` string, date-time: Server timestamp when the response was generated - `version` string: API version used for this request ## Other responses - `400`: Invalid paging, filter value, number, or time window - `401`: Unauthorized - Invalid API credentials - `403`: Forbidden - `500`: Internal server error ## Changes - **2026-10-28** `41acb2ceb84d`: 6 info - added the new optional `query` request parameter `agent_id` - added the new optional `query` request parameter `mode` - added the optional property `data/allOf[#/components/schemas/SentDmServicesEndpointsCustomerAPIv3VoiceCallsResponsesCallsListResponse]/calls/items/agent_id` to the response with the `200` status - added the optional property `data/allOf[#/components/schemas/SentDmServicesEndpointsCustomerAPIv3VoiceCallsResponsesCallsListResponse]/calls/items/caller_id_used` to the response with the `200` status - …2 more - **2026-10-23** `1a451bbb5736`: 1 info - endpoint added [Operation history](https://skmtc.dev/sentdm/apis/sent-dm-api-v3/changes/v3/voice/calls/get.md) --- [API](https://skmtc.dev/sentdm/apis/sent-dm-api-v3.md) - [All operations](https://skmtc.dev/sentdm/apis/sent-dm-api-v3/llms.txt) - [OpenAPI document](https://skmtc.dev/sentdm/apis/sent-dm-api-v3/revisions/bdcca958cac7?raw)