> ## Documentation Index
> Fetch the complete documentation index at: https://claudescope.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Sessions API — List, Get, Update, Delete

> Create, list, retrieve, update, delete, and poll sessions with the Claude Scope Sessions API — including frame data and processing status.

Sessions are the central resource in Claude Scope. Each session represents one analysis run — a recorded video, its extracted frames, the ARIA inspection results, and the generated agent prompt. You can create sessions manually, retrieve them individually or as a list, poll their processing status, update their metadata, or delete them. The Sessions API gives you full programmatic control over everything visible in the Claude Scope dashboard.

***

## POST /api/sessions — Create a session

Creates a new session record without uploading a video. Use this endpoint when you want to pre-create a session and track it separately, or when you are integrating with a custom recording pipeline. To upload a video and create a fully processed session in one step, use [POST /recordings](/api/recordings) instead.

### Request body

<ParamField body="title" type="string" required>
  Human-readable title for the session. Maximum 500 characters.
</ParamField>

<ParamField body="agentTarget" type="string" default="CLAUDE_CODE">
  Target AI coding agent. One of: `CLAUDE_CODE`, `CODEX`, `CURSOR`, `RAW`.
</ParamField>

<ParamField body="frameCount" type="number">
  Expected or actual number of frames. Minimum 0.
</ParamField>

<ParamField body="urlCount" type="number">
  Expected or actual number of URLs inspected. Minimum 0.
</ParamField>

### Response

