---
title: "Create realtime session"
description: "Open a realtime voice conversation with an agent.\n\nReturns a WebSocket `url` valid for 60 seconds. The long-lived API\nkey never travels on the socket: the session does, and its prefix\n(`rts_{cell}_`) takes it to the workspace's cell.\n"
---

> Documentation Index
> Fetch the complete documentation index at: https://docs.qomni.ai/llms.txt
> Use this file to discover all available pages before exploring further.

Path: Qomni Agents API › Realtime

`POST /realtime/sessions`

Open a realtime voice conversation with an agent.

Returns a WebSocket `url` valid for 60 seconds. The long-lived API
key never travels on the socket: the session does, and its prefix
(`rts_{cell}_`) takes it to the workspace's cell.

## Authentication

- `apiKey`, http, header `Authorization`, format `sk_agents_{live|test}_{cell}_{body}{checksum}`

## Request body

_Optional._

- `instructions` (`createRealtimeSession.instructions`; string, optional) — What the agent should do in this conversation.
  - maxLength 500

## Example request

```json
{
  "instructions": "string"
}
```

## Code samples

### TypeScript

```typescript
import { Qomni } from "@qomni/sdk";

const qomni = new Qomni({ apiKey: process.env.QOMNI_KEY! });

const realtimeSession = await qomni.agents.createRealtimeSession({
  instructions: "<instructions>"
});
console.log(realtimeSession);

```

### cURL

```bash
curl --request POST \
  --url https://api.qomni.ai/agents/v1/realtime/sessions \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "instructions": "string"
}
'
```

### Python

```python
import requests

url = "https://api.qomni.ai/agents/v1/realtime/sessions"

payload = { "instructions": "string" }
headers = {
    "Content-Type": "application/json",
    "Authorization": "Bearer <token>"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)
```

## Responses

### 201

The session.

#### Example

```json
{
  "id": "string",
  "url": "http://example.com",
  "client_secret": "string",
  "expires_at": "2019-08-24T14:15:22Z",
  "max_duration_seconds": 0,
  "livemode": true,
  "cell": "string"
}
```

- `id` (`createRealtimeSession.response.201.id`; string, required)
  - pattern `^rts_[0-9a-z]+$`
- `url` (`createRealtimeSession.response.201.url`; string, required) — Open within 60 s; speaks asyncapi.yaml.
  - format `uri`
- `client_secret` (`createRealtimeSession.response.201.client_secret`; string, required) — The session, for clients that build the URL themselves.
  - pattern `^rts_[a-z]{2}[0-9]+_`
- `expires_at` (`createRealtimeSession.response.201.expires_at`; string, required) — Connect before this instant.
  - format `date-time`
- `max_duration_seconds` (`createRealtimeSession.response.201.max_duration_seconds`; integer, required)
- `livemode` (`createRealtimeSession.response.201.livemode`; boolean, required)
- `cell` (`createRealtimeSession.response.201.cell`; string, required)

### 401

Missing or invalid credentials (`unauthenticated`).

#### Example

```json
{
  "error": {
    "code": "string",
    "message": "string",
    "request_id": "string",
    "fields": {
      "property1": [
        "string"
      ],
      "property2": [
        "string"
      ]
    }
  }
}
```

- `error` (`createRealtimeSession.response.401.error`; object, required)
  - `code` (`createRealtimeSession.response.401.error.code`; string, required) — Stable, machine-readable; each operation lists the codes it can return.
    - pattern `^[a-z][a-z0-9_]*$`
  - `message` (`createRealtimeSession.response.401.error.message`; string, required) — For people; may change at any time.
  - `request_id` (`createRealtimeSession.response.401.error.request_id`; string, optional)
  - `fields` (`createRealtimeSession.response.401.error.fields`; map<array<string>>, optional) — Only for validation_failed, the messages per field.

### 403

Valid credentials that may not do this (`insufficient_scope`, `api_key_wrong_product`…).

#### Example

```json
{
  "error": {
    "code": "string",
    "message": "string",
    "request_id": "string",
    "fields": {
      "property1": [
        "string"
      ],
      "property2": [
        "string"
      ]
    }
  }
}
```

- `error` (`createRealtimeSession.response.403.error`; object, required)
  - `code` (`createRealtimeSession.response.403.error.code`; string, required) — Stable, machine-readable; each operation lists the codes it can return.
    - pattern `^[a-z][a-z0-9_]*$`
  - `message` (`createRealtimeSession.response.403.error.message`; string, required) — For people; may change at any time.
  - `request_id` (`createRealtimeSession.response.403.error.request_id`; string, optional)
  - `fields` (`createRealtimeSession.response.403.error.fields`; map<array<string>>, optional) — Only for validation_failed, the messages per field.

### 422

The request does not match the contract (`validation_failed`).

#### Example

```json
{
  "error": {
    "code": "string",
    "message": "string",
    "request_id": "string",
    "fields": {
      "property1": [
        "string"
      ],
      "property2": [
        "string"
      ]
    }
  }
}
```

- `error` (`createRealtimeSession.response.422.error`; object, required)
  - `code` (`createRealtimeSession.response.422.error.code`; string, required) — Stable, machine-readable; each operation lists the codes it can return.
    - pattern `^[a-z][a-z0-9_]*$`
  - `message` (`createRealtimeSession.response.422.error.message`; string, required) — For people; may change at any time.
  - `request_id` (`createRealtimeSession.response.422.error.request_id`; string, optional)
  - `fields` (`createRealtimeSession.response.422.error.fields`; map<array<string>>, optional) — Only for validation_failed, the messages per field.

### 429

Too many requests for this key (`rate_limited`); retry after `Retry-After` seconds.

#### Example

```json
{
  "error": {
    "code": "string",
    "message": "string",
    "request_id": "string",
    "fields": {
      "property1": [
        "string"
      ],
      "property2": [
        "string"
      ]
    }
  }
}
```

- `error` (`createRealtimeSession.response.429.error`; object, required)
  - `code` (`createRealtimeSession.response.429.error.code`; string, required) — Stable, machine-readable; each operation lists the codes it can return.
    - pattern `^[a-z][a-z0-9_]*$`
  - `message` (`createRealtimeSession.response.429.error.message`; string, required) — For people; may change at any time.
  - `request_id` (`createRealtimeSession.response.429.error.request_id`; string, optional)
  - `fields` (`createRealtimeSession.response.429.error.fields`; map<array<string>>, optional) — Only for validation_failed, the messages per field.


Source: https://docs.qomni.ai/agents-api/create-realtime-session/index.md
