---
source: CrewKit documentation
url: https://crewkit.io/docs/api-sessions.md
title: "Sessions API"
description: "Create, list, update, and analyze coding sessions."
---


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.

---

## Next steps

- [API overview](/docs/api-overview)
- [Resources API](/docs/api-resources)