Sessions

Creating a Session

Create a session to start tracking a workflow. Sessions are optional but recommended for complex automation.

curl -X POST https://agentinbox.in/api/v1/sessions \
  -H "Authorization: Bearer $AgentInbox_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "user-signup-flow"}'

const session = await client.sessions.create({
  name: "user-signup-flow",
});
console.log(session.id); // "sess_789"

session = client.sessions.create(name="user-signup-flow")
print(session.id)  # "sess_789"

Listing Sessions

List all sessions with pagination and filtering by status.

const sessions = await client.sessions.list({ limit: 10 });
for (const s of sessions.data) {
  console.log(s.name, s.status);
}

sessions = client.sessions.list(limit=10)
for s in sessions.data:
    print(s.name, s.status)

Getting a Session

Retrieve a session by ID to see its associated inboxes, waits, and current status.

curl https://agentinbox.in/api/v1/sessions/sess_789 \
  -H "Authorization: Bearer $AgentInbox_API_KEY"

const session = await client.sessions.get("sess_789");
console.log(session.inboxes); // List of inbox IDs
console.log(session.status);  // "active" | "completed" | "failed"

Completing a Session

Mark a session as completed when your workflow finishes. This updates the status and finalizes the timeline.

curl -X POST https://agentinbox.in/api/v1/sessions/sess_789/complete \
  -H "Authorization: Bearer $AgentInbox_API_KEY"

await client.sessions.complete("sess_789");

Timeline

Every session maintains a timeline of events. View the timeline to debug or audit your workflow.

const timeline = await client.sessions.timeline("sess_789");
for (const event of timeline.events) {
  console.log(event.timestamp, event.type, event.description);
}

Timeline Events

Execution Replay

Replay a session's execution to debug failures or retry workflows. See the Execution Replay guide for details.

const replay = await client.sessions.replay("sess_789");
console.log(replay.steps);

Next Steps