Manage sessions
Retrieve state, organize sessions, handle retries, and release resources.
On this page
AuthenticationRetrieve and organizeInput idempotencyFailure and recoveryDelete a SessionSession resources belong to the organization authenticated by your API key. Store Session IDs alongside the corresponding user or workflow in your application.
Authentication
Configure the official OpenAI client with your Rebyte organization key and the Rebyte endpoint, as shown in Quickstart. For raw HTTP requests, send Authorization: Bearer <key> and OpenAI-Beta: agents=v1.
| Operations | Key permissions |
|---|---|
| Read Agents, Sessions, Turns, and Items | tasks:read |
| Create or change Agents and Sessions; submit events | tasks:write |
| Create/delete standalone Environments (Rebyte extension) | tasks:write |
| Read environment files and Artifacts | tasks:read and files:read |
| Write environment files or delete Artifacts | tasks:write and files:write |
| Read or change Vaults | api.vaults.read / api.vaults.write |
Keep organization keys on the server. Existing keys are not automatically granted Vault permissions.
Retrieve and organize
const session = await client.beta.agents.sessions.retrieve(sessionId);
console.log(session.status, session.required_actions);
const sessions = await client.beta.agents.sessions.list({ limit: 20 });
for (const entry of sessions.data) console.log(entry.id, entry.status);
Use metadata to associate Sessions with your application. POST /v1/agents/sessions/{session_id} updates metadata and the Session Agent's model, reasoning effort, or service tier. Generation setting updates apply to future Turns; running and queued Turns retain their settings. History and the Environment stay intact. List endpoints use cursor pagination.
To group tasks and feedback across Sessions, create a
Scenario and supply its scenario_id when creating
each Session. Omitted or null means unbound. This binding is immutable and
cannot be changed by a Session update. Session and Turn resources always include
scenario_id: string | null; new feedback inherits it. List bound Sessions with
GET /v1/agents/sessions?scenario_id=scn_…, or use the current extension source's
typed rebyte.sessions.list({ scenario_id }).
Scenario binding and filtering are part of Rebyte Loop (Preview).
Input idempotency
Set Idempotency-Key on an input submission and reuse it only when retrying that same input. The key is scoped to the Session. Reusing it with different events returns 409. Replaying an old cancellation does not cancel a newer Turn.
This contract applies to input submission. Session creation is not currently idempotent: after an ambiguous creation timeout, inspect existing Sessions and resolve whether creation succeeded before creating another.
Failure and recovery
Read both Session status and the latest Turn. A failed or cancelled Turn usually leaves the Session available for another input. Each message submission creates a Turn; concurrent submissions queue within that Session. Client-function waits time out after 24 hours. Failed environment initialization leaves the Session failed. Connection and execution errors preserve the existing Sandbox binding and files.
Long Sessions support automatic compaction and manual /compact, while remaining subject to the selected model's context limits. Worker-loss detection can take up to the current 15-minute activity timeout; external tool effects are not guaranteed exactly once.
Delete a Session
await client.beta.agents.sessions.delete(sessionId);
Deletion removes that Session's Artifacts and its private Environment/Sandbox. In the shared Environment API, deletion removes its attachment and Artifacts while preserving the shared Environment; its Sandbox, files and stdio MCP processes can remain even after the last Session is deleted. HTTP MCP cleanup still runs and can affect a reused upstream connection. Developers coordinate shared resource cleanup and explicitly delete the Environment after all Sessions detach. See MCP names and reuse. Save any Artifacts you need before Session deletion. Deleting a saved Agent does not delete its Sessions.