Returns a [Session object](#session-object).

***

## GET /api/sessions — List sessions

Returns all sessions belonging to your account, ordered by most recently updated.

### Request

No parameters required.

### Response

Returns an array of [Session objects](#session-object).

### Example

```bash theme={null}
curl https://api.claudescope.ai/api/sessions \
  -H "Authorization: Bearer <token>"
```

```json theme={null}
[
  {
    "id": "sess_ABC12345",
    "userId": "usr_XYZ",
    "title": "Checkout flow bug",
    "seedUrl": "https://your-app.com/checkout",
    "status": "complete",
    "duration": 45,
    "frameCount": 4,
    "urls": ["https://your-app.com/checkout"],
    "urlCount": 1,
    "agentTarget": "CLAUDE_CODE",
    "processingTime": 14320,
    "prompt": "You are an expert frontend engineer...",
    "createdAt": "2026-04-12T10:23:45.000Z",
    "updatedAt": "2026-04-12T10:24:00.000Z"
  }
]
```

***

## GET /api/sessions/stats — Get statistics

Returns aggregate statistics computed across all sessions in your account.

### Request

No parameters required.

### Response

<ResponseField name="totalSessions" type="number" required>
  Total number of sessions in your account.
</ResponseField>

<ResponseField name="completedSessions" type="number" required>
  Number of sessions with `status: "complete"`.
</ResponseField>

<ResponseField name="totalDuration" type="number" required>
  Sum of `duration` (in seconds) across all completed sessions.
</ResponseField>

<ResponseField name="avgProcessingTime" type="number" required>
  Average `processingTime` (in milliseconds) across all completed sessions.
</ResponseField>

***

## GET /api/sessions/:id — Get session with frames

Returns a single session including its full array of extracted frames.

### Path parameter

<ParamField path="id" type="string" required>
  The session ID, e.g. `sess_ABC12345`.
</ParamField>

### Response

Returns a [SessionWithFrames object](#session-object) — a Session with an additional `frames` array.

### Example

```bash theme={null}
curl https://api.claudescope.ai/api/sessions/sess_ABC12345 \
  -H "Authorization: Bearer <token>"
```

```json theme={null}
{
  "id": "sess_ABC12345",
  "userId": "usr_XYZ",
  "title": "Checkout flow bug",
  "seedUrl": "https://your-app.com/checkout",
  "status": "complete",
  "duration": 45,
  "frameCount": 4,
  "urls": ["https://your-app.com/checkout"],
  "urlCount": 1,
  "agentTarget": "CLAUDE_CODE",
  "processingTime": 14320,
  "prompt": "You are an expert frontend engineer...",
  "createdAt": "2026-04-12T10:23:45.000Z",
  "updatedAt": "2026-04-12T10:24:00.000Z",
  "frames": [
    {
      "id": "frm_001",
      "sessionId": "sess_ABC12345",
      "timestamp": 1200,
      "url": "https://your-app.com/checkout",
      "thumbnailUrl": "data:image/png;base64,iVBORw0KGgo...",
      "diffSummary": { "added": 2, "changed": 5, "removed": 0 },
      "ariaTree": [{ "role": "button", "name": "Place order" }],
      "createdAt": "2026-04-12T10:23:50.000Z"
    }
  ]
}
```

***

## GET /api/sessions/:id/status — Poll processing status

Returns the current processing state of a session. Use this endpoint to track progress when a session is actively being processed. Poll at a reasonable interval (e.g. every 2–3 seconds) until `overallStage` is `complete` or `error`.

### Path parameter

<ParamField path="id" type="string" required>
  The session ID to poll.
</ParamField>

### Response

<ResponseField name="sessionId" type="string" required>
  The session ID.
</ResponseField>

<ResponseField name="sessionStatus" type="string" required>
  High-level session status: `processing`, `complete`, or `error`.
</ResponseField>

<ResponseField name="processingStatus" type="object">
  Detailed per-lane processing state, or `null` if status information is not yet available.

  <Expandable title="processingStatus properties">
    <ResponseField name="overallStage" type="string">
      Current pipeline stage. One of: `uploading`, `extracting`, `analyzing`, `synthesizing`, `persisting`, `complete`, `error`.
    </ResponseField>

    <ResponseField name="visionLane" type="object">
      Status of the Vision AI analysis lane.

      <Expandable title="lane status properties">
        <ResponseField name="status" type="string">One of: `pending`, `running`, `complete`, `error`.</ResponseField>
        <ResponseField name="startedAt" type="string">ISO 8601 timestamp when the lane started.</ResponseField>
        <ResponseField name="completedAt" type="string">ISO 8601 timestamp when the lane completed.</ResponseField>
        <ResponseField name="error" type="string">Error message if the lane failed.</ResponseField>
        <ResponseField name="detail" type="string">Additional human-readable detail about current lane activity.</ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="playwrightLane" type="object">
      Status of the Playwright ARIA inspection lane. Same shape as `visionLane`.
    </ResponseField>

    <ResponseField name="frameExtraction" type="object">
      Status of the frame extraction step. Same shape as `visionLane`.
    </ResponseField>

    <ResponseField name="synthesis" type="object">
      Status of the prompt synthesis step. Same shape as `visionLane`.
    </ResponseField>

    <ResponseField name="lastUpdated" type="string">
      ISO 8601 timestamp of the most recent status update.
    </ResponseField>

    <ResponseField name="lastError" type="string">
      Most recent error message if any lane failed.
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="processingTime" type="number" required>
  Elapsed processing time in milliseconds.
</ResponseField>

<ResponseField name="lastError" type="string">
  Top-level error message if the session failed, or `null`.
</ResponseField>

### Example

```bash theme={null}
curl https://api.claudescope.ai/api/sessions/sess_ABC12345/status \
  -H "Authorization: Bearer <token>"
```

```json theme={null}
{
  "sessionId": "sess_ABC12345",
  "sessionStatus": "processing",
  "processingStatus": {
    "overallStage": "analyzing",
    "visionLane": {
      "status": "running",
      "startedAt": "2026-04-12T10:23:47.000Z",
      "completedAt": null,
      "detail": "Analyzing frame 2 of 4"
    },
    "playwrightLane": {
      "status": "complete",
      "startedAt": "2026-04-12T10:23:46.000Z",
      "completedAt": "2026-04-12T10:23:49.500Z"
    },
    "frameExtraction": {
      "status": "complete",
      "startedAt": "2026-04-12T10:23:45.500Z",
      "completedAt": "2026-04-12T10:23:47.000Z"
    },
    "synthesis": {
      "status": "pending"
    },
    "lastUpdated": "2026-04-12T10:23:51.000Z",
    "lastError": null
  },
  "processingTime": 6000,
  "lastError": null
}
```

***

## PATCH /api/sessions/:id — Update session

Updates one or more fields on an existing session. Only the fields you include in the request body are changed.

### Path parameter

<ParamField path="id" type="string" required>
  The session ID to update.
</ParamField>

### Request body (all fields optional)

<ParamField body="title" type="string">
  New session title. Maximum 500 characters.
</ParamField>

<ParamField body="status" type="string">
  New status. One of: `processing`, `complete`, `error`.
</ParamField>

<ParamField body="duration" type="number">
  Recording duration in seconds. Minimum 0.
</ParamField>

<ParamField body="urls" type="string[]">
  Updated list of URLs associated with the session.
</ParamField>

<ParamField body="prompt" type="string">
  Replacement prompt text.
</ParamField>

<ParamField body="agentTarget" type="string">
  New agent target. One of: `CLAUDE_CODE`, `CODEX`, `CURSOR`, `RAW`.
</ParamField>

<ParamField body="frameCount" type="number">
  Updated frame count. Minimum 0.
</ParamField>

<ParamField body="urlCount" type="number">
  Updated URL count. Minimum 0.
</ParamField>

### Response

Returns the updated [Session object](#session-object).

***

## DELETE /api/sessions/:id — Delete session

Permanently deletes a session and all associated frames. This action cannot be undone.

### Path parameter

<ParamField path="id" type="string" required>
  The session ID to delete.
</ParamField>

### Response

Returns `204 No Content` with an empty body on success.

***

## Session object

<ResponseField name="id" type="string" required>
  Unique session identifier.
</ResponseField>

<ResponseField name="userId" type="string" required>
  ID of the account that owns this session.
</ResponseField>

<ResponseField name="title" type="string" required>
  Human-readable session title.
</ResponseField>

<ResponseField name="seedUrl" type="string">
  The seed URL inspected by the Playwright lane, or `null` if not set.
</ResponseField>

<ResponseField name="status" type="string" required>
  Current session status: `processing`, `complete`, or `error`.
</ResponseField>

<ResponseField name="duration" type="number" required>
  Length of the source recording in seconds.
</ResponseField>

<ResponseField name="frameCount" type="number" required>
  Number of frames extracted from the recording.
</ResponseField>

<ResponseField name="urls" type="string[]" required>
  List of URLs that appeared in the recording.
</ResponseField>

<ResponseField name="urlCount" type="number" required>
  Count of unique URLs in the recording.
</ResponseField>

<ResponseField name="agentTarget" type="string" required>
  Agent target used when generating the prompt: `CLAUDE_CODE`, `CODEX`, `CURSOR`, or `RAW`.
</ResponseField>

<ResponseField name="processingTime" type="number" required>
  Total server-side processing time in milliseconds.
</ResponseField>

<ResponseField name="prompt" type="string" required>
  The generated agent-ready system prompt.
</ResponseField>

<ResponseField name="createdAt" type="string" required>
  ISO 8601 timestamp for when the session was created.
</ResponseField>

<ResponseField name="updatedAt" type="string" required>
  ISO 8601 timestamp for when the session was last updated.
</ResponseField>

## Frame object

<ResponseField name="id" type="string" required>
  Unique frame identifier.
</ResponseField>

<ResponseField name="sessionId" type="string" required>
  ID of the parent session.
</ResponseField>

<ResponseField name="timestamp" type="number" required>
  Position of the frame in the video, in milliseconds.
</ResponseField>

<ResponseField name="url" type="string" required>
  Browser URL at the time this frame was captured.
</ResponseField>

<ResponseField name="thumbnailUrl" type="string" required>
  Base64-encoded PNG data URL of the frame thumbnail.
</ResponseField>

<ResponseField name="diffSummary" type="object" required>
  ARIA tree diff between this frame and the previous one.

  <Expandable title="diffSummary properties">
    <ResponseField name="added" type="number">ARIA nodes added since the previous frame.</ResponseField>
    <ResponseField name="changed" type="number">ARIA nodes changed since the previous frame.</ResponseField>
    <ResponseField name="removed" type="number">ARIA nodes removed since the previous frame.</ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="ariaTree" type="ARIANode[]" required>
  ARIA accessibility tree captured for this frame. Each node has `role`, `name`, optional `children`, and an optional `diffStatus` of `added`, `changed`, or `removed`.
</ResponseField>

<ResponseField name="createdAt" type="string" required>
  ISO 8601 timestamp for when the frame record was persisted.
</ResponseField>