> ## Documentation Index > Fetch the complete documentation index at: https://docs.upliftai.org/llms.txt > Use this file to discover all available pages before exploring further. # List an assistant's sessions > Every web session and phone call one assistant handled, newest first. Filters are applied after each page is read, so a page can come back short or even empty with more behind it — keep paging until `nextCursor` is absent. Records are kept for 90 days. ## OpenAPI ````yaml /voice-agents/api-reference/openapi.yaml get /realtime-assistants/{realtimeAssistantId}/sessions openapi: 3.1.0 info: title: UpliftAI Voice Agents API version: '1.0' description: >- Build voice assistants, start conversations on the web or the phone, run calling campaigns, and receive outcomes by webhook. All endpoints take a bearer API key unless noted otherwise. servers: - url: https://api.upliftai.org/v1 security: - apiKey: [] tags: - name: Assistants - name: Authoring an assistant - name: Starting a conversation - name: Sessions & call records - name: Campaigns - name: Campaign outcomes - name: Contacts - name: Google Sheet sources - name: Integrations & delivery health paths: /realtime-assistants/{realtimeAssistantId}/sessions: get: tags: - Sessions & call records summary: List an assistant's sessions description: >- Every web session and phone call one assistant handled, newest first. Filters are applied after each page is read, so a page can come back short or even empty with more behind it — keep paging until `nextCursor` is absent. Records are kept for 90 days. operationId: listAssistantSessions parameters: - name: realtimeAssistantId in: path required: true schema: type: string format: uuid example: 452dda41-ea9d-458f-a14c-a4d0f1c8a342 - name: channel in: query schema: type: string enum: - web - telephony - whatsapp example: telephony - name: direction in: query description: Web sessions are always `inbound` — the user opens them. schema: type: string enum: - inbound - outbound - name: state in: query schema: type: string enum: - created - dispatched - dialing - ringing - answered - active - completed - failed example: completed - name: from in: query description: >- Inclusive lower bound on `createdAt`. Compared as a raw string against the ISO-8601 UTC timestamps in the response, so a non-ISO value silently shifts or voids the range instead of erroring. schema: type: string format: date-time example: '2026-08-16T00:00:00.000Z' - name: to in: query description: Inclusive upper bound on `createdAt`, same format as `from`. schema: type: string format: date-time example: '2026-08-17T00:00:00.000Z' - name: limit in: query description: >- Sessions read per page before filtering. Values above the maximum are clamped, not rejected. schema: type: integer minimum: 1 maximum: 100 default: 50 - name: cursor in: query description: >- The previous page's `nextCursor`, passed back unchanged. Treat it as opaque. schema: type: string - name: assistantAlias in: query description: >- `draft` lists only sessions launched on the draft. `prod` lists everything else, including sessions launched by an exact version number and sessions from before versions existed. schema: type: string enum: - prod - draft - name: include_summary in: query required: false description: >- Adds each call's `summary` to its row, up to about 1 KB each. Must be exactly `true` or `false`, anything else is a 400. A row with no summary leaves the key out: a call that never connected, one not summarised yet, or one from before summaries. schema: type: boolean default: false example: true responses: '200': description: One page of sessions, newest first. content: application/json: schema: $ref: '#/components/schemas/ListSessionsResponse' example: sessions: - sessionId: 25661352-xxxx-xxxx-xxxx-xxxxxxxxxxxx realtimeAssistantId: 452dda41-xxxx-xxxx-xxxx-xxxxxxxxxxxx organizationId: a12b7e74-xxxx-xxxx-xxxx-xxxxxxxxxxxx projectId: c782a4ec-xxxx-xxxx-xxxx-xxxxxxxxxxxx channel: telephony direction: outbound state: completed connected: true toNumber: '+923001234567' fromNumber: '+924238900100' roomName: call-25661352-xxxx-xxxx-xxxx-xxxxxxxxxxxx participantIdentity: callee-25661352 transportProvider: twilio variables: source: assistant-test createdAt: '2026-08-16T18:55:22.677Z' ringingAt: '2026-08-16T18:55:30.758Z' connectedAt: '2026-08-16T18:55:36.927Z' answeredAt: '2026-08-16T18:55:37.641Z' endedAt: '2026-08-16T18:56:17.411Z' durationSec: 40 - sessionId: 138d6508-xxxx-xxxx-xxxx-xxxxxxxxxxxx realtimeAssistantId: 452dda41-xxxx-xxxx-xxxx-xxxxxxxxxxxx organizationId: a12b7e74-xxxx-xxxx-xxxx-xxxxxxxxxxxx projectId: c782a4ec-xxxx-xxxx-xxxx-xxxxxxxxxxxx channel: web direction: inbound state: created connected: false outcome: no_answer roomName: web-138d6508-xxxx-xxxx-xxxx-xxxxxxxxxxxx participantIdentity: عائشہ صدیقی createdAt: '2026-08-18T05:14:25.444Z' nextCursor: >- eyJyZWFsdGltZUFzc2lzdGFudElkIjogIjQ1MmRkYTQxLXh4eHgteHh4eC14eHh4LXh4eHh4eHh4eHh4eCIsICJzZXNzaW9uSWQiOiAiMTM4ZDY1MDgteHh4eC14eHh4LXh4eHgteHh4eHh4eHh4eHh4IiwgImNyZWF0ZWRBdCI6ICIyMDI2LTA4LTE4VDA1OjE0OjI1LjQ0NFoifQ '400': description: A filter value is outside its enum. content: application/json: schema: $ref: '#/components/schemas/Error' example: message: - >- state must be one of the following values: created, dispatched, dialing, ringing, answered, active, completed, failed error: Bad Request statusCode: 400 '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '404': $ref: '#/components/responses/NotFound' components: schemas: ListSessionsResponse: type: object properties: sessions: type: array items: $ref: '#/components/schemas/SessionRecord' nextCursor: type: string description: Present while more pages exist. Error: type: object properties: message: description: >- One message per failed field for validation errors, a single string otherwise. oneOf: - type: string - type: array items: type: string error: type: string statusCode: type: integer SessionRecord: type: object description: One conversation — a browser session or a phone call. properties: sessionId: type: string format: uuid realtimeAssistantId: type: string format: uuid description: >- The assistant that ran the session. Still returned after that assistant is deleted. organizationId: type: string format: uuid projectId: type: string format: uuid channel: type: string enum: - web - telephony - whatsapp direction: type: string enum: - inbound - outbound description: Browser sessions are `inbound` by convention — the user opens them. state: type: string enum: - created - dispatched - dialing - ringing - answered - active - completed - failed description: >- Each channel walks its own path: - **Web session**: `created` → `active` → `completed` - **Phone call**: `dispatched` → `dialing` → `ringing` → `answered` → `completed`, or `failed` The dial hops come from the carrier, which may skip any of them. connected: type: boolean description: >- Whether audio was ever bridged — false for everything up to and including `ringing`. outcome: type: string enum: - busy - no_answer - unreachable - voicemail - silent_pickup - failed description: >- Why no conversation happened; present exactly when `connected` is false. An in-flight call reads `no_answer` simply because it has not connected yet, so treat it as a verdict only once `state` is `failed`. endedBy: type: string enum: - callee - agent - supervisor - system description: Who hung up. toNumber: type: string description: E.164. Telephony only. example: '+923001234567' fromNumber: type: string description: E.164 caller id the callee saw. Telephony only. example: '+924232591000' calleeName: type: string description: >- Display name of the person called, stamped at dial time from the campaign contact. roomName: type: string description: Server-generated, `{prefix}-{sessionId}`. participantIdentity: type: string description: >- Identifies the human on the call: the token identity for a browser session, the SIP participant for a phone call. transportProvider: type: string description: Carrier that placed the call, e.g. `twilio`. example: twilio variables: type: object additionalProperties: true description: >- The values you supplied when the session was created, returned verbatim. campaignId: type: string format: uuid description: Set on calls a campaign dialed. runId: type: string format: uuid description: The campaign run that dialed this call. contactId: type: string description: The campaign contact that was dialed. createdAt: type: string format: date-time description: >- When the record was created — for an outbound call, when it was dispatched, not when it rang. dialingAt: type: string format: date-time description: >- Carrier accepted the dial request. Reported by the carrier, so it can be absent even on a call that connected. ringingAt: type: string format: date-time description: Callee's phone started ringing. Same carrier caveat as `dialingAt`. connectedAt: type: string format: date-time description: Audio bridged (SIP answer). answeredAt: type: string format: date-time description: >- When the callee first spoke. `connectedAt` set while this stays absent is a phantom answer — the line opened and nobody spoke. endedAt: type: string format: date-time durationSec: type: integer description: >- Talk time, `answeredAt` to `endedAt`. Absent until the call ends, and on calls that never got an `answeredAt`. failureReason: type: string enum: - wrong_number - busy - declined - no_answer - unreachable - voicemail - silent_pickup - network_error - call_failed description: >- Why the call failed, on `state: failed`. The confusable ones: `no_answer` rang out, `unreachable` never rang (phone off), `silent_pickup` was answered but carried no callee audio, and `network_error` is a carrier or trunk fault rather than anything the callee did. failureReasonWithCode: type: string description: >- `failureReason` with the carrier's SIP code appended when there is one, as in `busy:486`. example: busy:486 adhoc: type: boolean description: The session ran on an inline config rather than a stored assistant. public: type: boolean description: The session was opened without an API key. audioUrl: type: string format: uri description: >- Recording link, valid one hour. Only when requested with `include_audio_url`. assistantVersion: type: integer description: >- The assistant version this session ran. Absent on sessions from before versions. assistantAlias: type: string enum: - prod - draft description: >- The alias the session was launched on. Absent when it was launched by an exact version number, and on sessions from before versions. summary: allOf: - $ref: '#/components/schemas/ConversationSummary' description: >- On list rows only, with `include_summary=true`. Absent, not null, when there is none. ConversationSummary: type: object description: >- Call summary: how it went, in a headline and a few bullets, plus the facts that came up. In English. Not available for adhoc sessions. properties: headline: type: string description: One sentence, end state first. example: >- Farmer agreed to try one bottle of Cruiser on the next corn crop and asked for an expert callback. bullets: type: array description: Usually three to five, in call order. Events, not values. items: type: string example: - >- Agent confirmed the farmer and introduced Cruiser seed treatment for corn - Farmer agreed to try one bottle on the next sowing - >- Farmer asked about rice pollination temperature and wanted an expert to call facts: type: array description: >- One per distinct fact, in display order. The first is the person's Decision or the Next Step when one exists. items: $ref: '#/components/schemas/ConversationSummaryFact' language: type: string enum: - en promptVersion: type: string example: call-summary-v1 model: type: string description: The model that wrote it. example: gpt-5.4-2026-03-05 generatedAt: type: string format: date-time required: - headline - bullets - facts - language - promptVersion - model - generatedAt ConversationSummaryFact: type: object properties: label: type: string description: >- One to three words, Title Case, e.g. `Decision`, `Delivery Address`, `Complaint Ref`. example: Decision value: type: string description: Up to fifteen words, English, Latin script. example: Will try one bottle on the next corn crop required: - label - value responses: Unauthorized: description: A bearer key was sent but is not recognized. content: application/json: schema: $ref: '#/components/schemas/Error' example: message: invalid authorization error: Unauthorized statusCode: 401 Forbidden: description: No API key sent, or the key lacks permission for this resource. content: application/json: schema: $ref: '#/components/schemas/Error' example: message: Forbidden resource error: Forbidden statusCode: 403 NotFound: description: No such resource in the API key's project. content: application/json: schema: $ref: '#/components/schemas/Error' example: message: 'Realtime assistant not found: 00000000-0000-4000-8000-000000000000' error: Not Found statusCode: 404 securitySchemes: apiKey: type: http scheme: bearer description: Project API key (`sk_api_…`). ````