Sessions

A session is an isolated container for a single end-user. Every agent runs inside a session, and every cost, log, and snapshot is scoped to it. Sessions let you enforce per-user spend limits, provide multi-tenant isolation, and produce billing data you can pass through to your users.

forUser — the common pattern

forUser is idempotent: if a session already exists for the given userId it is returned; otherwise a new one is created. Call it on every request — it is safe to call many times.

session.ts

import { Theazo } from class="cb-str">'theazo'

const theazo = new Theazo({ apiKey: process.env.THEAZO_API_KEY! })

// Idempotent — safe to call on every request
const session = await theazo.sessions.forUser(class="cb-str">'user_123', {
  limits: {
    maxCost: { amount: class="cb-num">500, currency: class="cb-str">'usd', period: class="cb-str">'day' },  class="cb-cmt">// $5.00/day
    maxAgents: class="cb-num">3,
    maxComputeMinutes: class="cb-num">60,
  },
  metadata: {
    plan: class="cb-str">'pro',
    email: class="cb-str">'alice@example.com',
  },
})

maxCost.amount is in integer cents — 500 means $5.00. All monetary values in Theazo use { amount: number, currency: string }, never plain strings.

Explicit creation

Use sessions.create when you need to create a session without a user ID, or when you need precise control over when a new session starts.

session.ts

const session = await theazo.sessions.create({
  userId: class="cb-str">'user_123',     class="cb-cmt">// optional — omit for anonymous sessions
  limits: {
    maxCost: { amount: class="cb-num">1000, currency: class="cb-str">'usd', period: class="cb-str">'month' },
    maxAgents: class="cb-num">10,
  },
  metadata: { source: class="cb-str">'api' },
})

console.log(session.id)        class="cb-cmt">// 'ses_...'
console.log(session.status)    class="cb-cmt">// 'active'
console.log(session.createdAt) class="cb-cmt">// Date

Fetching sessions

Get a session

session.ts

const session = await theazo.sessions.get(class="cb-str">'ses_...')

console.log(session.userId)  class="cb-cmt">// 'user_123'
console.log(session.status)  class="cb-cmt">// 'active' | 'paused' | 'terminated'

List sessions

session.ts

const { sessions, total } = await theazo.sessions.list({
  status: class="cb-str">'active',
  userId: class="cb-str">'user_123',    class="cb-cmt">// filter by user
  limit: class="cb-num">20,
  offset: class="cb-num">0,
})

Usage and limits

session.usage()

Returns current resource consumption for this session. Useful for building usage meters in your product UI.

session.ts

const usage = await session.usage()

console.log(usage.cost)            class="cb-cmt">// { amount: 234, currency: 'usd' }
console.log(usage.computeMinutes)  class="cb-cmt">// 47
console.log(usage.activeAgents)    class="cb-cmt">// 2
console.log(usage.modelCalls)      class="cb-cmt">// 38

session.limits()

Returns configured limits alongside current consumption so you can render progress bars or trigger warnings before a user hits their cap.

session.ts

const limits = await session.limits()

// Each entry: { limit, used, unit }
console.log(limits.maxCost)
// {
//   limit: { amount: 500, currency: 'usd', period: 'day' },
//   used:  { amount: 234, currency: 'usd' },
// }

console.log(limits.maxComputeMinutes)
// { limit: 60, used: 47, unit: 'minutes' }

console.log(limits.maxAgents)
// { limit: 3, used: 2, unit: 'agents' }

session.updateLimits(limits)

Update limits on a live session — for example when a user upgrades their plan. Partial updates are supported; omitted fields are unchanged.

session.ts

await session.updateLimits({
  maxCost: { amount: class="cb-num">2000, currency: class="cb-str">'usd', period: class="cb-str">'day' }, class="cb-cmt">// upgrade to $20/day
  maxAgents: class="cb-num">10,
})

Session lifecycle

Sessions progress through three states: active, paused, and terminated. Pausing preserves all running agents as snapshots; resuming restores them. Termination is permanent.

session-lifecycle.ts

// Pause — suspends all running agents, preserves state as snapshots
await session.pause()

// Resume — restores all paused agents from their snapshots
await session.resume()

// Terminate — permanent, destroys all agents and releases compute
await session.terminate()

terminate() is irreversible. All agent state, files, and browser sessions are destroyed. Snapshots created before termination remain accessible via the API.

Limit enforcement

When a session reaches its maxCost or maxComputeMinutes limit, Theazo automatically pauses all running agents and fires a session.limit_reached webhook. Agents are not terminated — they can be resumed once limits are updated.

webhook-payload.json

// Listen for limit events on your webhook endpoint
// POST https://yourapp.com/webhooks/theazo
{
  class="cb-str">"event": class="cb-str">"session.limit_reached",
  class="cb-str">"data": {
    class="cb-str">"sessionId": class="cb-str">"ses_...",
    class="cb-str">"userId": class="cb-str">"user_123",
    class="cb-str">"limitType": class="cb-str">"maxCost",
    class="cb-str">"used": { class="cb-str">"amount": class="cb-num">500, class="cb-str">"currency": class="cb-str">"usd" },
    class="cb-str">"limit": { class="cb-str">"amount": class="cb-num">500, class="cb-str">"currency": class="cb-str">"usd", class="cb-str">"period": class="cb-str">"day" }
  }
}

Method reference

theazo.sessions.forUser(userId, opts?)Promise<Session>Get or create a session for a user. Idempotent — safe to call on every request.

theazo.sessions.create(opts)Promise<Session>Explicitly create a new session. Always creates, even if userId already has one.

theazo.sessions.get(id)Promise<Session>Fetch a session by ID.

theazo.sessions.list(filters?)Promise<{ sessions, total }>List sessions with optional filters: status, userId, limit, offset.

session.usage()Promise<UsageSnapshot>Current consumption: cost, computeMinutes, activeAgents, modelCalls.

session.limits()Promise<LimitsSnapshot>Configured limits alongside current usage for each dimension.

session.updateLimits(limits)Promise<void>Update limits on a live session. Partial updates supported.

session.pause()Promise<void>Suspend all running agents as snapshots. Session transitions to 'paused'.

session.resume()Promise<void>Restore all paused agents from snapshots. Session transitions to 'active'.

session.terminate()Promise<void>Permanently destroy the session and all agents. Irreversible.