API Reference

Sessions

A session is a contiguous window of AI tool activity by a single user. Sessions are created automatically by the FORG agent when a new period of activity begins after 30 minutes of inactivity (configurable via session_timeout).

The session object

{
  "id":            "sess_4f9a2e1b8c3d",
  "user_id":       "user_abc123",
  "project_id":    "proj_xyz789",
  "started_at":    "2025-05-28T09:12:00Z",
  "ended_at":      "2025-05-28T10:47:23Z",
  "duration_s":    5723,
  "model":         "claude-opus-4-5",
  "models":        ["claude-opus-4-5", "claude-sonnet-4"],
  "tokens_in":     84320,
  "tokens_out":    22180,
  "cost_usd":      4.2160,
  "signal_count":  47,
  "error_count":   2,
  "adapter":       "claude-code"
}

List sessions

GET /api/v1/sessions

Query parameters:

Parameter	Type	Description
`user_id`	string	Filter by user
`project_id`	string	Filter by project
`model`	string	Filter by primary model (exact match)
`adapter`	string	Filter by adapter name
`from`	ISO 8601	Sessions starting at or after this time
`to`	ISO 8601	Sessions starting before this time
`limit`	number	Page size (default: 20, max: 100)
`cursor`	string	Pagination cursor from previous response
`order`	string	`desc` (default) or `asc`

Example:

curl "https://forg.pro/api/v1/sessions?user_id=user_abc123&from=2025-05-01&limit=10" \
  -H "Authorization: Bearer forg_live_..."

{
  "data": [
    {
      "id": "sess_4f9a2e1b8c3d",
      "user_id": "user_abc123",
      "started_at": "2025-05-28T09:12:00Z",
      "tokens_in": 84320,
      "tokens_out": 22180,
      "cost_usd": 4.216,
      ...
    }
  ],
  "cursor": "sess_9b3c1d2e",
  "has_more": true,
  "total": 142
}

Get a session

GET /api/v1/sessions/:id

curl "https://forg.pro/api/v1/sessions/sess_4f9a2e1b8c3d" \
  -H "Authorization: Bearer forg_live_..."

Returns the full session object including all signals within the session.

List signals in a session

GET /api/v1/sessions/:id/events

Returns all individual signal events within the session, paginated. See the Events page for the event schema.

Node.js example

import { ForgClient } from "@forg-pro/sdk";

const forg = new ForgClient({ apiKey: process.env.FORG_API_KEY });

// List last 7 days of sessions for a user
const sessions = await forg.sessions.list({
  user_id: "user_abc123",
  from: new Date(Date.now() - 7 * 24 * 60 * 60 * 1000).toISOString(),
  limit: 50,
});

for (const session of sessions.data) {
  console.log(`${session.id}: $${session.cost_usd.toFixed(4)} | ${session.tokens_in} in`);
}

// Paginate
if (sessions.has_more) {
  const page2 = await forg.sessions.list({ cursor: sessions.cursor });
}