Sessions

A session is one ongoing conversation between an agent and one contact on one channel: a customer in your Telegram group, a colleague in Slack, a caller on WhatsApp. The project’s runtime keeps every session’s transcript so the agent can carry context from message to message and so you can review what was said.

Sessions belong to a project. Any active member of the project can view them.

What a session shows

Status

The transcript

Opening a session shows every message in order. Each entry has a role and a time:

Seeing tool entries in line with the conversation makes it easy to tell why the agent said something.

Browse sessions

Sessions are listed most recent first and load in pages as you scroll, 25 at a time by default and at most 100 per page. They can be narrowed to one channel.

Watch a session live

Each agent’s page has a Live activity panel that streams what the agent is doing in one session as it happens.

The stream reconnects by itself about once a minute and resumes from the last event it received, so a long session can be watched without gaps.

Sessions and executions

A session is the conversation; an execution is the record of one run that the conversation triggered. A long conversation can produce many runs.

To see every run a conversation caused:

1. Copy the session ID.
2. Open Executions, choose AI Agent runs and paste the ID into Session ID.
3. Select Apply.

Privacy

Session transcripts can contain personal details sent by your contacts. Limit who has access to the project, and do not paste transcripts into public tickets.

Sessions API

The Sessions API lets your code do what a channel does today: open a conversation with an agent, send it messages, follow what it does as it happens, step in when it needs approval, and stop it. The agent runs on Syntic’s side, so your code does not have to host a loop, store history or execute built-in tools.

Use it when an agent should be part of your own product (a web app, a back-office job, a CI step) rather than reached through a messaging channel.

Endpoints

Base URL https://app.syntic.ai/v1 (the paths above already include /v1). Authenticate with a private key (Authorization: Bearer sk_live_...) and send syntic-beta: agents-2026-11-01 while the API is in preview. A key sees only sessions in its own workspace.

Start a session

POST /v1/sessions

Response 201 Created:

{
  "id": "sesn_01JC7M2K4P6R8T0V2X4Z",
  "type": "session",
  "agent_id": "agt_01JC4R8W6Q2N9X3T5V7Y",
  "agent_version": 4,
  "status": "running",
  "channel": "api",
  "title": "Refund for order 88123",
  "usage": { "input_tokens": 0, "cached_input_tokens": 0, "output_tokens": 0, "cost_usd": "0.0000" },
  "outcome": null,
  "created_at": "2026-11-05T10:00:00Z",
  "last_event_at": "2026-11-05T10:00:00Z",
  "metadata": {}
}

outcome is filled in when a turn ends: { "reason": "end_turn" | "max_turns" | "budget_exhausted" | "interrupted" | "error", "message": "..." }.

Send events

POST /v1/sessions/{session_id}/events with { "events": [ ... ] }. Up to 20 events per call.

Response 202 Accepted with the stored events and their ids. Sending a user.tool_result or user.approval for a call that is not waiting gives 409 tool_call_not_pending.

Stream events

GET /v1/sessions/{session_id}/stream returns Content-Type: text/event-stream. Each event has an id: line (the event id) and a data: line with JSON. Reconnect with the Last-Event-ID header to resume without gaps; events are kept for replay for 24 hours. A comment line (: keep-alive) is sent every 15 seconds so proxies do not drop an idle connection. The stream ends when the session is archived; otherwise the server closes it after 10 minutes and you reconnect.

Example stream:

id: evt_01JC7M3A
data: {"type":"status.changed","status":"running","outcome":null}

id: evt_01JC7M3B
data: {"type":"tool_call.started","tool_call_id":"call_7","name":"lookup_order","arguments":{"order_id":"88123"},"executor":"client"}

id: evt_01JC7M3C
data: {"type":"status.changed","status":"requires_action","outcome":null}

# Start a session with a first message
curl -sS https://app.syntic.ai/v1/sessions \
  -H "Authorization: Bearer $SYNTIC_API_KEY" \
  -H "Content-Type: application/json" \
  -H "syntic-beta: agents-2026-11-01" \
  -d '{"agent_id": "agt_01JC4R8W6Q2N9X3T5V7Y",
       "input": [{"type": "user.message", "content": "Please refund order 88123."}]}'
 
