> ## Documentation Index > Fetch the complete documentation index at: https://docs.lusor.ai/llms.txt > Use this file to discover all available pages before exploring further. # List sessions > Server-side filtering over the workspace's session history, newest first. `deviceId` and `status` are exact single-value matches; the filter parameters (`statuses`, `statusMode`, `nameContains`, `deviceContains`, `createdBefore`, `createdAfter`) are applied server-side so the result stays correct across `limit`/`offset` pages. ## OpenAPI ````yaml /api-reference/openapi.yaml get /v1/sessions openapi: 3.1.0 info: title: Lusor API version: 0.1.0 description: | Run AI agents on real phones, or drive a phone directly with deterministic actions. ## Authentication Every `/v1/*` endpoint except `GET /v1/health` requires an API key. Create one in the Lusor dashboard under **Settings → API Keys**. A key is shown once and is bound to one workspace. Revoking it there stops it working immediately. Send it in either header: - `X-Api-Key: ` - `Authorization: Bearer ` Because a key is bound to its workspace, `workspaceId` query and body parameters are optional for API-key callers. A request that names a different workspace returns an opaque `404`. ## Runs Use `POST /v1/agents/{id}/turns` to start or continue an agent run. Read the run under `/v1/sessions/{id}`; poll `GET /v1/sessions/{id}/status` or `GET /v1/sessions/{id}/events` for progress. ## Errors Errors are JSON: `{ "error": "", "message": "" }`. A request that fails validation returns `400` in one of two shapes, depending on the endpoint: `{ "error": "validation_error", "details": { ... } }` (direct phone control actions, for example), or `{ "error": "bad_request", "message": "" }` (agent endpoints, for example). Branch on `error`. contact: name: Lusor url: https://lusor.ai license: name: Proprietary url: https://lusor.ai/terms servers: - url: https://api.lusor.ai description: Production security: - ApiKey: [] - BearerAuth: [] tags: - name: Agents description: Persistent agents, the phone each one uses, and their turns (runs). - name: Secrets description: | Secrets saved in a workspace (passwords, sign-in details). A run uses them by name through `secrets`; values never travel in a request. - name: Sessions description: | Run records: list, inspect, stop, and read events and artifacts. Start a run with `POST /v1/agents/{id}/turns`, or without an agent through `POST /v1/workspaces/{workspaceId}/devices/{deviceId}/sessions`. - name: LiveView description: | View-only WebRTC live view of a session's phone: signaling, ICE servers, and stream control. API keys get live view only on the customer's own phone, not on a Lusor Phone. - name: Devices description: | The phones in your workspace, and reads of their current screen and UI tree. - name: DeviceVerbs description: | Direct phone control: deterministic actions (tap, swipe, type, key, clear, back, home, recent, screenshot, apps/start, apps/stop) and chains of them. On a Lusor Phone, API-key calls meter phone minutes. - name: Shell description: | Restricted shell escape hatch. Commands are checked against a denylist and audit-logged. No command output is returned. - name: Datasets description: Lists a run produced, saved as reusable Datasets. - name: Skills description: Reusable automation skills (Markdown documents). - name: PhoneNumbers description: | Workspace phone numbers and their stored SMS messages. Read-only for API keys. - name: Emails description: | Workspace Agent Mail addresses and stored inbound mail. Read-only: there is no compose, reply, or send endpoint, and message bodies are returned as raw plain text without HTML execution, remote asset fetches, or code extraction. - name: Workspaces description: The workspace an API key is bound to. - name: Catalog description: The catalog of apps that can be installed on a Lusor Phone. - name: Health description: Service health check. paths: /v1/sessions: get: tags: - Sessions summary: List sessions description: | Server-side filtering over the workspace's session history, newest first. `deviceId` and `status` are exact single-value matches; the filter parameters (`statuses`, `statusMode`, `nameContains`, `deviceContains`, `createdBefore`, `createdAfter`) are applied server-side so the result stays correct across `limit`/`offset` pages. operationId: listSessions parameters: - $ref: '#/components/parameters/WorkspaceIdQuery' - name: deviceId in: query description: Exact device id match. schema: type: string minLength: 1 - name: status in: query description: | Exact single-status match, applied verbatim (not filtered to the known vocabulary). Use `statuses` for a multi-status include/exclude filter. schema: type: string minLength: 1 - name: statuses in: query description: | Comma-separated list of DB statuses, included or excluded per `statusMode`. Entries outside the known vocabulary (`queued`, `running`, `executing`, `awaiting_human`, `completed`, `complete`, `cancelled`, `failed`) are dropped silently — an unrecognised spelling filters nothing rather than failing the request. schema: type: string minLength: 1 - name: statusMode in: query description: | Applies to `statuses` only. `include` = "is" / "is any of"; `exclude` = "is not" / "is not any of". schema: type: string enum: - include - exclude default: include - name: nameContains in: query description: | Case-insensitive substring matched against the user-set name OR the first prompt. Both columns are tested on every request — the prompt is a second match source, not only a fallback for a session with no name set. The value is sanitized before it is matched: `,`, `(`, `)` and `"` are replaced with spaces, because those characters are reserved by the filter expression the term is embedded in — so `foo,bar` matches `foo bar`, not a stored `foo,bar`. A term consisting only of substituted characters sanitizes to empty, and the filter is then skipped: the listing is returned unfiltered rather than as an empty result. schema: type: string minLength: 1 maxLength: 200 - name: deviceContains in: query description: | Case-insensitive substring over the device name OR its id. schema: type: string minLength: 1 maxLength: 200 - name: createdBefore in: query description: | Exclusive upper bound on `created_at`, as a UTC instant with an uppercase `Z` suffix. Seconds and fractional seconds are optional, matching the handler (`2026-09-13T12:00Z`, `2026-09-13T12:00:00Z`, `2026-09-13T12:00:00.5Z`). A numeric offset such as `+02:00` — valid RFC 3339, but rejected by the handler — and any other malformed value are a 400. The `pattern` cannot express month lengths, so a nonexistent calendar date such as `2026-02-29T12:00:00Z` still matches it even though the handler rejects that request; no other keyword on this parameter rejects it either. schema: type: string pattern: >- ^\d{4}-(0[1-9]|1[0-2])-(0[1-9]|[12]\d|3[01])T([01]\d|2[0-3]):[0-5]\d(:[0-5]\d(\.\d+)?)?Z$ - name: createdAfter in: query description: | Inclusive lower bound on `created_at`, as a UTC instant with an uppercase `Z` suffix. Seconds and fractional seconds are optional, matching the handler (`2026-09-13T12:00Z`, `2026-09-13T12:00:00Z`, `2026-09-13T12:00:00.5Z`). A numeric offset such as `+02:00` — valid RFC 3339, but rejected by the handler — and any other malformed value are a 400. The `pattern` cannot express month lengths, so a nonexistent calendar date such as `2026-02-29T12:00:00Z` still matches it even though the handler rejects that request; no other keyword on this parameter rejects it either. schema: type: string pattern: >- ^\d{4}-(0[1-9]|1[0-2])-(0[1-9]|[12]\d|3[01])T([01]\d|2[0-3]):[0-5]\d(:[0-5]\d(\.\d+)?)?Z$ - name: limit in: query schema: type: integer minimum: 1 maximum: 200 default: 50 - name: offset in: query schema: type: integer minimum: 0 default: 0 responses: '200': description: Session list content: application/json: schema: type: object properties: data: type: array items: $ref: '#/components/schemas/SessionV2' required: - data '400': description: | Either no workspace context could be resolved from the query string or the API key binding — returned as `{ error, message }`; or a query parameter failed validation — returned as `{ error, details }`. content: application/json: schema: anyOf: - $ref: '#/components/schemas/ErrorResponse' - $ref: '#/components/schemas/ValidationErrorResponse' components: parameters: WorkspaceIdQuery: name: workspaceId in: query required: false schema: type: string format: uuid description: | Workspace the request is scoped to. Optional for API keys: a key is bound to one workspace when it is created, and naming any other workspace returns an opaque 404. schemas: SessionV2: type: object required: - id - prompt - status - createdAt properties: id: type: string prompt: type: string status: $ref: '#/components/schemas/SessionStatusV2' deviceId: type: - string - 'null' workspaceId: type: - string - 'null' format: uuid app: type: - string - 'null' outputSchema: type: - object - 'null' additionalProperties: true output: oneOf: - type: object additionalProperties: true - type: array items: {} - type: 'null' description: | Structured output. Populated when `status == completed`. Shape is caller-defined via `outputSchema` on session create. error: type: - string - 'null' description: | Machine-readable failure code when `status == failed`. Known code: `secret_required:` - a run created with an API key needed a credential or 2FA code (`` is the agent's slug for it, for example `gmail_password`) that it was not given. The run ends immediately rather than waiting for a human. Save the secret in the workspace, then retry the run naming it in `secrets` (`.`). Dashboard runs never fail this way: they pause in `awaiting_human` and are answered in the dashboard. Known code: `credits_exhausted` - the run's model cost reached the workspace's credit balance at the time the run started, so it stopped; upgrade the plan or buy a credit pack, then continue the session. createdAt: type: string format: date-time startedAt: type: - string - 'null' format: date-time completedAt: type: - string - 'null' format: date-time maxDurationSecs: type: - integer - 'null' format: int64 description: >- Effective per-session duration cap in seconds as persisted by the API at session creation. Null means a historical row has no persisted cap; consumers must not infer the current default from null. ErrorResponse: type: object required: - error - message properties: error: type: string message: type: string ValidationErrorResponse: type: object required: - error - details properties: error: type: string example: validation_error details: type: object additionalProperties: true SessionStatusV2: type: string enum: - queued - running - executing - awaiting_human - complete - completed - failed - cancelled securitySchemes: ApiKey: type: apiKey in: header name: X-Api-Key description: Workspace API key, created in the dashboard under Settings → API Keys. BearerAuth: type: http scheme: bearer description: >- The same workspace API key, sent as `Authorization: Bearer `. ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.