---
title: "Organization agent sessions page contract"
method: GET
path: "/api/v1/organizations/{org_slug}/pages/sessions"
tags: ["organizations"]
---

# Organization agent sessions page contract

`GET /api/v1/organizations/{org_slug}/pages/sessions`

## Request

- Base URL: `https://composal.com` (the document declares no server; this is the origin it was published from)
- URL: `https://composal.com/api/v1/organizations/{org_slug}/pages/sessions`
- Auth: HTTP bearer

Cross-repo browser of captured agent sessions for one organization, restricted to repositories the current user can read. Returns the filtered/paginated session list with per-session stats, filter facets, and — when `session` is supplied — the expanded session's checkpoint timeline, its server-derived git `commits` and `pull_requests`, and its checkpoint `linked_commits`. Each expanded checkpoint carries the Git commit IDs it is attached to (`linked_commits`), resolved through the reverse checkpoint→commit lookup; `linked_commits_available` is false and the lists are empty when that lookup is unavailable. Payloads carry sanitized provenance only (no storage keys, checksums, or archive URLs).

## Path parameters

- `org_slug` string, required

## Query parameters

- `repo` string
- `adapter` string
- `user_id` string
- `status` string
- `from` string
- `to` string
- `offset` integer
- `limit` integer
- `session` string

## Response `200`

Organization sessions page contract

