Sessions API

Sessions track AI coding activity. The CLI creates sessions automatically when you run crewkit code. The API provides endpoints for managing and analyzing session data.

All session endpoints are organization-scoped: /:org_id/sessions.

Create session

POST /:org_id/sessions
Content-Type: application/json

{
  "remote_url": "git@github.com:acme/backend",
  "component": "api",
  "repository_id": "repo_abc123"
}

Creates a Run and an initial Conversation. Returns the conversation.

List sessions

GET /:org_id/sessions

Query parameters:

Get session

GET /:org_id/sessions/:id

Returns the session with full details.

Update session

PATCH /:org_id/sessions/:id
Content-Type: application/json

{
  "model_metrics": {
    "input_tokens": 15000,
    "output_tokens": 3000,
    "cost_usd": 0.045
  }
}

Used by the CLI to periodically update session metrics.

End session

POST /:org_id/sessions/:id/end
Content-Type: application/json

{
  "summary": "Refactored authentication module...",
  "model_metrics": { ... }
}

Marks the session as ended. Triggers background analysis jobs.

Session hierarchy

GET /:org_id/sessions/:id/hierarchy

Returns the full session hierarchy: Run > Conversation > Tasks.

Threads

GET /:org_id/sessions/threads

Returns conversations grouped by thread (related sessions that share context).

Search

GET /:org_id/sessions/search?q=authentication

Full-text search across session summaries and metadata.

Compact

POST /:org_id/sessions/:id/compact

Trigger context compaction for the session.

Analytics

Summary

GET /:org_id/sessions/analytics/summary

Returns headline KPIs: total sessions, cost, tokens, average duration.

Query parameters: start_date, end_date, project_id, agent_name

Timeseries

GET /:org_id/sessions/analytics/timeseries

Returns metrics over time for charting.

Query parameters: start_date, end_date, interval (day/week), metric (sessions/cost/tokens)

By agent

GET /:org_id/sessions/analytics/by-agent

Metrics broken down by agent.

Cost breakdown

GET /:org_id/sessions/analytics/cost-breakdown

Cost split by model, project, and user.

By user

GET /:org_id/sessions/analytics/by-user

Per-user session metrics (requires admin/manager role).

Team overview

GET /:org_id/sessions/analytics/team-overview

Aggregated team performance metrics.

Event ingestion

POST /:org_id/observability/sessions/:session_id/events
Content-Type: application/json

{
  "events": [
    {
      "event_type": "PostToolUse",
      "timestamp": "2026-01-20T10:30:00Z",
      "data": { ... }
    }
  ]
}

Batched ingestion of hook events from the CLI.

Next steps

• API overview
• Resources API