# Follow it
curl -sSN https://app.syntic.ai/v1/sessions/sesn_01JC7M2K4P6R8T0V2X4Z/stream \
  -H "Authorization: Bearer $SYNTIC_API_KEY" \
  -H "syntic-beta: agents-2026-11-01"

const base = 'https://app.syntic.ai/v1'
const headers = {
  Authorization: `Bearer ${process.env.SYNTIC_API_KEY}`,
  'Content-Type': 'application/json',
  'syntic-beta': 'agents-2026-11-01',
}
 
const session = await (await fetch(`${base}/sessions`, {
  method: 'POST', headers,
  body: JSON.stringify({
    agent_id: 'agt_01JC4R8W6Q2N9X3T5V7Y',
    input: [{ type: 'user.message', content: 'Please refund order 88123.' }],
  }),
})).json()
 
const stream = await fetch(`${base}/sessions/${session.id}/stream`, { headers })
const reader = stream.body.pipeThrough(new TextDecoderStream()).getReader()
let buf = ''
for (;;) {
  const { value, done } = await reader.read()
  if (done) break
  buf += value
  let cut
  while ((cut = buf.indexOf('\n\n')) >= 0) {
    const block = buf.slice(0, cut); buf = buf.slice(cut + 2)
    const data = block.split('\n').find((l) => l.startsWith('data: '))
    if (!data) continue
    const ev = JSON.parse(data.slice(6))
    if (ev.type === 'tool_call.started' && ev.executor === 'client') {
      const output = await runMyTool(ev.name, ev.arguments)
      await fetch(`${base}/sessions/${session.id}/events`, {
        method: 'POST', headers,
        body: JSON.stringify({ events: [{ type: 'user.tool_result', tool_call_id: ev.tool_call_id, content: JSON.stringify(output) }] }),
      })
    }
    if (ev.type === 'message.completed') console.log(ev.content)
  }
}

import json, os, requests
 
BASE = "https://app.syntic.ai/v1"
H = {"Authorization": f"Bearer {os.environ['SYNTIC_API_KEY']}", "syntic-beta": "agents-2026-11-01"}
 
session = requests.post(f"{BASE}/sessions", headers=H, json={
    "agent_id": "agt_01JC4R8W6Q2N9X3T5V7Y",
    "input": [{"type": "user.message", "content": "Please refund order 88123."}],
}).json()
 
with requests.get(f"{BASE}/sessions/{session['id']}/stream", headers=H, stream=True) as r:
    for line in r.iter_lines(decode_unicode=True):
        if not line or not line.startswith("data: "):
            continue
        ev = json.loads(line[6:])
        if ev["type"] == "tool_call.started" and ev["executor"] == "client":
            output = run_my_tool(ev["name"], ev["arguments"])
            requests.post(f"{BASE}/sessions/{session['id']}/events", headers=H, json={
                "events": [{"type": "user.tool_result", "tool_call_id": ev["tool_call_id"], "content": json.dumps(output)}],
            })
        elif ev["type"] == "message.completed":
            print(ev["content"])

List and read history

GET /v1/sessions takes limit (1 to 100, default 20), after_id, before_id, agent_id, status and channel (api, telegram, slack, whatsapp and so on, so API and channel sessions appear in one list). GET /v1/sessions/{id}/events returns stored events oldest first with the same pagination; message.delta events are not stored, only message.completed.

Errors

Errors use the error envelope.

Limits

Model tokens are billed exactly like chat completions, to the workspace of the key that started the session. Built-in tools add their own line items.

Build notes for the platform team

• Back the API with the existing runtime and the execution store: each turn opens an execution with session_id set, so the Console’s Executions and Live activity views keep working unchanged.
• The event type list above is the contract SDKs will wrap. Add new types only; never rename one.
• Raw upstream error text must never appear in an error event; map it to the envelope first.

Related

• Channels: where sessions come from.
• Executions: run history and traces.
• Tools & skills.
• Agent definitions API
• Stream format