Session channels

Every session has two durable streams: .in carries records from your clients to the task, .out carries records from the task back to your clients. The sessions SDK wraps these as session.in.* and session.out.*. This page documents the underlying HTTP endpoints for callers that aren’t using the TypeScript SDK. All channel endpoints live under /realtime/v1/sessions/{session}/{io}, where:

{session} is the session’s friendly ID (session_…) or your externalId. One token authorizes both forms.
{io} is either in or out.

Authorize requests with a secret key or a session public token. The token’s scopes decide what you can do — see Authorization below.

Append a record

Append a single record to a channel.

Append to .in

curl -X POST "https://api.trigger.dev/realtime/v1/sessions/{session}/in/append" \
  -H "Authorization: Bearer $TRIGGER_TOKEN" \
  -H "Content-Type: application/json" \
  -H "X-Part-Id: 0f8c2b1e-..." \
  --data '{"type":"user-message","text":"hello"}'

The body is the raw record — any text up to 1MiB (records over the per-record cap return 413). The response is { "ok": true }. Set the X-Part-Id header to a unique value per record to make the append idempotent: replaying the same X-Part-Id does not duplicate the record. Appending to a closed or expired session returns 400.

Appending to .out requires a secret key. A session public token (even one with write:sessions) can only append to .in — appending to .out with a public token returns 403. The .out stream is the task’s to write.

Read a channel over SSE

Subscribe to a channel as a Server-Sent Events stream. New records are delivered as they arrive.

Read .out

curl -N "https://api.trigger.dev/realtime/v1/sessions/{session}/out" \
  -H "Authorization: Bearer $TRIGGER_TOKEN" \
  -H "Last-Event-ID: 42" \
  -H "Timeout-Seconds: 60"

Header	Direction	Description
`Last-Event-ID`	request	Resume after this sequence number. Set it to the last `id:` you received to pick up exactly where you left off after a disconnect.
`Timeout-Seconds`	request	How long the server holds the stream open with no new records before closing, `1`–`600`.

Each SSE event carries:

id: — the record’s sequence number. Use the most recent one as Last-Event-ID to resume.
data: — a JSON record { "data": <record>, "id": <id> }. For .out on a chat.agent session, data is a UI message chunk (text, reasoning, tool call, or a custom data part).

id: 42
data: {"data":{"type":"text","text":"echo: hello"},"id":42}

Control records

Some .out events are control records rather than data. A control record has an empty body and carries a trigger-control header naming its subtype:

Subtype	Meaning
`turn-complete`	The current turn finished. Carries sibling headers `public-access-token` (a refreshed session token), `session-in-event-id`, and `last-event-id`.
`upgrade-required`	The session needs to hand off to a run on a newer deployed version.

Route control records by their subtype instead of treating them as message content. The TypeScript SDK does this for you — session.out.read filters control records out of the chunk stream and surfaces them through onControl.

Drain records non-streaming

Fetch a batch of records without holding an SSE connection open. Useful for polling or for reading a tail at startup.

Drain .out

curl "https://api.trigger.dev/realtime/v1/sessions/{session}/out/records?afterEventId=42" \
  -H "Authorization: Bearer $TRIGGER_TOKEN"

Pass afterEventId to return only records after that sequence number; omit it to read from the start of the retained window. The response is:

{
  "records": [
    { "data": { "type": "text", "text": "echo: hello" }, "id": 43, "seqNum": 43 }
  ]
}

Each record carries data, id, seqNum, and an optional headers array (present on control records). Page forward by passing the highest seqNum you received as the next afterEventId.

Authorization

The action you can take depends on your token and the channel:

Action	Endpoint	Required authorization
Subscribe (SSE)	`GET .../{io}`	`read:sessions:{id}` — works on both `.in` and `.out`
Drain records	`GET .../{io}/records`	`read:sessions:{id}` — works on both `.in` and `.out`
Append to `.in`	`POST .../in/append`	`write:sessions:{id}`
Append to `.out`	`POST .../out/append`	Secret key only

Reads work in both directions for a read:sessions token. Writes split by direction: a write:sessions token can append to .in, but .out is reserved for the task and requires a secret key. See session scopes for how to mint a token.

Using the SDK instead

If you’re writing TypeScript, the sessions SDK is the ergonomic path. sessions.open(idOrExternalId) returns a SessionHandle whose session.in and session.out channels call these endpoints for you, with auto-retry, Last-Event-ID resume, and control-record routing built in:

Your backend

import { sessions } from "@trigger.dev/sdk";

const session = sessions.open(chatId);

// append to .in
await session.in.send({ type: "user-message", text: "hello" });

// read .out over SSE
const stream = await session.out.read({ signal: AbortSignal.timeout(30_000) });
for await (const chunk of stream) {
  console.log(chunk);
}

See session.in and session.out for the full handle API.

API reference

Tasks API

Batches API

Runs API

Bulk actions API

Errors API

Queues API

Schedules API

Env Vars API

Deployments API

Waitpoints API

Sessions API

Query API

Append a record

Read a channel over SSE

Control records

Drain records non-streaming

Authorization

Using the SDK instead

Documentation Index

​Append a record

​Read a channel over SSE

​Control records

​Drain records non-streaming

​Authorization

​Using the SDK instead

Append a record

Read a channel over SSE

Control records

Drain records non-streaming

Authorization

Using the SDK instead