# Realtime

Neon Realtime streams live query results to your application: a client subscribes to a SQL query and receives the current rows, then each transaction's changes. Each branch gets its own endpoint, returned as `invocation_url`, and a new branch inherits its parent's Realtime settings.

Neon Realtime is coming soon and isn't available yet. These endpoints are documented ahead of launch.

Changes return `202` and finish in the background, so poll the state endpoint until `pending` is `false`. `allowed_origins` limits which browser origins can connect, not server clients. An empty list or `*` allows any origin, omitting it keeps the current value, and a new list can take about a minute to apply.

Your backend issues Realtime tokens with the branch's shared secret, so keep it server-side. After a rotation, the previous secret keeps working until `pending` is `false`.

You can also manage Realtime with [`neon realtime`](/docs/cli/realtime), stream a query with [`neon realtime subscribe`](/docs/cli/realtime#subscribe), or declare it in `neon.ts` with [`preview.realtime`](/docs/reference/neon-ts#realtime).

---

> API Reference / Realtime / Disable Realtime

## DELETE /projects/{project_id}/branches/{branch_id}/realtime

Disables Realtime for the branch and discards its shared secret. Deprovisioning is asynchronous.

### Parameters

- `project_id` (string, path, required)
  The project ID
- `branch_id` (string, path, required)
  The branch ID

### Code examples

```bash
curl "https://console.neon.tech/api/v2/projects/$PROJECT_ID/branches/$BRANCH_ID/realtime" \
  -X DELETE \
  -H "Authorization: Bearer $NEON_API_KEY"
```

```typescript
import { createNeonClient, raw } from '@neon/sdk';

const neon = createNeonClient({ apiKey: process.env.NEON_API_KEY });
const { data } = await raw.disableProjectBranchRealtime({
  client: neon.client,
  path: {
    project_id: process.env.PROJECT_ID,
    branch_id: process.env.BRANCH_ID
  }
});
```

### Errors

**default**
General Error.

The request may or may not be safe to retry, depending on the HTTP method, response status code,
and whether a response was received.

- If no response is returned from the API, a network error or timeout likely occurred.
- In some cases, the request may have reached the server and been successfully processed, but the response failed to reach the client. As a result, retrying non-idempotent requests can lead to unintended results.

The following HTTP methods are considered non-idempotent: `POST`, `PATCH`, `DELETE`, and `PUT`. Retrying these methods is generally **not safe**.
The following methods are considered idempotent: `GET`, `HEAD`, and `OPTIONS`. Retrying these methods is **safe** in the event of a network error or timeout.

Any request that returns a `503 Service Unavailable` response is always safe to retry.

Any request that returns a `423 Locked` response is safe to retry. `423 Locked` indicates that the resource is temporarily locked, for example, due to another operation in progress.

- `request_id` (string, optional)
  Unique identifier for the request, useful for debugging.
  You can set this value manually by including an `X-Request-ID` header in the request. If not provided, the value will be generated automatically.
  
- `code` (string, required)
  Machine-readable code classifying the error type. See `message` for a human-readable explanation.
  Default: ``
- `message` (string, required)
  Error message

---

> API Reference / Realtime / Enable Realtime

## POST /projects/{project_id}/branches/{branch_id}/realtime

Enables Realtime for the branch, or applies new options to an enabled branch. Provisioning is
asynchronous; poll the Realtime state until it is no longer pending.


### Parameters

- `project_id` (string, path, required)
  The project ID
- `branch_id` (string, path, required)
  The branch ID

### Request body

- `allowed_origins` (array, optional)
  The browser origins allowed to connect, each `http` or `https` with a host and optional port
  and no path. An empty list, or `*` alone, allows any origin. Omitted keeps the current or
  inherited value.
  

### Code examples

```bash
curl "https://console.neon.tech/api/v2/projects/$PROJECT_ID/branches/$BRANCH_ID/realtime" \
  -X POST \
  -H "Authorization: Bearer $NEON_API_KEY"
```

```typescript
import { createNeonClient, raw } from '@neon/sdk';

const neon = createNeonClient({ apiKey: process.env.NEON_API_KEY });
const { data } = await raw.enableProjectBranchRealtime({
  client: neon.client,
  path: {
    project_id: process.env.PROJECT_ID,
    branch_id: process.env.BRANCH_ID
  }
});
```

### Errors

**default**
General Error.

The request may or may not be safe to retry, depending on the HTTP method, response status code,
and whether a response was received.

- If no response is returned from the API, a network error or timeout likely occurred.
- In some cases, the request may have reached the server and been successfully processed, but the response failed to reach the client. As a result, retrying non-idempotent requests can lead to unintended results.

The following HTTP methods are considered non-idempotent: `POST`, `PATCH`, `DELETE`, and `PUT`. Retrying these methods is generally **not safe**.
The following methods are considered idempotent: `GET`, `HEAD`, and `OPTIONS`. Retrying these methods is **safe** in the event of a network error or timeout.

Any request that returns a `503 Service Unavailable` response is always safe to retry.

Any request that returns a `423 Locked` response is safe to retry. `423 Locked` indicates that the resource is temporarily locked, for example, due to another operation in progress.

- `request_id` (string, optional)
  Unique identifier for the request, useful for debugging.
  You can set this value manually by including an `X-Request-ID` header in the request. If not provided, the value will be generated automatically.
  
- `code` (string, required)
  Machine-readable code classifying the error type. See `message` for a human-readable explanation.
  Default: ``
- `message` (string, required)
  Error message

---

> API Reference / Realtime / Retrieve Realtime state

## GET /projects/{project_id}/branches/{branch_id}/realtime

Retrieves whether Realtime is enabled for the branch, whether a change is still being applied,
and, once provisioned, its invocation URL and allowed origins. The shared secret is returned by
`GET /projects/{project_id}/branches/{branch_id}/realtime/secret`.


### Parameters

- `project_id` (string, path, required)
  The project ID
- `branch_id` (string, path, required)
  The branch ID

### Response (200)

- `enabled` (boolean, optional)
  Whether Realtime is enabled for the branch.
- `pending` (boolean, optional)
  Whether a provisioning, settings, rotation or deprovisioning change is still being applied.
- `invocation_url` (string, optional)
- `revision` (integer, optional, format: int32)
- `allowed_origins` (array, optional)

### Code examples

```bash
curl "https://console.neon.tech/api/v2/projects/$PROJECT_ID/branches/$BRANCH_ID/realtime" \
  -H "Authorization: Bearer $NEON_API_KEY"
```

```typescript
import { createNeonClient, raw } from '@neon/sdk';

const neon = createNeonClient({ apiKey: process.env.NEON_API_KEY });
const { data } = await raw.getProjectBranchRealtime({
  client: neon.client,
  path: {
    project_id: process.env.PROJECT_ID,
    branch_id: process.env.BRANCH_ID
  }
});
```

### Errors

**default**
General Error.

The request may or may not be safe to retry, depending on the HTTP method, response status code,
and whether a response was received.

- If no response is returned from the API, a network error or timeout likely occurred.
- In some cases, the request may have reached the server and been successfully processed, but the response failed to reach the client. As a result, retrying non-idempotent requests can lead to unintended results.

The following HTTP methods are considered non-idempotent: `POST`, `PATCH`, `DELETE`, and `PUT`. Retrying these methods is generally **not safe**.
The following methods are considered idempotent: `GET`, `HEAD`, and `OPTIONS`. Retrying these methods is **safe** in the event of a network error or timeout.

Any request that returns a `503 Service Unavailable` response is always safe to retry.

Any request that returns a `423 Locked` response is safe to retry. `423 Locked` indicates that the resource is temporarily locked, for example, due to another operation in progress.

- `request_id` (string, optional)
  Unique identifier for the request, useful for debugging.
  You can set this value manually by including an `X-Request-ID` header in the request. If not provided, the value will be generated automatically.
  
- `code` (string, required)
  Machine-readable code classifying the error type. See `message` for a human-readable explanation.
  Default: ``
- `message` (string, required)
  Error message

---

> API Reference / Realtime / Retrieve the Realtime shared secret

## GET /projects/{project_id}/branches/{branch_id}/realtime/secret

Retrieves the secret the application backend issues Realtime tokens with. Requires permission to
read the project's credentials. Returns 404 while Realtime is disabled or before the secret is
provisioned. After a rotation, this returns the previous secret until `pending` is false.


### Parameters

- `project_id` (string, path, required)
  The project ID
- `branch_id` (string, path, required)
  The branch ID

### Response (200)

- `secret` (string, optional)
  The key the application backend issues Realtime tokens with, `nrt_live_1` followed by the unpadded base64url 32-byte AES-256-GCM key.
- `pending` (boolean, optional)
  Whether a change is still being applied. After a rotation, the secret changes when this becomes false.

### Code examples

```bash
curl "https://console.neon.tech/api/v2/projects/$PROJECT_ID/branches/$BRANCH_ID/realtime/secret" \
  -H "Authorization: Bearer $NEON_API_KEY"
```

```typescript
import { createNeonClient, raw } from '@neon/sdk';

const neon = createNeonClient({ apiKey: process.env.NEON_API_KEY });
const { data } = await raw.getProjectBranchRealtimeSecret({
  client: neon.client,
  path: {
    project_id: process.env.PROJECT_ID,
    branch_id: process.env.BRANCH_ID
  }
});
```

### Errors

**default**
General Error.

The request may or may not be safe to retry, depending on the HTTP method, response status code,
and whether a response was received.

- If no response is returned from the API, a network error or timeout likely occurred.
- In some cases, the request may have reached the server and been successfully processed, but the response failed to reach the client. As a result, retrying non-idempotent requests can lead to unintended results.

The following HTTP methods are considered non-idempotent: `POST`, `PATCH`, `DELETE`, and `PUT`. Retrying these methods is generally **not safe**.
The following methods are considered idempotent: `GET`, `HEAD`, and `OPTIONS`. Retrying these methods is **safe** in the event of a network error or timeout.

Any request that returns a `503 Service Unavailable` response is always safe to retry.

Any request that returns a `423 Locked` response is safe to retry. `423 Locked` indicates that the resource is temporarily locked, for example, due to another operation in progress.

- `request_id` (string, optional)
  Unique identifier for the request, useful for debugging.
  You can set this value manually by including an `X-Request-ID` header in the request. If not provided, the value will be generated automatically.
  
- `code` (string, required)
  Machine-readable code classifying the error type. See `message` for a human-readable explanation.
  Default: ``
- `message` (string, required)
  Error message

---

> API Reference / Realtime / Rotate the Realtime shared secret

## POST /projects/{project_id}/branches/{branch_id}/realtime/rotate_secret

Replaces the branch's Realtime shared secret. Rotation is asynchronous: once the Realtime state is
no longer pending, the previous secret stops working and
`GET /projects/{project_id}/branches/{branch_id}/realtime/secret` returns the new one.


### Parameters

- `project_id` (string, path, required)
  The project ID
- `branch_id` (string, path, required)
  The branch ID

### Code examples

```bash
curl "https://console.neon.tech/api/v2/projects/$PROJECT_ID/branches/$BRANCH_ID/realtime/rotate_secret" \
  -X POST \
  -H "Authorization: Bearer $NEON_API_KEY"
```

```typescript
import { createNeonClient, raw } from '@neon/sdk';

const neon = createNeonClient({ apiKey: process.env.NEON_API_KEY });
const { data } = await raw.rotateProjectBranchRealtimeSecret({
  client: neon.client,
  path: {
    project_id: process.env.PROJECT_ID,
    branch_id: process.env.BRANCH_ID
  }
});
```

### Errors

**default**
General Error.

The request may or may not be safe to retry, depending on the HTTP method, response status code,
and whether a response was received.

- If no response is returned from the API, a network error or timeout likely occurred.
- In some cases, the request may have reached the server and been successfully processed, but the response failed to reach the client. As a result, retrying non-idempotent requests can lead to unintended results.

The following HTTP methods are considered non-idempotent: `POST`, `PATCH`, `DELETE`, and `PUT`. Retrying these methods is generally **not safe**.
The following methods are considered idempotent: `GET`, `HEAD`, and `OPTIONS`. Retrying these methods is **safe** in the event of a network error or timeout.

Any request that returns a `503 Service Unavailable` response is always safe to retry.

Any request that returns a `423 Locked` response is safe to retry. `423 Locked` indicates that the resource is temporarily locked, for example, due to another operation in progress.

- `request_id` (string, optional)
  Unique identifier for the request, useful for debugging.
  You can set this value manually by including an `X-Request-ID` header in the request. If not provided, the value will be generated automatically.
  
- `code` (string, required)
  Machine-readable code classifying the error type. See `message` for a human-readable explanation.
  Default: ``
- `message` (string, required)
  Error message