> For the complete documentation index, see [llms.txt](https://help.aximo.autify.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://help.aximo.autify.com/api-reference/sessions.md).
# Sessions
Create and monitor AI test sessions.
## List sessions
> Returns sessions visible to your organization, newest first.\
> Filter by project, test case, or status. Results are paginated.\
> Archived (soft-deleted) sessions are excluded; they remain readable via\
> \`GET /api/sessions/{sessionId}\`, flagged by \`archivedAt\`.
```json
{"openapi":"3.0.3","info":{"title":"Aximo API","version":"1.0.0"},"tags":[{"name":"Sessions","description":"Create and monitor AI test sessions."}],"servers":[{"url":"/","description":"Current environment"}],"security":[{"ApiKeyAuth":[]}],"components":{"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","in":"header","name":"x-api-key","description":"Organization API key generated from Settings → API Keys."}},"schemas":{"SessionStatus":{"type":"string","enum":["queued","created","preparing","running","succeeded","failed","terminated","error","archived"],"description":"Terminal statuses (stop polling): `succeeded`, `failed`, `terminated`, `error`, `archived`.\n"},"SessionList":{"type":"object","required":["items","totalCount","page","pageSize","totalPages"],"properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/SessionListItem"}},"totalCount":{"type":"integer"},"page":{"type":"integer"},"pageSize":{"type":"integer"},"totalPages":{"type":"integer"}}},"SessionListItem":{"type":"object","required":["id","title","prompt","platform","status","createdAt"],"properties":{"id":{"type":"string","format":"uuid"},"projectId":{"type":"string","format":"uuid","nullable":true},"caseId":{"type":"string","format":"uuid","nullable":true},"title":{"type":"string"},"prompt":{"type":"string","description":"Truncated to 200 characters."},"platform":{"$ref":"#/components/schemas/Platform"},"status":{"$ref":"#/components/schemas/SessionStatus"},"result":{"$ref":"#/components/schemas/SessionResult"},"startedAt":{"type":"string","format":"date-time","nullable":true},"completedAt":{"type":"string","format":"date-time","nullable":true},"createdAt":{"type":"string","format":"date-time"},"durationMs":{"type":"integer","nullable":true}}},"Platform":{"type":"string","enum":["desktop","android","ios"]},"SessionResult":{"type":"string","nullable":true,"enum":["passed","failed","error"]},"Error":{"type":"object","required":["error"],"properties":{"error":{"type":"string"}}}},"responses":{"Unauthorized":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"RateLimited":{"description":"Rate limit exceeded — e.g. the daily session limit was reached for the\norganization, or too many API requests were sent in a short window\n(retry after the number of seconds in the `Retry-After` header).\n","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"InternalError":{"description":"Unexpected server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"paths":{"/api/sessions":{"get":{"operationId":"listSessions","summary":"List sessions","description":"Returns sessions visible to your organization, newest first.\nFilter by project, test case, or status. Results are paginated.\nArchived (soft-deleted) sessions are excluded; they remain readable via\n`GET /api/sessions/{sessionId}`, flagged by `archivedAt`.\n","tags":["Sessions"],"parameters":[{"name":"projectId","in":"query","schema":{"type":"string","format":"uuid"},"description":"Filter by workspace."},{"name":"caseId","in":"query","schema":{"type":"string","format":"uuid"},"description":"Filter to sessions linked to a specific test case."},{"name":"status","in":"query","schema":{"$ref":"#/components/schemas/SessionStatus"}},{"name":"page","in":"query","schema":{"type":"integer","minimum":1,"default":1}},{"name":"pageSize","in":"query","schema":{"type":"integer","minimum":1,"maximum":100,"default":25}}],"responses":{"200":{"description":"Paginated session list.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SessionList"}}}},"400":{"description":"Invalid query parameters.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"description":"The API key's user is banned or no longer a member of the organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/InternalError"}}}}}}
```
## Create a session
> Triggers a new AI test session and returns its ID. The session is queued immediately\
> and will begin executing as soon as a worker is available.\
> \
> Poll \`GET /api/sessions/{sessionId}\` until \`status\` reaches a terminal value:\
> \`succeeded\`, \`failed\`, \`terminated\`, \`error\`, or \`archived\`.
```json
{"openapi":"3.0.3","info":{"title":"Aximo API","version":"1.0.0"},"tags":[{"name":"Sessions","description":"Create and monitor AI test sessions."}],"servers":[{"url":"/","description":"Current environment"}],"security":[{"ApiKeyAuth":[]}],"components":{"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","in":"header","name":"x-api-key","description":"Organization API key generated from Settings → API Keys."}},"schemas":{"Platform":{"type":"string","enum":["desktop","android","ios"]},"RunRequestError":{"type":"object","required":["error"],"properties":{"error":{"type":"string"},"availableModels":{"type":"array","items":{"type":"string"},"description":"Present when the request was rejected for its `model`: the models this\norganization can run, the same list `GET /api/models` returns.\n"}}},"Error":{"type":"object","required":["error"],"properties":{"error":{"type":"string"}}}},"responses":{"Unauthorized":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"RateLimited":{"description":"Rate limit exceeded — e.g. the daily session limit was reached for the\norganization, or too many API requests were sent in a short window\n(retry after the number of seconds in the `Retry-After` header).\n","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"InternalError":{"description":"Unexpected server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"paths":{"/api/sessions":{"post":{"operationId":"createSession","summary":"Create a session","description":"Triggers a new AI test session and returns its ID. The session is queued immediately\nand will begin executing as soon as a worker is available.\n\nPoll `GET /api/sessions/{sessionId}` until `status` reaches a terminal value:\n`succeeded`, `failed`, `terminated`, `error`, or `archived`.\n","tags":["Sessions"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["title","prompt","projectId"],"properties":{"title":{"type":"string","minLength":1,"maxLength":500,"description":"Session title."},"prompt":{"type":"string","minLength":1,"maxLength":10000,"description":"Test instructions for the AI agent."},"projectId":{"type":"string","format":"uuid","description":"ID of the workspace to run the session under."},"platform":{"$ref":"#/components/schemas/Platform","default":"desktop"},"model":{"type":"string","enum":["haiku","sonnet","kimi","gpt-5.4","gpt-5.4-mini","gpt-5.5","auto"],"description":"Model to use for this session. Call `GET /api/models` for the values\nyour organization can run — anything else is rejected with `400`, and\nthe error carries the usable list in `availableModels`. When omitted,\nthe `defaultModel` from that endpoint applies.\n"},"startUrl":{"type":"string","format":"uri","description":"Starting URL for desktop sessions."},"caseId":{"type":"string","format":"uuid","description":"Link this session to an existing test case."},"tags":{"type":"array","maxItems":10,"items":{"type":"string","maxLength":64},"default":[],"description":"Labels for filtering sessions."},"interactiveMode":{"type":"boolean","default":false,"description":"Run the session in interactive mode: when the instructions are too\nvague to complete without guessing, the agent pauses and asks a\nclarifying question (answered from the session view in the dashboard)\ninstead of proceeding.\n"},"hostnameOverrideIds":{"type":"array","items":{"type":"string","format":"uuid"},"description":"IDs of hostname overrides to apply for this session. Overrides are\nresolved against the workspace's configured hostname overrides;\nunknown IDs are ignored.\n"},"deviceArn":{"type":"string","description":"Encrypted device token from `GET /api/devices`. Required for mobile sessions unless `userDeviceId` is set (local devices never use a Device Farm token)."},"deviceName":{"type":"string","description":"Human-readable device name (mobile only)."},"uploadArn":{"type":"string","description":"Encrypted upload token from `GET /api/uploads/{id}`. Required for mobile sessions with own app."},"uploadType":{"type":"string","enum":["own_app","existing","sample"],"description":"App source type (mobile only)."},"appName":{"type":"string","description":"Display name of the app used in test instructions (mobile only)."},"bundleId":{"type":"string","description":"App bundle identifier (mobile only)."},"userDeviceId":{"type":"string","format":"uuid","description":"Run the session on a registered local device (BYOD) instead of\nAWS Device Farm — a desktop machine or a locally connected phone\nregistered via `POST /api/devices/register`. Cannot be combined\nwith `deviceArn`/`deviceName`. Requires the BYOD feature to be\nenabled for your organization.\n"},"apps":{"type":"array","maxItems":3,"description":"Up to 3 apps to install for a mobile session. Takes precedence over the\nsingle-app fields (`uploadArn`/`uploadType`/`appName`/`bundleId`); the\nfirst entry is the primary app.\n","items":{"type":"object","required":["uploadArn","uploadType","appName"],"properties":{"uploadArn":{"type":"string","description":"Encrypted upload token from `GET /api/uploads/{id}`."},"uploadType":{"type":"string","enum":["own_app","existing","sample"]},"appName":{"type":"string","nullable":true},"bundleId":{"type":"string"}}}}}}}}},"responses":{"201":{"description":"Session created and queued.","content":{"application/json":{"schema":{"type":"object","required":["success","sessionId"],"properties":{"success":{"type":"boolean"},"sessionId":{"type":"string","format":"uuid"}}}}}},"400":{"description":"Invalid request body — including a `model` this organization cannot run\n(the response then carries `availableModels`), combining `userDeviceId`\nwith `deviceArn`/`deviceName`, a local device whose platform does not\nmatch the session platform, or a local-device app reference\n(`uploadArn`/`apps`) supplied without a `bundleId` to launch it.\n","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RunRequestError"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"description":"Forbidden — `userDeviceId` used while BYOD is not enabled for the\norganization, or the API key is not organization-scoped, or its owner\nis banned or no longer a member of the organization.\n","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Project, upload, or user device not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/InternalError"}}}}}}
```
## Get session status
> Returns the current state and full results of a session. Poll this endpoint\
> until \`status\` is a terminal value.\
> \
> \*\*Terminal statuses\*\* (stop polling): \`succeeded\`, \`failed\`, \`terminated\`, \`error\`, \`archived\`.
```json
{"openapi":"3.0.3","info":{"title":"Aximo API","version":"1.0.0"},"tags":[{"name":"Sessions","description":"Create and monitor AI test sessions."}],"servers":[{"url":"/","description":"Current environment"}],"security":[{"ApiKeyAuth":[]}],"components":{"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","in":"header","name":"x-api-key","description":"Organization API key generated from Settings → API Keys."}},"schemas":{"Session":{"type":"object","required":["id","title","prompt","platform","model","status","tags","screenshotsCount","toolCount","failedToolCount","llmCallCount","createdAt"],"properties":{"id":{"type":"string","format":"uuid"},"title":{"type":"string"},"prompt":{"type":"string"},"platform":{"$ref":"#/components/schemas/Platform"},"model":{"type":"string","enum":["default","haiku","sonnet","opus","kimi","gpt-5.4","gpt-5.4-mini","gpt-5.5","auto"]},"status":{"$ref":"#/components/schemas/SessionStatus"},"result":{"$ref":"#/components/schemas/SessionResult"},"summary":{"type":"string","nullable":true,"description":"AI-generated summary of what happened during the session."},"observations":{"type":"array","nullable":true,"items":{"type":"object","properties":{"description":{"type":"string"},"messageId":{"type":"string"}}}},"tags":{"type":"array","items":{"type":"string"}},"screenshotsCount":{"type":"integer"},"toolCount":{"type":"integer"},"failedToolCount":{"type":"integer"},"llmCallCount":{"type":"integer"},"creditsUsed":{"type":"number","nullable":true,"description":"Credits consumed by this session."},"startedAt":{"type":"string","format":"date-time","nullable":true},"completedAt":{"type":"string","format":"date-time","nullable":true},"duration":{"type":"integer","nullable":true,"description":"Execution duration in milliseconds."},"createdAt":{"type":"string","format":"date-time"},"archivedAt":{"type":"string","format":"date-time","nullable":true,"description":"Set when the session was archived (soft-deleted). Archived sessions are excluded from lists but stay readable by id."},"mobileSession":{"$ref":"#/components/schemas/MobileSession"}}},"Platform":{"type":"string","enum":["desktop","android","ios"]},"SessionStatus":{"type":"string","enum":["queued","created","preparing","running","succeeded","failed","terminated","error","archived"],"description":"Terminal statuses (stop polling): `succeeded`, `failed`, `terminated`, `error`, `archived`.\n"},"SessionResult":{"type":"string","nullable":true,"enum":["passed","failed","error"]},"MobileSession":{"type":"object","nullable":true,"properties":{"deviceArn":{"type":"string","description":"Encrypted device identifier token."},"deviceName":{"type":"string"},"devicePlatform":{"type":"string"},"uploadArn":{"type":"string","nullable":true,"description":"Encrypted upload identifier token."},"uploadType":{"type":"string","nullable":true,"enum":["own_app","existing","sample"]},"appName":{"type":"string","nullable":true},"bundleId":{"type":"string","nullable":true}}},"Error":{"type":"object","required":["error"],"properties":{"error":{"type":"string"}}}},"responses":{"Unauthorized":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"RateLimited":{"description":"Rate limit exceeded — e.g. the daily session limit was reached for the\norganization, or too many API requests were sent in a short window\n(retry after the number of seconds in the `Retry-After` header).\n","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"InternalError":{"description":"Unexpected server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"paths":{"/api/sessions/{sessionId}":{"get":{"operationId":"getSession","summary":"Get session status","description":"Returns the current state and full results of a session. Poll this endpoint\nuntil `status` is a terminal value.\n\n**Terminal statuses** (stop polling): `succeeded`, `failed`, `terminated`, `error`, `archived`.\n","tags":["Sessions"],"parameters":[{"name":"sessionId","in":"path","required":true,"schema":{"type":"string","format":"uuid"},"description":"Session UUID returned by `POST /api/sessions`."}],"responses":{"200":{"description":"Session details.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Session"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"description":"Session not found or belongs to another organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/InternalError"}}}}}}
```
## Get session messages
> Returns the message timeline (tool calls, assistant text, user input) for a\
> session. Cursor-paginated; pass \`nextCursor\` to fetch subsequent pages.
```json
{"openapi":"3.0.3","info":{"title":"Aximo API","version":"1.0.0"},"tags":[{"name":"Sessions","description":"Create and monitor AI test sessions."}],"servers":[{"url":"/","description":"Current environment"}],"security":[{"ApiKeyAuth":[]}],"components":{"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","in":"header","name":"x-api-key","description":"Organization API key generated from Settings → API Keys."}},"schemas":{"SessionMessagesPage":{"type":"object","required":["items"],"properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/SessionMessage"}},"nextCursor":{"type":"string","nullable":true,"description":"Pass as `cursor` on the next request. `null` when no more pages."}}},"SessionMessage":{"type":"object","required":["id","role","content","createdAt"],"properties":{"id":{"type":"string","format":"uuid"},"role":{"type":"string","description":"One of `user`, `assistant`, `system`, `tool`."},"content":{"type":"string"},"metadata":{"type":"object","nullable":true,"description":"Tool-call metadata when `role` is `tool` or `assistant`. Common keys:\n`toolName`, `toolInput`, `toolOutput`, `toolCallId`, `toolCalls`.\n\nOn the first `user` message, `rewritten: true` indicates `content` is\nthe AI-normalized form of the user's prompt (restructured into ordered\nsteps); `originalPrompt` then holds the user's exact text. User messages\nrejected by safety review carry `rejected`, `verdict`, and\n`rejectionReason`.\n","additionalProperties":true},"createdAt":{"type":"string","format":"date-time"}}},"Error":{"type":"object","required":["error"],"properties":{"error":{"type":"string"}}}},"responses":{"Unauthorized":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"RateLimited":{"description":"Rate limit exceeded — e.g. the daily session limit was reached for the\norganization, or too many API requests were sent in a short window\n(retry after the number of seconds in the `Retry-After` header).\n","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"InternalError":{"description":"Unexpected server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"paths":{"/api/sessions/{sessionId}/messages":{"get":{"operationId":"getSessionMessages","summary":"Get session messages","description":"Returns the message timeline (tool calls, assistant text, user input) for a\nsession. Cursor-paginated; pass `nextCursor` to fetch subsequent pages.\n","tags":["Sessions"],"parameters":[{"name":"sessionId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"cursor","in":"query","schema":{"type":"string"},"description":"Cursor returned by a prior call (`nextCursor`)."},{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":100,"default":50}},{"name":"order","in":"query","schema":{"type":"string","enum":["asc","desc"],"default":"asc"}}],"responses":{"200":{"description":"Paginated messages.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SessionMessagesPage"}}}},"400":{"description":"Invalid query parameters.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"description":"Session not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/InternalError"}}}}}}
```
## Get session screenshots
> Returns screenshots captured during a session, ordered by capture time.\
> URLs are presigned (expire after 1 hour for S3) or relative paths.
```json
{"openapi":"3.0.3","info":{"title":"Aximo API","version":"1.0.0"},"tags":[{"name":"Sessions","description":"Create and monitor AI test sessions."}],"servers":[{"url":"/","description":"Current environment"}],"security":[{"ApiKeyAuth":[]}],"components":{"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","in":"header","name":"x-api-key","description":"Organization API key generated from Settings → API Keys."}},"schemas":{"SessionScreenshotsPage":{"type":"object","required":["items"],"properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/SessionScreenshot"}},"nextCursor":{"type":"string","nullable":true}}},"SessionScreenshot":{"type":"object","required":["id","url","capturedAt"],"properties":{"id":{"type":"string","format":"uuid"},"url":{"type":"string","description":"Resolved screenshot URL. May be a presigned S3 URL (expires in 1 hour),\na relative `/api/screenshots/...` path, or a `data:` URI.\n"},"messageId":{"type":"string","format":"uuid","nullable":true},"width":{"type":"integer","nullable":true},"height":{"type":"integer","nullable":true},"resizedWidth":{"type":"integer","nullable":true},"resizedHeight":{"type":"integer","nullable":true},"capturedAt":{"type":"string","format":"date-time"}}},"Error":{"type":"object","required":["error"],"properties":{"error":{"type":"string"}}}},"responses":{"Unauthorized":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"RateLimited":{"description":"Rate limit exceeded — e.g. the daily session limit was reached for the\norganization, or too many API requests were sent in a short window\n(retry after the number of seconds in the `Retry-After` header).\n","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"InternalError":{"description":"Unexpected server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"paths":{"/api/sessions/{sessionId}/screenshots":{"get":{"operationId":"getSessionScreenshots","summary":"Get session screenshots","description":"Returns screenshots captured during a session, ordered by capture time.\nURLs are presigned (expire after 1 hour for S3) or relative paths.\n","tags":["Sessions"],"parameters":[{"name":"sessionId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"cursor","in":"query","schema":{"type":"string"}},{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":100,"default":50}},{"name":"order","in":"query","schema":{"type":"string","enum":["asc","desc"],"default":"asc"}}],"responses":{"200":{"description":"Paginated screenshots.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SessionScreenshotsPage"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"description":"Session not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/InternalError"}}}}}}
```
## Get session timeline
> Returns the merged step timeline: each step combines a message (tool call,\
> assistant turn, or user input) with any screenshots captured for that step.\
> \
> This is the recommended endpoint for downstream consumers (e.g. generating\
> a Playwright spec from the session) — it gives ordered, paired data without\
> having to join messages and screenshots manually.
```json
{"openapi":"3.0.3","info":{"title":"Aximo API","version":"1.0.0"},"tags":[{"name":"Sessions","description":"Create and monitor AI test sessions."}],"servers":[{"url":"/","description":"Current environment"}],"security":[{"ApiKeyAuth":[]}],"components":{"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","in":"header","name":"x-api-key","description":"Organization API key generated from Settings → API Keys."}},"schemas":{"SessionTimeline":{"type":"object","required":["sessionId","stepCount","steps"],"properties":{"sessionId":{"type":"string","format":"uuid"},"stepCount":{"type":"integer"},"steps":{"type":"array","items":{"$ref":"#/components/schemas/TimelineStep"}}}},"TimelineStep":{"type":"object","required":["index","messageId","role","createdAt","screenshots"],"properties":{"index":{"type":"integer"},"messageId":{"type":"string"},"role":{"type":"string"},"toolName":{"type":"string","nullable":true},"toolInput":{"nullable":true,"description":"Tool call arguments (shape depends on tool)."},"toolOutput":{"nullable":true},"text":{"type":"string","nullable":true},"rewritten":{"type":"boolean","description":"True when `text` is the AI-normalized form of the user's prompt\n(restructured into ordered steps). Only present on the first user step.\n"},"originalPrompt":{"type":"string","description":"The user's exact prompt text. Present when `rewritten` is true."},"createdAt":{"type":"string","format":"date-time"},"screenshots":{"type":"array","items":{"$ref":"#/components/schemas/SessionScreenshot"}}}},"SessionScreenshot":{"type":"object","required":["id","url","capturedAt"],"properties":{"id":{"type":"string","format":"uuid"},"url":{"type":"string","description":"Resolved screenshot URL. May be a presigned S3 URL (expires in 1 hour),\na relative `/api/screenshots/...` path, or a `data:` URI.\n"},"messageId":{"type":"string","format":"uuid","nullable":true},"width":{"type":"integer","nullable":true},"height":{"type":"integer","nullable":true},"resizedWidth":{"type":"integer","nullable":true},"resizedHeight":{"type":"integer","nullable":true},"capturedAt":{"type":"string","format":"date-time"}}},"Error":{"type":"object","required":["error"],"properties":{"error":{"type":"string"}}}},"responses":{"Unauthorized":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"RateLimited":{"description":"Rate limit exceeded — e.g. the daily session limit was reached for the\norganization, or too many API requests were sent in a short window\n(retry after the number of seconds in the `Retry-After` header).\n","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"InternalError":{"description":"Unexpected server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"paths":{"/api/sessions/{sessionId}/timeline":{"get":{"operationId":"getSessionTimeline","summary":"Get session timeline","description":"Returns the merged step timeline: each step combines a message (tool call,\nassistant turn, or user input) with any screenshots captured for that step.\n\nThis is the recommended endpoint for downstream consumers (e.g. generating\na Playwright spec from the session) — it gives ordered, paired data without\nhaving to join messages and screenshots manually.\n","tags":["Sessions"],"parameters":[{"name":"sessionId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Session timeline.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SessionTimeline"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"description":"Session not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/InternalError"}}}}}}
```
## Get session capture metadata
> Returns CDP-derived capture metadata recorded during a session: ordered\
> events (actions, navigations, network XHR/fetch, console, exceptions,\
> snapshot triggers), the browser context, and the post-session storage\
> state. Only available when the organization has the CDP capture feature\
> flag enabled and the session ran on the desktop VM.\
> \
> \`404\` is returned when no capture exists for the session.
```json
{"openapi":"3.0.3","info":{"title":"Aximo API","version":"1.0.0"},"tags":[{"name":"Sessions","description":"Create and monitor AI test sessions."}],"servers":[{"url":"/","description":"Current environment"}],"security":[{"ApiKeyAuth":[]}],"components":{"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","in":"header","name":"x-api-key","description":"Organization API key generated from Settings → API Keys."}},"schemas":{"SessionCapture":{"type":"object","required":["sessionId","platform","snapshotCount","truncated"],"properties":{"sessionId":{"type":"string","format":"uuid"},"platform":{"type":"string"},"startedAt":{"type":"string","format":"date-time","nullable":true},"endedAt":{"type":"string","format":"date-time","nullable":true},"browserContext":{"type":"object","nullable":true,"description":"UA, viewport, locale, timezone captured at session start.","additionalProperties":true},"events":{"type":"array","description":"Ordered, timestamped events: action_started/completed,\npage_navigated, page_lifecycle, request, response, console,\nexception, dialog_opened, snapshot_captured, target_attached,\ntarget_detached.\n","items":{"type":"object","required":["type","ts"],"properties":{"type":{"type":"string"},"ts":{"type":"integer","description":"Epoch millis (Date.now()) when the event was recorded inside the VM."}},"additionalProperties":true}},"storageState":{"type":"object","nullable":true,"description":"Cookies and localStorage captured at session end.","additionalProperties":true},"snapshotCount":{"type":"integer","description":"Number of DOM+AX snapshots captured (one per `screenshot` tool call and per page-load)."},"snapshotsPrefix":{"type":"string","nullable":true,"description":"S3 prefix for snapshot blobs. Null while snapshots are persisted inline."},"snapshots":{"type":"array","description":"Inline DOM + accessibility-tree snapshots, in capture order. Each\nentry pairs a pixel-level event (a `screenshot` tool call or a\n`Page.lifecycleEvent: load`) with the structural state of the page\nat that moment. Large — expect single-MB responses on long\nsessions.\n","items":{"type":"object","required":["id","ts","trigger","targetId","url"],"properties":{"id":{"type":"string","format":"uuid"},"ts":{"type":"integer","description":"Epoch ms when the snapshot was taken"},"messageId":{"type":"string","format":"uuid","nullable":true,"description":"AgentMessage that triggered the snapshot, when trigger was `screenshot`."},"trigger":{"type":"string","enum":["screenshot","page_load"]},"targetId":{"type":"string","description":"CDP target (tab/iframe) id"},"url":{"type":"string"},"title":{"type":"string"},"dom":{"description":"DOMSnapshot.captureSnapshot payload (computed styles excluded for size)."},"axTree":{"description":"Accessibility.getFullAXTree payload — what `getByRole`/`getByLabel` index into."}}}},"truncated":{"type":"boolean","description":"True if the event buffer reached its cap and dropped tail events."},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}}},"Error":{"type":"object","required":["error"],"properties":{"error":{"type":"string"}}}},"responses":{"Unauthorized":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"RateLimited":{"description":"Rate limit exceeded — e.g. the daily session limit was reached for the\norganization, or too many API requests were sent in a short window\n(retry after the number of seconds in the `Retry-After` header).\n","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"InternalError":{"description":"Unexpected server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"paths":{"/api/sessions/{sessionId}/capture":{"get":{"operationId":"getSessionCapture","summary":"Get session capture metadata","description":"Returns CDP-derived capture metadata recorded during a session: ordered\nevents (actions, navigations, network XHR/fetch, console, exceptions,\nsnapshot triggers), the browser context, and the post-session storage\nstate. Only available when the organization has the CDP capture feature\nflag enabled and the session ran on the desktop VM.\n\n`404` is returned when no capture exists for the session.\n","tags":["Sessions"],"parameters":[{"name":"sessionId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"includeSnapshots","in":"query","required":false,"description":"Controls how `snapshots[]` is returned.\n- `none`: empty array.\n- `metadata` (default): each entry has `id`, `ts`, `messageId`,\n `trigger`, `targetId`, `url`, `title`, `domBytes`, `axBytes` —\n fetch full content per-snapshot via\n `GET /api/sessions/{id}/snapshots/{snapshotId}`.\n- `full`: includes the full `dom` and `axTree` inline (can be\n multi-MB; avoid for routine MCP/agent calls).\n","schema":{"type":"string","enum":["none","metadata","full"],"default":"metadata"}}],"responses":{"200":{"description":"Session capture blob.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SessionCapture"}}}},"400":{"description":"Invalid query parameter (e.g. unknown `includeSnapshots` value).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"description":"Session or capture not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/InternalError"}}}}}}
```
## Get one DOM + AX snapshot
> Returns a single snapshot by id (one entry from \`snapshots\[]\` on the\
> capture). Use this when the capture blob would be too large and you\
> only need one page's structure.
```json
{"openapi":"3.0.3","info":{"title":"Aximo API","version":"1.0.0"},"tags":[{"name":"Sessions","description":"Create and monitor AI test sessions."}],"servers":[{"url":"/","description":"Current environment"}],"security":[{"ApiKeyAuth":[]}],"components":{"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","in":"header","name":"x-api-key","description":"Organization API key generated from Settings → API Keys."}},"responses":{"Unauthorized":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"RateLimited":{"description":"Rate limit exceeded — e.g. the daily session limit was reached for the\norganization, or too many API requests were sent in a short window\n(retry after the number of seconds in the `Retry-After` header).\n","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"InternalError":{"description":"Unexpected server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"schemas":{"Error":{"type":"object","required":["error"],"properties":{"error":{"type":"string"}}}}},"paths":{"/api/sessions/{sessionId}/snapshots/{snapshotId}":{"get":{"operationId":"getSessionSnapshot","summary":"Get one DOM + AX snapshot","description":"Returns a single snapshot by id (one entry from `snapshots[]` on the\ncapture). Use this when the capture blob would be too large and you\nonly need one page's structure.\n","tags":["Sessions"],"parameters":[{"name":"sessionId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"snapshotId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Single snapshot.","content":{"application/json":{"schema":{"type":"object","required":["id","ts","trigger","targetId","url"],"properties":{"id":{"type":"string","format":"uuid"},"ts":{"type":"integer"},"messageId":{"type":"string","format":"uuid","nullable":true},"trigger":{"type":"string","enum":["screenshot","page_load"]},"targetId":{"type":"string"},"url":{"type":"string"},"title":{"type":"string"},"dom":{"description":"DOMSnapshot.captureSnapshot payload"},"axTree":{"description":"Accessibility.getFullAXTree payload"}}}}}},"400":{"description":"Invalid sessionId or snapshotId."},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"description":"Session, capture or snapshot not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/InternalError"}}}}}}
```