> ## 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 processes

List running and recently ended processes, ordered by process ID. Filter by session, state, command execution, job, or machine.

Ended processes are retained for up to one hour, with a maximum of 1,024 records. Servers sharing a workspace store share these records; snapshots preserve ended records. Times are RFC 3339 strings in UTC.

> [accordion] Errors
>
> | Status | Meaning |
> | - | - |
> | `400` | A query parameter is not valid (`invalid_value`, with `param`), such as an unknown `state` or a `machine` not in `provider:name` format. |
> | `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`). |
>
> 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}/processes
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}/processes:
    get:
      tags:
        - Processes
      summary: List processes
      operationId: list_processes_v1_workspaces__workspace_id__processes_get
      parameters:
        - $ref: '#/components/parameters/workspaceId'
        - name: session_id
          in: query
          required: false
          description: Filter by session ID. If omitted, include all sessions.
          schema:
            type: string
        - name: state
          in: query
          required: false
          description: Filter by execution state.
          schema:
            $ref: '#/components/schemas/ProcessState'
        - name: line_id
          in: query
          required: false
          description: Command execution ID returned as `line_id` by the shell endpoint.
          schema:
            type: string
        - name: job_id
          in: query
          required: false
          description: >-
            Filter processes by job ID (`job_` and 32 hex digits), including
            descendant processes.
          schema:
            type: string
        - name: machine
          in: query
          required: false
          description: Filter by machine name in `provider:name` format.
          schema:
            type: string
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProcessList'
              example:
                items:
                  - pid: 42
                    session_id: default
                    line_id: line_019a5e2c-7b41-7c3e-9f20-4d8e1a6b5c37
                    parent: null
                    group: 42
                    command: sleep 30
                    cwd: /
                    machine:
                      type: host
                      name: my-laptop
                      id: my-laptop
                    machine_pid:
                      pid: 12345
                      started: 1794009600
                      exited: null
                    state: running
                    started_at: '2026-11-07T00:00:00.000Z'
                    ended_at: null
                    exit: null
                    signal: null
                    error: null
components:
  parameters:
    workspaceId:
      name: workspace_id
      in: path
      required: true
      description: Workspace ID.
      schema:
        type: string
      example: demo
  schemas:
    ProcessState:
      enum:
        - running
        - stopping
        - exited
      title: ProcessState
      type: string
    ProcessList:
      properties:
        items:
          items:
            $ref: '#/components/schemas/ProcessResponse'
          type: array
      required:
        - items
      type: object
    ProcessResponse:
      properties:
        command:
          title: Command
          type: string
        cwd:
          type: string
          title: Cwd
        ended_at:
          anyOf:
            - type: string
              format: date-time
            - type: 'null'
          title: Ended At
        error:
          anyOf:
            - type: string
            - type: 'null'
          title: Error
        exit:
          anyOf:
            - type: integer
            - type: 'null'
          title: Exit
        group:
          title: Group
          type: integer
        line_id:
          anyOf:
            - type: string
            - type: 'null'
          title: Line Id
        machine:
          $ref: '#/components/schemas/ProcessMachineResponse'
        machine_pid:
          anyOf:
            - $ref: '#/components/schemas/MachinePidResponse'
            - type: 'null'
        parent:
          anyOf:
            - type: integer
            - type: 'null'
          title: Parent
        pid:
          title: Pid
          type: integer
        session_id:
          type: string
          title: Session Id
        signal:
          anyOf:
            - type: integer
            - type: 'null'
          title: Signal
        started_at:
          type: string
          format: date-time
          title: Started At
        state:
          title: State
          type: string
      required:
        - pid
        - session_id
        - line_id
        - parent
        - group
        - command
        - cwd
        - machine
        - machine_pid
        - state
        - started_at
        - ended_at
        - exit
        - signal
        - error
      title: ProcessResponse
      type: object
    ProcessMachineResponse:
      properties:
        id:
          type: string
          title: Id
          description: >-
            What the provider calls the machine, such as an E2B sandbox id or a
            container.
        name:
          type: string
          title: Name
          description: >-
            The machine's name under `machines:`; with the type it makes the
            machine's full name, `type:name`.
        type:
          type: string
          title: Type
          description: >-
            The machine's provider, such as `e2b` or `docker`, or `host` for the
            host running Mirage.
      required:
        - type
        - name
        - id
      title: ProcessMachineResponse
      type: object
    MachinePidResponse:
      properties:
        exited:
          anyOf:
            - type: number
            - type: 'null'
          title: Exited
        pid:
          title: Pid
          type: integer
        started:
          title: Started
          type: number
      required:
        - pid
        - started
        - exited
      title: MachinePidResponse
      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.