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

# Session events

> Submit input and subscribe to session event streams.

Events are how you talk to a running session. You **post input events** to send messages, tool results, and cancellations, and you **subscribe to output events** to watch progress live. Events are the live view; the stored record is in [items and turns](/reference/sessions). For a walkthrough, see the [streaming guide](/guides/streaming). Paths are relative to `/v1`.

| Method | Path | Behavior |
| - | - | - |
| `POST` | `/agents/sessions/{session_id}/events` | Submit a nonempty `events` array; successful admission returns `204 No Content`. |
| `GET` | `/agents/sessions/{session_id}/events` | Subscribe to session events as `text/event-stream`. |
| `POST` | `/agents/sessions` | Create a session with optional `input`; set `stream: true` for a creation stream instead of a JSON session response. |

```bash theme={"dark"}
curl -N -H "Authorization: Bearer $API_KEY" \
  "$BASE_URL/agents/sessions/$SESSION_ID/events"

curl -X POST "$BASE_URL/agents/sessions/$SESSION_ID/events" \
  -H "Authorization: Bearer $API_KEY" -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: follow-up-1' \
  -d '{"events":[{"type":"agent.session.input.message","input":[{"role":"user","content":[{"type":"input_text","text":"Continue."}]}]}]}'
```

## Input event types

| Type | Purpose | Fields |
| - | - | - |
| `agent.session.input.message` | Send a user message. Starts a turn, or joins the running one. | `input`: a list of messages with `role` and `content` |
| `agent.session.input.tool_result` | Answer a function call | `turn_id`, `call_id`, `success`, and `output` (or `error` when `success` is false) |
| `agent.session.input.cancel` | Stop the running turn | none |

## Behavior

A submitted message can start a turn; do not infer completion from the `204`. Follow status events or retrieve turns. Closing a GET subscription does **not** cancel the turn. For SSE reconnection, send `Last-Event-ID` with a previously received event ID; the stream emits `id`, `event`, and JSON `data` fields. Treat IDs as opaque. Invalid cursors can return `400`.

## Output event names

The pinned event inventory records the following output **type names**, not full validated event payload definitions:

| Family | Types |
| - | - |
| Session lifecycle | `agent.session.created`, `agent.session.idle`, `agent.session.in_progress`, `agent.session.requires_action`, `agent.session.failed` |
| Environment | `agent.session.environment.pending`, `agent.session.environment.ready`, `agent.session.environment.connected`, `agent.session.environment.disconnected`, `agent.session.environment.failed` |
| Turn lifecycle | `agent.session.turn.created`, `agent.session.turn.in_progress`, `agent.session.turn.completed`, `agent.session.turn.failed`, `agent.session.turn.cancelled` |
| Turn content | `agent.session.turn.item.added`, `agent.session.turn.item.done`, `agent.session.turn.content_part.added`, `agent.session.turn.content_part.done`, `agent.session.turn.output_text.delta`, `agent.session.turn.output_text.done` |
| Reasoning summary | `agent.session.turn.reasoning_summary_part.added`, `agent.session.turn.reasoning_summary_part.done`, `agent.session.turn.reasoning_summary_text.delta`, `agent.session.turn.reasoning_summary_text.done` |
| Subagent | `agent.session.subagent.created`, `agent.session.subagent.active`, `agent.session.subagent.closed` |
| Other | `agent.output.command_execution_output.delta`, `error` |

For text, concatenate `delta` from `agent.session.turn.output_text.delta`; use `agent.session.turn.completed` or `failed` to decide a turn's outcome. Handle event types you do not recognize without assuming this table is exhaustive. Stream failures may arrive as `error` events after HTTP headers have already succeeded; see [Errors](/reference/errors).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.