> ## Documentation Index
> Fetch the complete documentation index at: https://docs.mirage.strukto.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# List workspace logs

List completed commands with captured output and related file operations, newest first.

Use `limit` and `after` for pagination, or `format=jsonl` to export all matching commands. Log retention depends on the server.

> [accordion] Errors
>
> | Status | Meaning |
> | - | - |
> | `400` | The request is malformed: the body is not JSON (`invalid_json`) or not a JSON object, a field is missing (`missing_field`), unknown (`unknown_field`) or has a wrong value (`invalid_value`), or the request is otherwise invalid (`invalid_request`). `param` names the field at fault. |
> | `401` | The token is missing or wrong (`unauthorized`). |
> | `404` | The workspace, session, job, file or route does not exist, or the caller may not see it (`not_found`). |
> | `429` | Past a rate limit (`rate_limited`), or a new session past max\_sessions (`session_limit`). |
> | `403` | The call is refused. A policy refused it (`policy_refused`, with `decision`), a mount mode or permission refused it (`forbidden`), the backend is out of space or quota (`storage_full`), or the request came for a host or from a browser origin that is not allowed (`host_not_allowed`, `origin_not_allowed`). |
>
> See [error examples and recovery steps](https://docs.mirage.strukto.ai/api/errors.md). The [complete OpenAPI contract](https://github.com/strukto-ai/mirage/blob/main/docs/openapi.yaml) includes every response schema.


## OpenAPI

````yaml /openapi.yaml get /v1/workspaces/{workspace_id}/logs
openapi: 3.2.0
info:
  title: Mirage API
  version: '0.1'
servers:
  - url: http://127.0.0.1:8765
    description: A local server on its default port
security:
  - bearerAuth: []
tags:
  - name: Workspace operations
    x-group: Workspaces
  - name: Workspaces
    x-group: Lifecycle
    parent: Workspace operations
  - name: Sessions
  - name: Shell
    parent: Workspace operations
  - name: VFS
    parent: Workspace operations
  - name: Tools
  - name: Documents
    x-group: Agent Instructions
    parent: Workspace operations
  - name: Snapshots
  - name: Templates
    parent: Configuration
  - name: Saved VFS
    x-group: VFS
    parent: Configuration
  - name: Saved CLIs
    x-group: CLI
    parent: Configuration
  - name: Saved machines
    x-group: Machine
    parent: Configuration
  - name: Configuration
  - name: Policies
    parent: Configuration
  - name: Asks
    parent: Workspace operations
    x-group: Approval requests
  - name: Lines
    parent: Workspace operations
    x-group: Commands
  - name: Jobs
    parent: Workspace operations
  - name: Processes
    parent: Workspace operations
  - name: Machines
    parent: Workspace operations
  - name: Server
  - name: Service
    parent: Server
  - name: Daemon
    parent: Server
  - name: Auth
paths:
  /v1/workspaces/{workspace_id}/logs:
    get:
      tags:
        - Workspaces
      summary: List workspace logs
      operationId: workspace_logs_v1_workspaces__workspace_id__logs_get
      parameters:
        - $ref: '#/components/parameters/workspaceId'
        - name: session
          in: query
          description: Filter by session ID. Omit or leave empty to include all sessions.
          schema:
            type: string
        - name: limit
          in: query
          description: Maximum commands per JSON page. Ignored for JSONL export.
          schema:
            type: integer
            minimum: 1
            maximum: 200
            default: 50
        - name: after
          in: query
          description: >-
            The `next` cursor from the previous JSON page. Reuse it on the same
            server with the same filters. Results can change between pages.
            Ignored for JSONL export.
          schema:
            type: string
        - name: format
          in: query
          description: >-
            Use `json` for paginated results, newest first, or `jsonl` to export
            all retained matches oldest first. JSONL ignores `limit` and `after`
            and contains `command`, `vfs`, and `result` records linked by
            `parent`. Each record has a `timestamp`, an RFC 3339 string in UTC.
            Values other than `jsonl` select JSON.
          schema:
            type: string
            default: json
      responses:
        '200':
          description: >-
            Completed command logs. Empty JSON returns `{"items": [], "next":
            null}`; an empty JSONL export has no body.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/LogPage'
              example:
                items:
                  - id: line_019a5e2c-7b41-7c3e-9f20-4d8e1a6b5c37
                    command: echo hi
                    cwd: /
                    started_at: '2026-11-07T00:00:01.000Z'
                    duration_ms: 7
                    exit_code: 0
                    stdout: |
                      hi
                    stderr: ''
                    user_id: null
                    api_key_id: null
                    mounts: []
                next: null
            application/x-ndjson:
              schema:
                type: string
              example: >
                {"type":"command","session":"01a1b425-ec80-7038-86e0-75b597344043","timestamp":"2026-11-07T00:00:01.000Z","cwd":"/","id":"line_019a5e2c-7b41-7c3e-9f20-4d8e1a6b5c37","command":"echo
                hi"}

                {"type":"result","session":"01a1b425-ec80-7038-86e0-75b597344043","timestamp":"2026-11-07T00:00:01.007Z","cwd":"/","parent":"line_019a5e2c-7b41-7c3e-9f20-4d8e1a6b5c37","duration_ms":7,"exit_code":0,"stdout":"hi\n","stderr":""}
components:
  parameters:
    workspaceId:
      name: workspace_id
      in: path
      required: true
      description: Workspace ID.
      schema:
        type: string
      example: demo
  schemas:
    LogPage:
      properties:
        items:
          items:
            $ref: '#/components/schemas/CommandLog'
          title: Items
          type: array
        next:
          anyOf:
            - type: string
            - type: 'null'
          title: Next
          description: >-
            Cursor for the next page, or null when no more results are
            available.
      required:
        - items
        - next
      title: LogPage
      type: object
    CommandLog:
      properties:
        id:
          title: Id
          type: string
        command:
          title: Command
          type: string
        cwd:
          anyOf:
            - type: string
            - type: 'null'
          title: Cwd
        started_at:
          type: string
          format: date-time
          title: Started At
          description: When the command started.
        duration_ms:
          title: Duration Ms
          type: number
          description: Command duration in milliseconds.
        exit_code:
          anyOf:
            - type: integer
            - type: 'null'
          title: Exit Code
        stdout:
          title: Stdout
          type: string
        stderr:
          title: Stderr
          type: string
        user_id:
          anyOf:
            - type: string
            - type: 'null'
          title: User Id
        api_key_id:
          anyOf:
            - type: string
            - type: 'null'
          title: Api Key Id
        mounts:
          items:
            $ref: '#/components/schemas/LogMount'
          title: Mounts
          type: array
      required:
        - id
        - command
        - cwd
        - started_at
        - duration_ms
        - exit_code
        - stdout
        - stderr
        - user_id
        - api_key_id
        - mounts
      title: CommandLog
      type: object
    LogMount:
      properties:
        op:
          title: Op
          type: string
        path:
          title: Path
          type: string
        source:
          title: Source
          type: string
        bytes:
          anyOf:
            - type: integer
            - type: 'null'
          title: Bytes
        started_at:
          type: string
          format: date-time
          title: Started At
          description: When the call started.
        duration_ms:
          title: Duration Ms
          type: number
      required:
        - op
        - path
        - source
        - bytes
        - started_at
        - duration_ms
      title: LogMount
      type: object
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: >-
        The server's token (MIRAGE_AUTH_TOKEN) or a JWT. A daemon in the default
        local mode with no token accepts requests without one.

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.