Get a session's status

curl --request GET \
  --url https://api.upliftai.org/v1/realtime-assistants/sessions/{sessionId} \
  --header 'Authorization: Bearer <token>'

import requests

url = "https://api.upliftai.org/v1/realtime-assistants/sessions/{sessionId}"

headers = {"Authorization": "Bearer <token>"}

response = requests.get(url, headers=headers)

print(response.text)

const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};

fetch('https://api.upliftai.org/v1/realtime-assistants/sessions/{sessionId}', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.upliftai.org/v1/realtime-assistants/sessions/{sessionId}",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://api.upliftai.org/v1/realtime-assistants/sessions/{sessionId}"

	req, _ := http.NewRequest("GET", url, nil)

	req.Header.Add("Authorization", "Bearer <token>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

require 'uri'
require 'net/http'

url = URI("https://api.upliftai.org/v1/realtime-assistants/sessions/{sessionId}")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)
request["Authorization"] = 'Bearer <token>'

response = http.request(request)
puts response.read_body

{
  "sessionId": "session_MjU2NjEzNTIteHh4eC14eHh4LXh4eHgteHh4eHh4eHh4eHh4",
  "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": "+924232591000",
  "roomName": "call-25661352-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "participantIdentity": "callee-25661352",
  "transportProvider": "twilio",
  "variables": {
    "patientName": "عائشہ صدیقی",
    "appointmentTime": "کل صبح 11 بجے"
  },
  "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
}

GET

realtime-assistants

sessions

{sessionId}

Get a session's status

curl --request GET \
  --url https://api.upliftai.org/v1/realtime-assistants/sessions/{sessionId} \
  --header 'Authorization: Bearer <token>'

import requests

url = "https://api.upliftai.org/v1/realtime-assistants/sessions/{sessionId}"

headers = {"Authorization": "Bearer <token>"}

response = requests.get(url, headers=headers)

print(response.text)

const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};

fetch('https://api.upliftai.org/v1/realtime-assistants/sessions/{sessionId}', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.upliftai.org/v1/realtime-assistants/sessions/{sessionId}",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://api.upliftai.org/v1/realtime-assistants/sessions/{sessionId}"

	req, _ := http.NewRequest("GET", url, nil)

	req.Header.Add("Authorization", "Bearer <token>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

require 'uri'
require 'net/http'

url = URI("https://api.upliftai.org/v1/realtime-assistants/sessions/{sessionId}")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)
request["Authorization"] = 'Bearer <token>'

response = http.request(request)
puts response.read_body

{
  "sessionId": "session_MjU2NjEzNTIteHh4eC14eHh4LXh4eHgteHh4eHh4eHh4eHh4",
  "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": "+924232591000",
  "roomName": "call-25661352-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "participantIdentity": "callee-25661352",
  "transportProvider": "twilio",
  "variables": {
    "patientName": "عائشہ صدیقی",
    "appointmentTime": "کل صبح 11 بجے"
  },
  "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
}

Authorizations

Authorization

string

header

required

Project API key (sk_api_…).

Path Parameters

sessionId

string

required

The callId from the call dispatch, a sessionId from the sessions list, or a callId from a campaign's calls list or a webhook.

Query Parameters

include_audio_url

boolean

Adds audioUrl, a recording link valid for one hour. Any value switches it on, including false, so omit the parameter instead. The link is signed without checking a recording exists, so it 404s on calls that were never recorded.

Response

The session as it stands right now.

One conversation — a browser session or a phone call.

sessionId

string

The session id.

realtimeAssistantId

string<uuid>

The assistant that ran the session. Still returned after that assistant is deleted.

organizationId

string<uuid>

projectId

string<uuid>

channel

enum<string>

Available options:

web,

telephony,

whatsapp

direction

enum<string>

Browser sessions are inbound by convention — the user opens them.

Available options:

inbound,

outbound

state

enum<string>

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.

Available options:

created,

dispatched,

dialing,

ringing,

answered,

active,

completed,

failed

connected

boolean

Whether audio was ever bridged — false for everything up to and including ringing.

outcome

enum<string>

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.

Available options:

busy,

no_answer,

unreachable,

voicemail,

silent_pickup,

failed

endedBy

enum<string>

Who hung up.

Available options:

callee,

agent,

supervisor,

system

toNumber

string

E.164. Telephony only.

Example:

"+923001234567"

fromNumber

string

E.164 caller id the callee saw. Telephony only.

Example:

"+924232591000"

calleeName

string

Display name of the person called, stamped at dial time from the campaign contact.

roomName

string

Server-generated, {prefix}-{sessionId}.

participantIdentity

string

Identifies the human on the call: the token identity for a browser session, the SIP participant for a phone call.

transportProvider

string

Carrier that placed the call, e.g. twilio.

Example:

"twilio"

variables

object

The values you supplied when the session was created, returned verbatim.

campaignId

string<uuid>

Set on calls a campaign dialed.

runId

string<uuid>

The campaign run that dialed this call.

contactId

string

The campaign contact that was dialed.

createdAt

string<date-time>

When the record was created — for an outbound call, when it was dispatched, not when it rang.

dialingAt

string<date-time>

Carrier accepted the dial request. Reported by the carrier, so it can be absent even on a call that connected.

ringingAt

string<date-time>

Callee's phone started ringing. Same carrier caveat as dialingAt.

connectedAt

string<date-time>

Audio bridged (SIP answer).

answeredAt

string<date-time>

When the callee first spoke. connectedAt set while this stays absent is a phantom answer — the line opened and nobody spoke.

endedAt

string<date-time>

durationSec

integer

Talk time, answeredAt to endedAt. Absent until the call ends, and on calls that never got an answeredAt.

failureReason

enum<string>

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.

Available options:

wrong_number,

busy,

declined,

no_answer,

unreachable,

voicemail,

silent_pickup,

network_error,

call_failed

failureReasonWithCode

string

failureReason with the carrier's SIP code appended when there is one, as in busy:486.

Example:

"busy:486"

adhoc

boolean

The session ran on an inline config rather than a stored assistant.

public

boolean

The session was opened without an API key.

audioUrl

string<uri>

Recording link, valid one hour. Only when requested with include_audio_url.

assistantVersion

integer

The assistant version this session ran. Absent on sessions from before versions.

assistantAlias

enum<string>

The alias the session was launched on. Absent when it was launched by an exact version number, and on sessions from before versions.

Available options:

prod,

draft

summary

object

On list rows only, with include_summary=true. Absent, not null, when there is none.

Show child attributes

Getting started

Concepts

Assistants

Tools

Personalization

Calling

Campaigns

Webhooks

Testing

API Reference

Get a session's status

Authorizations

Path Parameters

Query Parameters

Response