Sessions

List sessions, filter by companion or client, and retrieve conversation transcripts

Every connection creates a session. A session captures the full configuration — which companion, tools, knowledge, and FAQs were attached — along with timing data, cost, and the complete conversation transcript between the user and the agent.

The Sessions API gives you three endpoints:

Endpoint	What you get
`GET /public/sessions`	A paginated list of sessions with filters for companion, client, tags, and free-text search
`GET /public/sessions/{sessionId}`	Full session details including configuration, timing, and the complete conversation transcript
`DELETE /public/sessions/{sessionId}`	Permanently deletes a finished session, its transcript, and the memory stored from it

Getting the session ID

Where the session ID comes from

Listing sessions

Paginated session list with filters

Retrieving a session

Full session details with the transcript

Session fields

What each session record includes

Session cost

The billed cost of a session in USD

Deleting a session

Permanently remove a session and its data

API reference

Full schemas for the session endpoints

Getting the session ID

When you create a session from your Omniagent, the response includes a connection.id. This is the session ID you use to query session data later.

curl -X POST https://companion-api.napster.com/public/agents/agent_abc123/connections \
  -H "X-Api-Key: $NAPSTER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "channelType": "webrtc"
  }'

Response:

{
  "token": "eyJhbGci...",
  "connection": {
    "id": "sess_abc123"
  }
}

Store the connection.id on your backend. You need it to retrieve session details and transcripts.

Listing sessions

Retrieve a paginated list of sessions across your project:

curl https://companion-api.napster.com/public/sessions?pageSize=10 \
  -H "X-Api-Key: $NAPSTER_API_KEY"

Response:

{
  "items": [
    {
      "id": "sess_abc123",
      "companionId": "comp_abc123",
      "companion": {
        "id": "comp_abc123",
        "firstName": "Alex",
        "lastName": "Chen"
      },
      "functions": ["fn_def456"],
      "knowledgeBaseId": "kb_abc123",
      "knowledgeBase": {
        "id": "kb_abc123",
        "name": "Product Docs"
      },
      "faqIds": ["faq_abc123"],
      "faqCollections": [
        {
          "id": "faq_abc123",
          "name": "Support FAQs"
        }
      ],
      "externalClientId": "user_12345",
      "tags": {
        "environment": "production",
        "channel": "web"
      },
      "sessionType": "webrtc",
      "modality": "audio",
      "status": "closed",
      "closeReason": "idle_timeout",
      "agent": {
        "id": "agent_abc123",
        "name": "Support Agent"
      },
      "cost": 0.42,
      "createdAt": 1710000000,
      "startedAt": 1710000005,
      "closedAt": 1710000300
    }
  ],
  "filteredCount": 1,
  "totalCount": 42,
  "pageIndex": 0,
  "pageSize": 10
}

Filtering

Use query parameters to narrow results:

Parameter	Type	Description
`companionId`	string	Filter by companion
`externalClientId`	string	Filter by your external user or client identifier
`search`	string	Free-text search across sessions
`tags`	string	Filter by tag key-value pairs
`pageIndex`	integer	Page number (zero-based)
`pageSize`	integer	Number of results per page

curl "https://companion-api.napster.com/public/sessions?companionId=comp_abc123&pageSize=20" \
  -H "X-Api-Key: $NAPSTER_API_KEY"

Retrieving a session

Get the full details of a session, including the conversation transcript:

curl https://companion-api.napster.com/public/sessions/sess_abc123 \
  -H "X-Api-Key: $NAPSTER_API_KEY"

Response:

{
  "id": "sess_abc123",
  "companionId": "comp_abc123",
  "companion": {
    "id": "comp_abc123",
    "firstName": "Alex",
    "lastName": "Chen"
  },
  "functions": ["fn_def456"],
  "knowledgeBaseId": "kb_abc123",
  "knowledgeBase": {
    "id": "kb_abc123",
    "name": "Product Docs"
  },
  "faqIds": ["faq_abc123"],
  "faqCollections": [
    {
      "id": "faq_abc123",
      "name": "Support FAQs"
    }
  ],
  "externalClientId": "user_12345",
  "tags": {
    "environment": "production"
  },
  "sessionType": "webrtc",
  "modality": "audio",
  "status": "closed",
  "closeReason": "idle_timeout",
  "agent": {
    "id": "agent_abc123",
    "name": "Support Agent"
  },
  "cost": 0.42,
  "createdAt": 1710000000,
  "startedAt": 1710000005,
  "closedAt": 1710000300,
  "conversation": {
    "items": [
      {
        "role": "agent",
        "text": "Hi there! How can I help you today?",
        "timestamp": 1710000006
      },
      {
        "role": "user",
        "text": "I'd like to check the status of my order.",
        "timestamp": 1710000010
      },
      {
        "role": "agent",
        "text": "Let me look that up for you. Your order #ORD-7890 shipped yesterday and is expected to arrive by Friday.",
        "timestamp": 1710000015
      }
    ]
  }
}

The conversation.items array contains each message in chronological order. Each item includes:

Field	Description
`role`	Who sent the message (`agent` or `user`)
`text`	The message content
`timestamp`	Unix timestamp of the message

Session fields

Beyond the transcript, each session record includes:

