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 conversation keyed by the Claude session ID. Returns the conversation.

List sessions

GET /:org_id/sessions

Query parameters:

Parameter	Description
`page`	Page number (default: 1)
`per_page`	Items per page (default: 25)
`project_id`	Filter by project
`repo`	Filter by repository slug
`agent_name`	Filter by agent
`current_user_only`	Only show own sessions

Get session

GET /:org_id/sessions/:id

Returns the session with full details, including nested subagent sessions (tasks) and plans.

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.

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.