Sessions

A session runs an agent with a fixed harness, instructions, environment, permissions, and budget. Its transcript and changes remain available after the sandbox stops.

Start a session

Use New session in the dashboard or POST /v1/sessions:

JSON

{
  "harness": {"type": "claude_code", "model": "claude-sonnet-5"},
  "environment": "api-environment",
  "instructions": "Run relevant tests before proposing a change.",
  "prompt": "Fix the failing request validation test.",
  "budget": 5
}

harness is required. environment accepts a saved environment name or an inline object. Omit it to use the basic sandbox with no configured repositories.

Claude Code uses the account's default model when model is omitted. An explicit budget above the account's session ceiling is rejected.

Conversations

Sessions accept follow-up messages by default. Claude Code queues a message sent during a turn for the next turn; Codex steers the current turn when possible.

Shell

curl https://api.ellipsis.dev/v1/sessions/SESSION_ID/messages \
  -H "Authorization: Bearer $ELLIPSIS_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"message": "Add a regression test for the empty input."}'

After a turn with no pending messages, the sandbox stays warm for about one minute, then pauses. A later message resumes the retained conversation and workspace. The conversation shares one budget.

Closing a browser tab does not stop work. Stop a session from the dashboard or POST /v1/sessions/{session_id}/stop.

One-shot tasks

Set interactive: false to close after the first turn. A one-shot session requires a prompt and rejects follow-up messages.

JSON

{
  "harness": {"type": "codex", "model": "gpt-5.6-terra"},
  "interactive": false,
  "prompt": "Run the tests and report failures.",
  "environment": "api-environment",
  "budget": 3
}

Codex supports one-shot tasks, follow-up messages, and resumed conversations. See Models for available capabilities.

Inspect the result

What you need	Endpoint
Status and cost	`GET /v1/sessions/{session_id}`
Messages and tool results	`GET /v1/sessions/{session_id}/records`
Changes	`GET /v1/sessions/{session_id}/diff`
Commits and pull requests	`GET /v1/sessions/{session_id}/git`
Execution results and resolved settings	`GET /v1/sessions/{session_id}/executions`
Validated JSON output	`GET /v1/sessions/{session_id}/output`
Transcript export	`GET /v1/sessions/{session_id}/export`

Use the SDK's live stream to follow work without polling. Lifecycle explains the main transitions; Session events lists every event with JSON examples and field specifications.

The session's source identifies how it started, such as api, cron, react, or mention. Its optional event describes the external event using a resource type such as github.pull_request or slack.message. A pull request can start a session through either a mention or an automation; both use event.type: "github.pull_request". API, CLI, web, and cron starts have event: null.

Read fields according to event.type: GitHub events include repository, Slack events include channel_id, and each variant has its own relevant fields. An automation's trigger remains the configured schedule or matching rule.

Find sessions by handler

When a saved handler starts a session, the session's handler records its service, id, effective display name in agent_name, and configuration fingerprint sha. The display name comes from ellipsis.name, or the service default when omitted. These values stay fixed when the session resumes or the handler changes. Built-in responders, older sessions, and sessions started without a handler have handler: null.

Sessions to find	Endpoint
GitHub mentions, including the built-in responder	`GET /v1/sessions?service=github&source=mention`
Sentry investigations from issue and metric alerts, including legacy automations	`GET /v1/sessions?service=sentry`
Sessions started by one saved handler	`GET /v1/sessions?handler=HANDLER_ID`

Get handler IDs from GET /v1/handlers. The handler filter also works after that handler is deleted. Service filters include older sessions without handler attribution.

The same service, source, and handler filters work with GET /v1/sessions/search. For example, GET /v1/sessions/search?q=validation&service=github&source=mention searches GitHub mention sessions for validation-related work.

When a session stops

A closed session can have succeeded or failed. Read exit_status alongside status.

Exit status	Meaning
`success`	The agent finished
`budget_hit`	A session or trailing spend limit was reached
`cancelled`	The session was stopped
`lifecycle_hook_failed`	Environment setup or a hook failed
`missing_sandbox_variables`	A referenced secret was not stored

Inspect the transcript and environment log before retrying. A retry starts new work and incurs new usage.

Cost and records

Model requests and sandbox time contribute to usage. A warm sandbox continues to accrue compute usage until it stops. See Pricing.

Complete messages persist in the transcript. Live text deltas are temporary. Retention settings apply to stored session records.