Sessions API — List, Get, Update, Delete

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 instead.

Request body

string

required

Human-readable title for the session. Maximum 500 characters.

string

default:"CLAUDE_CODE"

Target AI coding agent. One of: CLAUDE_CODE, CODEX, CURSOR, RAW.

number

Expected or actual number of frames. Minimum 0.

number

Expected or actual number of URLs inspected. Minimum 0.

Response

Returns a 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.

Example

curl https://api.claudescope.ai/api/sessions \
  -H "Authorization: Bearer <token>"

[
  {
    "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

number

required

Total number of sessions in your account.

number

required

Number of sessions with status: "complete".

number

required

Sum of duration (in seconds) across all completed sessions.

number

required

Average processingTime (in milliseconds) across all completed sessions.

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

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

Path parameter

string

required

The session ID, e.g. sess_ABC12345.

Response

Returns a SessionWithFrames object — a Session with an additional frames array.

Example

curl https://api.claudescope.ai/api/sessions/sess_ABC12345 \
  -H "Authorization: Bearer <token>"

{
  "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

string

required

The session ID to poll.

Response

string

required

The session ID.

string

required

High-level session status: processing, complete, or error.

object

Detailed per-lane processing state, or null if status information is not yet available.

Show processingStatus properties

string

Current pipeline stage. One of: uploading, extracting, analyzing, synthesizing, persisting, complete, error.

object

Status of the Vision AI analysis lane.

Show lane status properties

string

One of: pending, running, complete, error.

string

ISO 8601 timestamp when the lane started.

string

ISO 8601 timestamp when the lane completed.

string

Error message if the lane failed.

string

Additional human-readable detail about current lane activity.

object

Status of the Playwright ARIA inspection lane. Same shape as visionLane.

object

Status of the frame extraction step. Same shape as visionLane.

object

Status of the prompt synthesis step. Same shape as visionLane.

string

ISO 8601 timestamp of the most recent status update.

string

Most recent error message if any lane failed.

number

required

Elapsed processing time in milliseconds.

string

Top-level error message if the session failed, or null.

Example

curl https://api.claudescope.ai/api/sessions/sess_ABC12345/status \
  -H "Authorization: Bearer <token>"

{
  "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

string

required

The session ID to update.

Request body (all fields optional)

string

New session title. Maximum 500 characters.

string

New status. One of: processing, complete, error.

number

Recording duration in seconds. Minimum 0.

string[]

Updated list of URLs associated with the session.

string

Replacement prompt text.

string

New agent target. One of: CLAUDE_CODE, CODEX, CURSOR, RAW.

number

Updated frame count. Minimum 0.

number

Updated URL count. Minimum 0.

Response

Returns the updated Session object.

DELETE /api/sessions/:id — Delete session

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

Path parameter

string

required

The session ID to delete.

Response

Returns 204 No Content with an empty body on success.

Session object

string

required

Unique session identifier.

string

required

ID of the account that owns this session.

string

required

Human-readable session title.

string

The seed URL inspected by the Playwright lane, or null if not set.

string

required

Current session status: processing, complete, or error.

number

required

Length of the source recording in seconds.

number

required

Number of frames extracted from the recording.

string[]

required

List of URLs that appeared in the recording.

number

required

Count of unique URLs in the recording.

string

required

Agent target used when generating the prompt: CLAUDE_CODE, CODEX, CURSOR, or RAW.

number

required

Total server-side processing time in milliseconds.

string

required

The generated agent-ready system prompt.

string

required

ISO 8601 timestamp for when the session was created.

string

required

ISO 8601 timestamp for when the session was last updated.

Frame object

string

required

Unique frame identifier.

string

required

ID of the parent session.

number

required

Position of the frame in the video, in milliseconds.

string

required

Browser URL at the time this frame was captured.

string

required

Base64-encoded PNG data URL of the frame thumbnail.

object

required

ARIA tree diff between this frame and the previous one.

Show diffSummary properties

number

ARIA nodes added since the previous frame.

number

ARIA nodes changed since the previous frame.

number

ARIA nodes removed since the previous frame.

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.

string

required

ISO 8601 timestamp for when the frame record was persisted.

Overview

Endpoints

Sessions API — List, Get, Update, Delete

POST /api/sessions — Create a session

Request body

Response

GET /api/sessions — List sessions

Request

Response

Example

GET /api/sessions/stats — Get statistics

Request

Response

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

Path parameter

Response

Example

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

Path parameter

Response

Example

PATCH /api/sessions/:id — Update session

Path parameter

Request body (all fields optional)

Response

DELETE /api/sessions/:id — Delete session

Path parameter

Response

Session object

Frame object

​POST /api/sessions — Create a session

​Request body

​Response

​GET /api/sessions — List sessions

​Request

​Response

​Example

​GET /api/sessions/stats — Get statistics

​Request

​Response

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

​Path parameter

​Response

​Example

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

​Path parameter

​Response

​Example

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

​Path parameter

​Request body (all fields optional)

​Response

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

​Path parameter

​Response

​Session object

​Frame object

POST /api/sessions — Create a session

Request body

Response

GET /api/sessions — List sessions

Request

Response

Example

GET /api/sessions/stats — Get statistics

Request

Response

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

Path parameter

Response

Example

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

Path parameter

Response

Example

PATCH /api/sessions/:id — Update session

Path parameter

Request body (all fields optional)

Response

DELETE /api/sessions/:id — Delete session

Path parameter

Response

Session object

Frame object