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
The official SDK uses your Rebyte organization key. 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; it does not replace the resolved Agent or Environment. 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. Failed environment initialization leaves the Session failed. Connection and execution errors preserve the existing Sandbox binding and files.
There is no automatic conversation compaction. Long Sessions remain 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.