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 two 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 |
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
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. |
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. For failed sessions, closeReason may indicate the cause. |
closeReason | Why the session ended (e.g. idle_timeout). Present once the session is closed. |
createdAt / startedAt / closedAt | Unix timestamps for when the session was created, connected, and ended. |
functionMetrics | Connection metrics for the session's WebSocket-based tools. See Tool connection metrics below. |
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 metrics
When a session uses WebSocket-based tools, the platform opens a socket to each tool's server at session start. functionMetrics records that connection's lifecycle per tool — use it to answer "did my tool connect, when, and why not":
{
"id": "sess_abc123",
"functionMetrics": [
{
"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 functionMetrics. To control what happens to the session when a tool connects slowly or fails, see the tool's connectionBehavior setting.
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.