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

title

string

required

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

agentTarget

string

default:"CLAUDE_CODE"

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

frameCount

number

Expected or actual number of frames. Minimum 0.

urlCount

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

totalSessions

number

required

Total number of sessions in your account.

completedSessions

number

required

Number of sessions with status: "complete".

totalDuration

number

required

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

avgProcessingTime

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

sessionId

string

required

The session ID.

sessionStatus

string

required

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

processingStatus

object

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

Show processingStatus properties

overallStage

string

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

visionLane

object

Status of the Vision AI analysis lane.

Show lane status properties

status

string

One of: pending, running, complete, error.

startedAt

string

ISO 8601 timestamp when the lane started.

completedAt

string

ISO 8601 timestamp when the lane completed.

error

string

Error message if the lane failed.

detail

string

Additional human-readable detail about current lane activity.

playwrightLane

object

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

frameExtraction

object

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

synthesis

object

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

lastUpdated

string

ISO 8601 timestamp of the most recent status update.

lastError

string

Most recent error message if any lane failed.

processingTime

number

required

Elapsed processing time in milliseconds.

lastError

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)

title

string

New session title. Maximum 500 characters.

status

string

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

duration

number

Recording duration in seconds. Minimum 0.

urls

string[]

Updated list of URLs associated with the session.

prompt

string

Replacement prompt text.

agentTarget

string

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

frameCount

number

Updated frame count. Minimum 0.

urlCount

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.

userId

string

required

ID of the account that owns this session.

title

string

required

Human-readable session title.

seedUrl

string

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

status

string

required

Current session status: processing, complete, or error.

duration

number

required

Length of the source recording in seconds.

frameCount

number

required

Number of frames extracted from the recording.

urls

string[]

required

List of URLs that appeared in the recording.

urlCount

number

required

Count of unique URLs in the recording.

agentTarget

string

required

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

processingTime

number

required

Total server-side processing time in milliseconds.

prompt

string

required

The generated agent-ready system prompt.

createdAt

string

required

ISO 8601 timestamp for when the session was created.

updatedAt

string

required

ISO 8601 timestamp for when the session was last updated.

Frame object

string

required

Unique frame identifier.

sessionId

string

required

ID of the parent session.

timestamp

number

required

Position of the frame in the video, in milliseconds.

url

string

required

Browser URL at the time this frame was captured.

thumbnailUrl

string

required

Base64-encoded PNG data URL of the frame thumbnail.

diffSummary

object

required

ARIA tree diff between this frame and the previous one.

Show diffSummary properties

added

number

ARIA nodes added since the previous frame.

changed

number

ARIA nodes changed since the previous frame.

removed

number

ARIA nodes removed since the previous frame.

ariaTree

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.

createdAt

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

Overview

Endpoints

​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