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 |
| 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.
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 managed Sandbox and Artifacts. Save any files you need first. Deleting the saved Agent instead does not delete its Sessions.