---
title: "List voice sessions"
method: GET
path: "/voice/sessions"
tags: ["Voice"]
---

# List voice sessions

`GET /voice/sessions`

## Request

- Base URL: `https://api.natural.com`
- URL: `https://api.natural.com/voice/sessions`
- Auth: HTTP bearer

List voice sessions

## Query parameters

- `customerPartyId` string: Customer party to act for (pty_*). Omit for your account's call log, including delegated activity. Requires authorization from that customer.
- `paymentIntentId` string: Only sessions associated with this payment intent.
- `status` 'awaitingCall' | 'inProgress' | 'ended' | 'canceled' | 'expired': Filter by call-session status.
- `createdAfter` string: Only sessions created after this RFC 3339 timestamp (exclusive).
- `createdBefore` string: Only sessions created before this RFC 3339 timestamp (exclusive).
- `limit` integer: Maximum results per page.
- `cursor` string: Cursor from the previous page with the same customer and filters.

## Headers

- `X-Instance-ID` string, nullable

## Response `200`

Successful Response

- object
  - `data` VoiceSession[], required
    - `id` string, required: Voice session ID (vos_*).
    - `type` 'voiceSession', required: Resource type. Always `voiceSession`.
    - `attributes` object, required: `kind` is the session's purpose and names the block that holds its result. New kinds may be added; ignore kinds you don't handle.
      - `kind` 'payment', required: Collects payment for a payment intent.
      - `status` 'awaitingCall' | 'inProgress' | 'ended' | 'canceled' | 'expired', required: Call lifecycle, independent of payment outcome. `ended` requires a recorded call end. `expired` means the dial window or call time limit passed without a recorded end.
      - `referenceId` string, nullable, required: Reference supplied when the session was created, or null.
      - `callerPhone` string, nullable, required: Supplied caller phone number, or null for a session without one.
      - `dialUri` string, nullable, required: Dial destination while the session accepts a call and you have permission to create payment voice sessions. Otherwise null. Treat it as opaque: store it from the create response and never build it from the session ID.
      - `dialExpiresAt` string, required: RFC 3339 deadline for starting the session's one permitted call.
      - `returnTarget` string, nullable, required: Requested return destination, or null. This does not confirm the destination answered.
      - `call` object, required
        - `startedAt` string, nullable, required: Reported call start time in RFC 3339, or null when unavailable.
        - `endedAt` string, nullable, required: Time the call was recorded as ended in RFC 3339, or null.
        - `durationSeconds` integer, nullable, required: Reported call duration in seconds, or null.
        - `endedBy` 'caller' | 'assistant' | 'unknown', nullable, required: Reported party ending the call. Null before an end is recorded.
        - `summary` string, nullable, required: Redacted call summary, or null.
        - `returnRequestedAt` string, nullable, required: Time a return transfer was requested in RFC 3339, or null. This does not confirm the return leg connected.
      - `completedAt` string, nullable, required: RFC 3339 time the session closed, or null. Set once the call has ended and its result is known, or the session expired or was canceled. `voiceSession.completed` fires once then.
      - `createdAt` string, required: RFC 3339 time the session was created.
      - `updatedAt` string, required: RFC 3339 time the stored session last changed.
      - `payment` object, required
        - `outcome` 'paid' | 'linkSent' | 'unpaid', nullable, required: `paid` when the card was charged on the call. `linkSent` when voice payment did not succeed and the caller was texted the payment link. `unpaid` otherwise. Null until the result is known, which can be while the call is still in progress. A later link payment does not change it. New values may be added.
        - `linkSentAt` string, nullable, required: RFC 3339 time the payment link was texted to the caller, or null.
        - `failedAttempts` integer, required: Card payments that failed during this session.
        - `failure` object, nullable, required: The last failed card payment in this session, or null.
          - `code` string, nullable, required: Failure code, when known. New codes may be added.
          - `reason` string, nullable, required: Explanation of the failure.
          - `advice` 'doNotRetry' | 'tryAgainLater' | 'confirmCardData', nullable, required: Recommended payer action, when known.
    - `relationships` object, required
      - `paymentIntent` object, required: Associated payment intent. Set on `payment` sessions.
        - `data` object, nullable, required: Related resource identifier.
          - `type` 'paymentIntent', required: Resource type. Always `paymentIntent`.
          - `id` string, required
      - `customerParty` object, required: Associated Natural customer, or null when none is associated.
        - `data` object, nullable, required: Related resource identifier.
          - `type` 'party', required: Resource type. Always `party`.
          - `id` string, required
  - `meta` object, required
    - `pagination` object, required
      - `hasMore` boolean, required: Whether more results are available.
      - `nextCursor` string, nullable, required: Cursor for the next page, or null when there are no more results.

## Other responses

- `400`: Validation Error
- `401`: Unauthorized
- `403`: Forbidden
- `404`: Not Found. Returned when the resource does not exist, or when it exists but is not accessible to your account. The two cases are intentionally indistinguishable, so that resource IDs cannot be enumerated by probing.
- `409`: Conflict
- `422`: Validation Error. The response contains one error object for each invalid request value.
- `428`: Precondition Required
- `429`: Too Many Requests
- `500`: Internal Server Error
- `501`: Not Implemented
- `502`: Bad Gateway
- `503`: Service Unavailable

## Changes

- **2026-10-27** `a63c15c71a0c`: 1 breaking, 1 info
  - removed the enum value `failed` from the `query` request parameter `status`
  - removed the `failed` enum value from the `data/items/attributes/anyOf[subschema #1: PaymentVoiceSessionAttributes]/status` response property for the response status `200`
- **2026-09-30** `6663cdab7a7c`: 11 breaking, 1 info
  - the `data/items/attributes` response's property type changed from `object` to no type for status `200`
  - removed the required property `data/items/attributes/call` from the response with the `200` status
  - removed the required property `data/items/attributes/callerPhone` from the response with the `200` status
  - removed the required property `data/items/attributes/createdAt` from the response with the `200` status
  - …8 more
- **2026-09-29** `4fab756be152`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/natural/apis/natural-api/changes/voice/sessions/get.md)

---

[API](https://skmtc.dev/natural/apis/natural-api.md) - [All operations](https://skmtc.dev/natural/apis/natural-api/llms.txt) - [OpenAPI document](https://skmtc.dev/natural/apis/natural-api/revisions/59c1208fa5dc?raw)