- object
  - `sessions` OrganizationSessionSummary[], required
    - `id` string, required
    - `adapter` string, required
    - `harness` string, required: Harness id the session presents as (codex, claude-code, cursor, roder, grok): the captured envelope's harness when recorded, else the adapter's canonical harness.
    - `status` string, required
    - `title` string, nullable, required
    - `external_session_id` string, required
    - `repository` OrganizationSessionRepository, required
      - `id` string, required
      - `slug` string, required
      - `name` string, required
    - `user` OrganizationSessionUser, required
      - `id` string, required
      - `name` string, nullable, required
      - `handle` string, nullable, required
      - `avatar_url` string, nullable, required: Avatar URL for the session owner: their OAuth/profile picture when set, otherwise a deterministic Gravatar derived from their email (mirrors History's commit author avatars).
    - `started_at` string, nullable, required
    - `ended_at` string, nullable, required
    - `last_checkpoint_at` string, nullable, required
    - `last_activity_at` string, nullable, required: When the session last did anything: the newest checkpoint capture, else the session end, else its start.
    - `created_at` string, nullable, required
    - `updated_at` string, nullable, required
    - `stats` OrganizationSessionStats, required
      - `checkpoint_count` integer, required
      - `uploaded_count` integer, required
      - `failed_count` integer, required
      - `pending_count` integer, required
      - `redaction_count` integer, required
      - `last_captured_at` string, nullable, required
      - `total_tokens` integer, nullable, required
      - `token_usage_scope` string, nullable, required
      - `token_usage` AgentTokenUsage, required: Itemized token counters a cost estimate prices. `input_tokens` is the uncached prompt share; `cache_read_input_tokens` and `cache_creation_input_tokens` are the two cache classes (priced very differently), with the creation count split by TTL when the provider reports it; `cached_input_tokens` is their sum. `output_tokens` already includes `reasoning_output_tokens`. `api_call_count` is the number of distinct model responses behind the counters. Each field is null when the harness did not report it.
        - `input_tokens` integer, nullable, required
        - `cached_input_tokens` integer, nullable, required
        - `cache_read_input_tokens` integer, nullable, required
        - `cache_creation_input_tokens` integer, nullable, required
        - `cache_creation_5m_input_tokens` integer, nullable, required
        - `cache_creation_1h_input_tokens` integer, nullable, required
        - `output_tokens` integer, nullable, required
        - `reasoning_output_tokens` integer, nullable, required
        - `total_tokens` integer, nullable, required
        - `api_call_count` integer, nullable, required
      - `model_usage` AgentModelTokenUsage[], required: Per-model split of `token_usage`, sorted by model. Empty when the checkpoints predate per-model accounting.
        - `input_tokens` integer, nullable, required
        - `cached_input_tokens` integer, nullable, required
        - `cache_read_input_tokens` integer, nullable, required
        - `cache_creation_input_tokens` integer, nullable, required
        - `cache_creation_5m_input_tokens` integer, nullable, required
        - `cache_creation_1h_input_tokens` integer, nullable, required
        - `output_tokens` integer, nullable, required
        - `reasoning_output_tokens` integer, nullable, required
        - `total_tokens` integer, nullable, required
        - `api_call_count` integer, nullable, required
        - `model` string, required: Provider model id this share of the usage was billed to.
      - `estimated_cost` AgentCostEstimate, required: Estimated token cost at today's public list prices, priced by Rails so no client carries a price table. `usd` is a decimal string. `floor` is true when a model in the session has no list price, so the figure is a lower bound; those models are listed in `unpriced_models`. `models` gives each priced model's share. Rows shipped to analytics carry the price at capture time instead, so history never moves when the table does.
        - `usd` string, required
        - `floor` boolean, required
        - `models` object[], required
          - `model` string, required
          - `usd` string, required
        - `unpriced_models` string[], required
        - `pricing_version` string, required
      - `message_count` integer, nullable, required: Conversation prompt and response count derived from the session's latest uploaded checkpoint transcript. Falls back to the captured harness count when the transcript has not been indexed, or null.
      - `agent_count` integer, nullable, required: Total agents the session ran (the primary agent plus its observed child agents), or null for a solo session with no observed subagents.
      - `model` string, nullable, required: Model id from the latest uploaded checkpoint, for cost estimation.
      - `commit_count` integer, required: Server-derived Git commits linked to this session. The commits themselves ride the expanded session, not the row.
      - `pull_request_count` integer, required: Distinct GitHub pull requests those commits belong to. Zero while a trailer link is waiting for its pull request.
      - `pull_requests` OrganizationSessionPullRequest[], required: The first few of those pull requests, in first-seen order, so a row can link them — at most three, whatever `pull_request_count` says. A reader renders the remainder as a `+N` from the count.
        - `number` integer, required
        - `state` 'open' | 'closed' | 'merged', required
        - `github_url` string, nullable, required: The pull request on GitHub, built from the virtual repository's owner and name. Null when that addressing is missing.
        - `merge_commit_sha` string, nullable, required: The commit that landed on merge, whatever strategy produced it.
        - `merged_at` string, nullable, required
        - `head_branch` string, nullable, required
  - `pagination` object, required
    - `offset` integer, required
    - `limit` integer, required
    - `has_more` boolean, required
  - `facets` object, required
    - `adapters` string[], required
    - `repositories` object[], required
      - `id` string, required
      - `slug` string, required
      - `name` string, required
      - `session_count` integer, required
    - `users` object[], required
      - `id` string, required
      - `name` string, nullable, required
      - `handle` string, nullable, required
      - `avatar_url` string, nullable, required: Avatar URL for the session owner: their OAuth/profile picture when set, otherwise a deterministic Gravatar derived from their email (mirrors History's commit author avatars).
      - `session_count` integer, required
  - `session` OrganizationSessionDetail, required
    - `id` string, required
    - `adapter` string, required
    - `harness` string, required: Harness id the session presents as (codex, claude-code, cursor, roder, grok): the captured envelope's harness when recorded, else the adapter's canonical harness.
    - `status` string, required
    - `title` string, nullable, required
    - `external_session_id` string, required
    - `repository` OrganizationSessionRepository, required
      - `id` string, required
      - `slug` string, required
      - `name` string, required
    - `user` OrganizationSessionUser, required
      - `id` string, required
      - `name` string, nullable, required
      - `handle` string, nullable, required
      - `avatar_url` string, nullable, required: Avatar URL for the session owner: their OAuth/profile picture when set, otherwise a deterministic Gravatar derived from their email (mirrors History's commit author avatars).
    - `started_at` string, nullable, required
    - `ended_at` string, nullable, required
    - `last_checkpoint_at` string, nullable, required
    - `last_activity_at` string, nullable, required: When the session last did anything: the newest checkpoint capture, else the session end, else its start.
    - `created_at` string, nullable, required
    - `updated_at` string, nullable, required
    - `original_resume` object, nullable, required: An author-only local resume target for the original provider session. Null for other viewers and unsupported providers.
      - `kind` 'codex_deep_link' | 'claude_command' | 'cursor_command' | 'grok_command', required
      - `value` string, required
    - `linked_commits_available` boolean, required: True when the reverse checkpoint→commit lookup succeeded for the expanded session; false when it was unavailable.
    - `total_tokens` integer, nullable, required: Session token headline: the latest checkpoint's own reported total (never a sum — turn and cumulative scopes are not additive), or null when no checkpoint reported usage.
    - `token_usage_scope` string, nullable, required: The scope of the headline total (turn, session, or cumulative).
    - `token_usage` AgentTokenUsage, required: Itemized token counters a cost estimate prices. `input_tokens` is the uncached prompt share; `cache_read_input_tokens` and `cache_creation_input_tokens` are the two cache classes (priced very differently), with the creation count split by TTL when the provider reports it; `cached_input_tokens` is their sum. `output_tokens` already includes `reasoning_output_tokens`. `api_call_count` is the number of distinct model responses behind the counters. Each field is null when the harness did not report it.
      - `input_tokens` integer, nullable, required
      - `cached_input_tokens` integer, nullable, required
      - `cache_read_input_tokens` integer, nullable, required
      - `cache_creation_input_tokens` integer, nullable, required
      - `cache_creation_5m_input_tokens` integer, nullable, required
      - `cache_creation_1h_input_tokens` integer, nullable, required
      - `output_tokens` integer, nullable, required
      - `reasoning_output_tokens` integer, nullable, required
      - `total_tokens` integer, nullable, required
      - `api_call_count` integer, nullable, required
    - `model_usage` AgentModelTokenUsage[], required: Per-model split of `token_usage`, sorted by model.
      - `input_tokens` integer, nullable, required
      - `cached_input_tokens` integer, nullable, required
      - `cache_read_input_tokens` integer, nullable, required
      - `cache_creation_input_tokens` integer, nullable, required
      - `cache_creation_5m_input_tokens` integer, nullable, required
      - `cache_creation_1h_input_tokens` integer, nullable, required
      - `output_tokens` integer, nullable, required
      - `reasoning_output_tokens` integer, nullable, required
      - `total_tokens` integer, nullable, required
      - `api_call_count` integer, nullable, required
      - `model` string, required: Provider model id this share of the usage was billed to.
    - `estimated_cost` AgentCostEstimate, required: Estimated token cost at today's public list prices, priced by Rails so no client carries a price table. `usd` is a decimal string. `floor` is true when a model in the session has no list price, so the figure is a lower bound; those models are listed in `unpriced_models`. `models` gives each priced model's share. Rows shipped to analytics carry the price at capture time instead, so history never moves when the table does.
      - `usd` string, required
      - `floor` boolean, required
      - `models` object[], required
        - `model` string, required
        - `usd` string, required
      - `unpriced_models` string[], required
      - `pricing_version` string, required
    - `models` string[], required: Distinct model ids seen across the session's checkpoints, first-seen order.
    - `redaction_count` integer, required: Total redactions across the session's checkpoints.
    - `linked_commits` string[], required: Distinct Git commit IDs the session's checkpoints are attached to, in first-seen order. Empty when the reverse lookup was unavailable.
    - `commits` OrganizationSessionCommit[], required: Server-derived git commits for this session, oldest first, each labelled by how it was found.
      - `sha` string, required: The 40-character git commit SHA.
      - `evidence` 'trailer' | 'merge' | 'checkpoint', required: How the server found this commit for the session: `trailer` — the commit message carried the session's `Vex-Session` line; `merge` — GitHub reported it as the pull request's merge commit. `checkpoint` — a session's checkpoint was sealed at this commit and no trailer named it.
      - `pull_request_number` integer, nullable, required: The pull request this commit was found in, or null for a trailer link discovered before any pull request named it.
    - `pull_requests` OrganizationSessionPullRequest[], required: Distinct GitHub pull requests those commits belong to, in first-seen order.
      - `number` integer, required
      - `state` 'open' | 'closed' | 'merged', required
      - `github_url` string, nullable, required: The pull request on GitHub, built from the virtual repository's owner and name. Null when that addressing is missing.
      - `merge_commit_sha` string, nullable, required: The commit that landed on merge, whatever strategy produced it.
      - `merged_at` string, nullable, required
      - `head_branch` string, nullable, required
    - `resume_checkpoint_id` string, nullable, required: Public id of the checkpoint a local resume/continue command should target — the latest UPLOADED checkpoint (only uploaded checkpoints have a verified archive). Null when none uploaded.
    - `checkpoints` OrganizationSessionCheckpoint[], required
      - `id` string, required
      - `external_checkpoint_id` string, required
      - `sequence_number` integer, required
      - `capture_kind` string, required
      - `status` string, required
      - `scrubber_version` string, required
      - `redaction_count` integer, required
      - `model` string, nullable, required: Model id from this checkpoint's sanitized envelope, or null.
      - `reasoning_effort` string, nullable, required: Reasoning effort from this checkpoint's sanitized envelope (none, minimal, low, medium, high, xhigh, max, ultra), or null.
      - `total_tokens` integer, nullable, required: This checkpoint's own reported token total, or null.
      - `token_usage_scope` string, nullable, required: What the reported total covers (turn, session, or cumulative), or null when no usage was reported.
      - `captured_at` string, nullable, required
      - `uploaded_at` string, nullable, required
      - `tombstoned_at` string, nullable, required
      - `linked_commits` string[], required: Native commit ids this checkpoint is attached to (reverse checkpoint→commit lookup). Empty when unavailable or unattached.
      - `linked_commits_available` boolean, required: True when the reverse checkpoint→commit lookup succeeded for this session; false (with empty `linked_commits`) when it was unavailable.
  - `search_enabled` boolean
  - `search` union
    - TranscriptSearchResult
      - `query` string, required
      - `mode_requested` string, required
      - `mode_used` string, required
      - `status` 'ready' | 'empty' | 'not_ready' | 'degraded', required
      - `coverage` object, required
        - `sessions` integer, required
        - `ready` integer, required
        - `pending` integer, required
        - `failed` integer, required
        - `indexed_at` string, nullable, required
      - `results` TranscriptSearchHit[], required
        - `session_id` string, required
        - `title` string, nullable, required
        - `repository` object, required
          - `id` string, required
          - `slug` string, required
        - `user` object, required
          - `id` string, required
          - `name` string, nullable, required
        - `harness` string, required
        - `model` string, nullable, required
        - `started_at` string, required
        - `url` string, required
        - `matches` TranscriptSearchMatch[], required
          - `role` 'user' | 'assistant', required
          - `excerpt` string, required
          - `source_ref` string, required
          - `checkpoint_id` string, required
          - `event_index` integer, required
          - `event_digest` string, required
          - `byte_start` integer, required
          - `byte_end` integer, required
          - `truncated` boolean, required
      - `pagination` object, required
        - `next_cursor` string, nullable, required
        - `window_exhausted` boolean, required
        - `budget_limited` boolean, required
      - `limits` object, required
        - `limit` integer, required
        - `max_bytes` integer, required
        - `candidate_window` integer, required
      - `degradation` string
    - TranscriptSearchError
      - `status` 'error', required
      - `code` string, required
      - `error` string, required
      - `results` TranscriptSearchHit[], required
        - `session_id` string, required
        - `title` string, nullable, required
        - `repository` object, required
          - `id` string, required
          - `slug` string, required
        - `user` object, required
          - `id` string, required
          - `name` string, nullable, required
        - `harness` string, required
        - `model` string, nullable, required
        - `started_at` string, required
        - `url` string, required
        - `matches` TranscriptSearchMatch[], required
          - `role` 'user' | 'assistant', required
          - `excerpt` string, required
          - `source_ref` string, required
          - `checkpoint_id` string, required
          - `event_index` integer, required
          - `event_digest` string, required
          - `byte_start` integer, required
          - `byte_end` integer, required
          - `truncated` boolean, required

## Other responses

- `401`: Unauthorized
- `403`: Forbidden
- `404`: Not found
- `422`: Unprocessable entity
- `502`: Bad gateway

---

[API](https://skmtc.dev/composal/apis/vex-api.md) - [All operations](https://skmtc.dev/composal/apis/vex-api/llms.txt) - [OpenAPI document](https://skmtc.dev/composal/apis/vex-api/revisions/74298a24e040?raw)