Field	Description
`agent`	The Omniagent that served the session, as `{ id, name }`. `null` for per-session connections created without an agent.
`cost`	The billed cost of the session, in USD. See Session cost below.
`sessionType`	The channel the session ran on: `webrtc`, `websocket`, `voip`, `sip`, or `kiosk`.
`modality`	The interaction mode the session ran in: `audio`, `text`, or `video`.
`mode`	How the agent spoke: `conversation` or `puppeteer`. See Mode.
`status`	Session state: `pending`, `started`, `closed`, or `failed`. A session moves from `pending` to `started`, then `closed` — or straight to `failed` if the connection is never established. Failed sessions appear in the session list like any other; use this field to separate them.
`closeReason`	Why the session ended. Present once the session is `closed` or `failed`. See Close reasons below.
`direction`	For SIP calls: `inbound` if someone called your agent, `outbound` if your agent placed the call.
`sipConnection`	For SIP calls: the SIP Connection the call went through, as `{ id, name }`.
`createdAt` / `startedAt` / `closedAt`	Unix timestamps for when the session was created, connected, and ended.
`functionStates`	Connection state for each of the session's WebSocket-based tools. Returned only by `GET /public/sessions/{sessionId}`, not on list items. See Tool connection states below.

Close reasons

A session that ends before it starts has a status of failed; otherwise it's closed. Either way, closeReason says why:

`closeReason`	Meaning
`connection_closed`	The connection ended — the user closed the page or hung up, or the network dropped.
`idle_timeout`	The session was idle for too long. See Idle timeout.
`connection_aborted`	Your backend ended the session.
`connection_timeout`	The client didn't connect in time after the session was created.
`not_started`	The session was created, but no client ever connected.
`session_expired`	The AI provider's maximum session length was reached.
`no_credits_left`	Your organization ran out of credits.
`provider_connection_aborted`	The AI provider rejected the session's configuration. See `provider_connection_aborted`.
`function_connection_failed`	A WebSocket tool set to `abortOnFailure: true` couldn't connect.
`function_connection_lost`	A WebSocket tool set to `abortOnFailure: true` lost its connection during the session.
`avatar_allocation_failed`	The avatar couldn't be started.
`initialization_failed` / `session_initialization_failed`	The session couldn't be set up after the client connected (WebRTC / WebSocket).
`application_shutdown`	The server handling the session shut down.
`no_answer`	An outbound SIP call wasn't answered.
`rejected`	An outbound SIP call was declined, or the line was busy.
`failed`	An outbound SIP call couldn't be placed.
`unknown`	The session stopped reporting and was closed without a reason.

Session cost

The cost field reports the billed cost of the session in USD, calculated from the minutes the agent was active and your API key's model configuration. Use it to attribute spend per session, per companion, or per end user.

{
  "id": "sess_abc123",
  "sessionType": "webrtc",
  "status": "closed",
  "cost": 0.42,
  "closedAt": 1710000300
}

cost is null while a session is still pending or started — it is populated once the session closes and billing is finalized. To total spend across many sessions, list sessions and sum cost across the returned items, filtering by companionId or externalClientId as needed.

Tool connection states

When a session uses WebSocket-based tools, the platform opens a socket to each tool's server at session start. functionStates records that connection's lifecycle per tool — use it to answer "did my tool connect, when, and why not". It's returned by GET /public/sessions/{sessionId} as one flat array covering every tool in the session:

{
  "id": "sess_abc123",
  "functionStates": [
    {
      "name": "get_order_status",
      "state": "connected",
      "startedAt": "2026-08-14T10:15:02Z",
      "connectedAt": "2026-08-14T10:15:03Z"
    },
    {
      "name": "check_inventory",
      "state": "failed",
      "startedAt": "2026-08-14T10:15:02Z",
      "failedAt": "2026-08-14T10:15:07Z",
      "error": {
        "code": "connection_failed",
        "message": "WebSocket handshake timed out"
      }
    }
  ]
}

Field	Description
`name`	The tool's name.
`state`	The connection's current state.
`startedAt`	When the platform began connecting to the tool's server (ISO 8601).
`connectedAt`	When the socket connected successfully.
`failedAt`	When the connection attempt failed. `error` carries the cause as `{ code, message }`.
`canceledAt`	When the connection attempt was abandoned because the session ended first — for example, the user closed the tab before the tool finished connecting.

Only the timestamps that occurred are present. Tools with other execution types (HTTP, implicit) don't hold a session-long connection, so they never appear in functionStates. To control what happens to the session when a tool connects slowly or fails, see the tool's connectionBehavior setting.

This field was previously named functionMetrics and returned an object keyed by function library ID, with an array of tool entries under each ID. If your code reads functionMetrics, switch to functionStates — the entries themselves have the same fields, but they now come in a single array.

Cost is finalized on session close. Poll GET /public/sessions/{sessionId} after a session ends, or read it from the session list, rather than expecting a value mid-session.

Deleting a session

To remove a session permanently — for example, when an end user asks you to delete their data — call DELETE /public/sessions/{sessionId}:

curl -X DELETE https://companion-api.napster.com/public/sessions/sess_abc123 \
  -H "X-Api-Key: $NAPSTER_API_KEY"

The API returns 200 once the session is deleted. Deleting a session also removes its conversation transcript and the memory stored from it, so the agent no longer recalls that conversation in future sessions with the same user.

Deletion is permanent. The session, its transcript, and its memory can't be recovered.

You can only delete sessions that are closed or failed. To end a session that's still running, close it first.

Error	Status	When
`SessionNotFound`	`404`	No session with this ID exists in your project.
`SessionNotClosed`	`400`	The session is still `pending` or `started`.
`SessionDeleteFailed`	`400`	The session couldn't be deleted. Nothing was removed — retry the request.

Sessions

Getting the session ID

Listing sessions

Retrieving a session

Session fields

Session cost

Deleting a session

API reference

Getting the session ID

Listing sessions

Filtering

Retrieving a session

Session fields

Close reasons

Session cost

Tool connection states

Deleting a session

API reference

List sessions

Get a session

On this page