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

> ## Agent Instructions
> To set up offstage cloud from a coding agent, read https://api.offstage.cloud/SKILL.md and follow it. The whole API guide is one file at https://api.offstage.cloud/llms.txt.

# List tasks

> Lists the team's tasks, newest first, as summaries without `events` (`GET /v1/tasks/{taskId}` has them). Filter by `state` and `kind`; page with `limit` and `cursor`.



## OpenAPI

````yaml /openapi.json get /v1/tasks
openapi: 3.1.0
info:
  title: offstage cloud API
  version: 0.1.0
  summary: Real Macs for AI agents and CI, over HTTP.
  description: >-
    macOS sandboxes driven one call at a time, and fire-and-forget CI tasks, on
    Apple silicon Macs running macOS 27.


    - **Auth.** `Authorization: Bearer sk_offstage_…` (a team API key; one made
    before 2026-10-29 starts with `oc_live_` and still works), or the console's
    `oc_session` cookie. Operations marked `x-console-only: true` take only the
    cookie; an API key gets 403 `console-only`. A cookie request that changes
    something must come from this origin.

    - **Errors.** Every failure is `{"error": {"code", "message", "fix"?,
    "requestId"}}`. Switch on `code`; `fix`, when present, says what to do. Any
    operation can also answer 500 `internal` (a bug; quote the `requestId`), and
    an unknown route is 404 `no-such-route`.

    - **Request ids.** Every response carries an `x-request-id` header, repeated
    as `requestId` in error bodies.

    - **Units.** Times are Unix milliseconds, and durations end in `Ms`. Money
    is US dollars as numbers, exact to the micro-dollar (`costUsd`).

    - **Ids** are prefixed: `sbx_` sandbox, `cmd_` command, `run_` agent run,
    `task_` task, `key_` API key, `req_` request, `team_`, `usr_`, `box_` (a
    fleet Mac), `inv_`.

    - **Lists** are newest first. Pass the previous page's `nextCursor` as
    `cursor`; it is null on the last page.

    - **Bodies.** JSON, except file writes, which send raw bytes. Request
    schemas with `additionalProperties: false` refuse an unknown field with 400
    `unknown-field`.

    - **Limits.** A team may send 120 requests a minute, whatever key or session
    it uses. Every request also counts against its client address: 600 a minute,
    and far fewer on the routes that need no credential (5 sign-ups an hour, 20
    sign-ins and 20 verifications a minute). Over a window is 429 `rate-limit`
    with a `Retry-After` header.

    - **Verification.** A new account's team can sign in and look around, but
    cannot create sandboxes, tasks or API keys (403 `email-unverified`) until
    its owner opens the link emailed at signup.

    - **Holds.** No request is held longer than about 50 s, so default client
    timeouts and 60 s proxy idle timeouts are fine, except large files: a write
    answers once its upload is done, and a read streams for as long as the Mac
    takes to send it.


    The prose reference, with examples, is
    `https://api.offstage.cloud/llms.txt`. The agent setup guide is
    `https://api.offstage.cloud/SKILL.md`.
servers:
  - url: https://api.offstage.cloud
security:
  - apiKey: []
  - consoleSession: []
tags:
  - name: Sandboxes
    description: >-
      A Mac slot (a macOS user account) held for you: run commands, move files,
      take screenshots.
  - name: Tasks
    description: >-
      Fire-and-forget macOS work: clone a public repo, run a command, collect
      artifacts.
  - name: Recordings
    description: >-
      What a gui sandbox or gui task showed and did, kept by the plane: live
      while it runs, a replay after. Open one in the console at `/r/{id}`.
  - name: Capacity
    description: What the fleet can take right now, and whether the plane is up.
  - name: Billing
    description: The price, usage, the bill, the budget and the card.
  - name: Account
    description: Signing in, the team, its members and its API keys.
  - name: GitHub
    description: >-
      GitHub Actions jobs on offstage Macs: connect an organization in the
      console, then `runs-on: offstage-macos`.
  - name: Secrets
    description: Write-only team credentials selected by workload name.
paths:
  /v1/tasks:
    get:
      tags:
        - Tasks
      summary: List tasks
      description: >-
        Lists the team's tasks, newest first, as summaries without `events`
        (`GET /v1/tasks/{taskId}` has them). Filter by `state` and `kind`; page
        with `limit` and `cursor`.
      operationId: listTasks
      parameters:
        - $ref: '#/components/parameters/TaskState'
        - $ref: '#/components/parameters/TaskKind'
        - $ref: '#/components/parameters/Limit'
        - $ref: '#/components/parameters/Cursor'
      responses:
        '200':
          description: A page of task summaries.
          headers:
            x-request-id:
              $ref: '#/components/headers/RequestId'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TaskList'
        '400':
          description: >-
            `bad-state`, `bad-kind`, `bad-limit`, or `bad-cursor` (the cursor
            names no task of yours; start again without one).
          headers:
            x-request-id:
              $ref: '#/components/headers/RequestId'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: >-
            `unauthorized`: no credential, an `Authorization` header that is not
            `Bearer …`, a value that is not an `sk_offstage_` (or older
            `oc_live_`) key, a revoked or unknown key, or a box token. The
            message says which.
          headers:
            x-request-id:
              $ref: '#/components/headers/RequestId'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '413':
          $ref: '#/components/responses/BodyTooLarge'
        '429':
          $ref: '#/components/responses/RateLimited'
      security:
        - apiKey: []
        - consoleSession: []
components:
  parameters:
    TaskState:
      name: state
      in: query
      required: false
      description: Only tasks in this state.
      schema:
        $ref: '#/components/schemas/TaskState'
    TaskKind:
      name: kind
      in: query
      required: false
      description: Only tasks of this kind. `runner` lists GitHub Actions jobs.
      schema:
        $ref: '#/components/schemas/TaskKind'
    Limit:
      name: limit
      in: query
      required: false
      description: Page size.
      schema:
        type: integer
        minimum: 1
        maximum: 200
        default: 50
    Cursor:
      name: cursor
      in: query
      required: false
      description: >-
        The previous page's `nextCursor`. It marks a position among all your
        items, so an item that leaves the `state` filter between pages never
        breaks the listing.
      schema:
        type: string
  headers:
    RequestId:
      description: This request's id, `req_…`. Quote it when asking for help.
      required: true
      schema:
        type: string
        pattern: ^req_
  schemas:
    TaskList:
      type: object
      properties:
        tasks:
          type: array
          items:
            $ref: '#/components/schemas/TaskSummary'
        nextCursor:
          oneOf:
            - type: string
            - type: 'null'
          description: Pass as `cursor` for the next page; null on the last page.
      required:
        - tasks
        - nextCursor
      additionalProperties: false
    Error:
      type: object
      properties:
        error:
          type: object
          properties:
            code:
              type: string
              description: >-
                Stable and machine-readable, like `sandbox-closed`. Switch on
                this, not on the message.
            message:
              type: string
              description: What went wrong, for a person.
            fix:
              type: string
              description: What to do about it, when there is something to do.
            requestId:
              type: string
              description: >-
                The same as the `x-request-id` header. Quote it when asking for
                help.
              pattern: ^req_
          required:
            - code
            - message
            - requestId
          additionalProperties: false
      required:
        - error
      additionalProperties: false
      description: >-
        The one error envelope: every 4xx and 5xx the plane itself sends. A
        proxy in front of it may send a 5xx whose body is not JSON.
      examples:
        - error:
            code: sandbox-closed
            message: sandbox sbx_mh3k2f9aQ1xYz0aBcDeFgHiJ is closed (idle)
            fix: create a new sandbox
            requestId: req_mh3k2f9aQ1xYz0aBcDeFgHiJ
    TaskState:
      type: string
      enum:
        - queued
        - claimed
        - running
        - succeeded
        - failed
        - timed_out
        - cancelled
      description: >-
        `queued` → `claimed` → `running` → `succeeded` | `failed` | `timed_out`,
        or `cancelled` from any state before those. The last four are terminal.
    TaskKind:
      type: string
      enum:
        - build
        - test
        - screenshot
        - agent
        - runner
      description: >-
        Labels the task and picks its default `session`: `screenshot` runs
        `gui`, the rest `headless`. `agent` runs `agent` instead of `command`.
        `runner` is a GitHub Actions job: the plane makes one from a job queued
        with `runs-on: offstage-macos` (or `offstage-macos-gui`) in a connected
        GitHub organization, and its task carries `github`. No client submits
        one: `createTask` refuses it with 400 `bad-kind`.
    TaskSummary:
      type: object
      properties:
        id:
          type: string
          description: '`task_…`.'
          pattern: ^task_
        spec:
          $ref: '#/components/schemas/TaskSpec'
        state:
          $ref: '#/components/schemas/TaskState'
        createdAt:
          $ref: '#/components/schemas/Millis'
        boxId:
          type: string
          description: The Mac that holds or ran it. Absent until a slot claims it.
          pattern: ^box_
        slot:
          type: integer
          description: The slot on that Mac. Absent until claimed.
          minimum: 1
        startedAt:
          $ref: '#/components/schemas/Millis'
          description: When the command started. Absent until then.
        endedAt:
          $ref: '#/components/schemas/Millis'
          description: >-
            When it ended. Absent until then (and for a queued task that was
            cancelled).
        attempts:
          type: integer
          description: How many slots claimed it and never started it.
          minimum: 0
        requeued:
          type: boolean
          description: >-
            True once a slot claimed it and never started it, so it went back to
            `queued`.
        runtimeSeconds:
          type: integer
          description: Whole seconds from start to end. Absent until it ends.
          minimum: 0
        costUsd:
          $ref: '#/components/schemas/Usd'
          description: >-
            What its running time costs: accrued so far while it runs, final
            once it ends. 0 for work the fleet lost.
        createdBy:
          $ref: '#/components/schemas/CreatedBy'
        exitCode:
          type:
            - integer
            - 'null'
          description: >-
            The command's exit status once the Mac reports it; null before then,
            and when there was none (timed out, cancelled, lost).
        droppedLogLines:
          type: integer
          description: Log lines dropped from the front to keep the last 500.
          minimum: 0
        failureReason:
          oneOf:
            - $ref: '#/components/schemas/FailureReason'
            - type: 'null'
          description: Why it ended `failed` or `timed_out`; null in every other state.
        github:
          $ref: '#/components/schemas/GitHubJob'
          description: 'Only on a `runner` task: the GitHub Actions job it was made for.'
        replayUrl:
          type: string
          description: >-
            Where to watch it, live while it runs and as a replay after: the
            console's `/r/{id}` page. Present for a `gui` task that records.
      required:
        - id
        - spec
        - state
        - createdAt
        - attempts
        - requeued
        - costUsd
        - createdBy
        - exitCode
        - droppedLogLines
        - failureReason
      additionalProperties: false
      description: >-
        A task in a list: the task without `events`. Fields that do not apply
        yet are absent, not null.
      examples:
        - id: task_mh3k2f9aQ1xYz0aBcDeFgHiJ
          spec:
            repo: https://github.com/org/app
            kind: build
            command: set -o pipefail; swift build 2>&1 | tee build.log
            artifacts:
              - build.log
            session: headless
            timeoutMs: 1800000
            queueTimeoutMs: 900000
          state: running
          createdAt: 1793000000000
          boxId: box_mh3k2f9aQ1xYz0aBcDeFgHiJ
          slot: 2
          startedAt: 1793000001000
          attempts: 0
          requeued: false
          costUsd: 0.02
          createdBy:
            keyName: ci
          exitCode: null
          droppedLogLines: 0
          failureReason: null
    TaskSpec:
      type: object
      properties:
        repo:
          type: string
          description: The https clone URL.
        kind:
          $ref: '#/components/schemas/TaskKind'
        command:
          type: string
          description: Present unless `kind` is `agent` or `runner`.
        agent:
          type: string
          description: Present only when `kind` is `agent`.
        artifacts:
          type: array
          items:
            type: string
          description: >-
            Empty for a `runner` task: a GitHub job keeps its own artifacts on
            GitHub.
        session:
          $ref: '#/components/schemas/Session'
        timeoutMs:
          type: integer
          minimum: 1
        queueTimeoutMs:
          type: integer
          minimum: 1
        record:
          type: boolean
          description: '`false` when it was submitted not to record.'
        secrets:
          $ref: '#/components/schemas/SecretNames'
      required:
        - repo
        - kind
        - artifacts
        - session
        - timeoutMs
        - queueTimeoutMs
      additionalProperties: false
      description: The task as submitted, with defaults filled in.
    Millis:
      type: integer
      minimum: 0
      description: A time, in Unix milliseconds.
    Usd:
      type: number
      description: US dollars, exact to the micro-dollar (six decimal places).
    CreatedBy:
      description: >-
        Who started the work: `{keyName}` for an API key, `{email}` for a
        console user.
      oneOf:
        - type: object
          properties:
            keyName:
              type: string
          required:
            - keyName
          additionalProperties: false
        - type: object
          properties:
            email:
              type: string
          required:
            - email
          additionalProperties: false
    FailureReason:
      type: string
      enum:
        - exit
        - setup
        - timeout
        - no-capacity
        - box-lost
        - plane-restart
        - never-started
      description: >-
        Why a task ended `failed` or `timed_out`; branch on this, never on event
        text. `exit`: the command exited non-zero (billed). `setup`: the Mac
        could not get to running it, such as a failed clone, or it exited 0
        without a promised artifact (billed). `timeout`: it ran past `timeoutMs`
        (billed). `no-capacity`: no Mac took it within `queueTimeoutMs`; it
        never ran (free). `box-lost`, `plane-restart`, `never-started`: the
        fleet lost it; submit it again (free).
    GitHubJob:
      type: object
      description: >-
        The GitHub Actions job a `runner` task runs. GitHub gives a waiting job
        to any idle runner of its organization whose labels cover it, so once
        `jobStartedAt` is set these fields describe the job this task's runner
        actually took, which need not be the one it was registered for. A runner
        task whose runner got no job is cancelled once no job it could take
        still waits, and costs nothing.
      properties:
        org:
          type: string
          description: The GitHub organization the runner was registered on.
        repo:
          type: string
          description: '`owner/name` of the job''s repository.'
        workflowJobId:
          type: integer
          description: GitHub's job id.
        runId:
          type: integer
          description: GitHub's workflow run id.
        runUrl:
          type: string
          description: The job's page on GitHub.
        jobName:
          type: string
        workflowName:
          type: string
        jobStartedAt:
          type: integer
          description: >-
            When GitHub said this task's runner took the job (Unix ms). The task
            is billed, per second from its Mac's start, only once this is set;
            until then its `costUsd` is 0.
        runnerName:
          type: string
          description: The runner GitHub says picked the job up. Absent until it did.
        conclusion:
          type: string
          description: >-
            GitHub's verdict once the job completed: `success`, `failure`,
            `cancelled`, `skipped`, `timed_out`, and so on. Absent until then.
      required:
        - org
        - repo
        - workflowJobId
        - runId
        - runUrl
        - jobName
        - workflowName
      additionalProperties: false
    Session:
      type: string
      enum:
        - headless
        - gui
      description: >-
        `headless`: the slot's user with no desktop; every slot takes it from
        boot. `gui`: the slot's logged-in desktop session, remade after every
        customer, so `gui` slots are scarce.
    SecretNames:
      type: array
      minItems: 1
      maxItems: 16
      uniqueItems: true
      items:
        type: string
        pattern: ^[A-Za-z_][A-Za-z0-9_-]{0,63}$
      description: >-
        Existing team names. Encoded selected payload at most120 KiB; at most
        one apple-signing bundle.
  responses:
    BodyTooLarge:
      description: >-
        The JSON body is over 1 MiB (a `command` is 64 KiB at most; the rest is
        spare).
      headers:
        x-request-id:
          $ref: '#/components/headers/RequestId'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    RateLimited:
      description: >-
        `rate-limit`: this team has sent more than 120 requests in the last 60
        s, or this client address more than 600 (fewer on the routes that need
        no credential). The `Retry-After` header gives the seconds left in the
        window.
      headers:
        x-request-id:
          $ref: '#/components/headers/RequestId'
        Retry-After:
          schema:
            type: string
          description: Seconds until the window opens again.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
  securitySchemes:
    apiKey:
      type: http
      scheme: bearer
      description: >-
        A team API key, `sk_offstage_…`, created in the console. Everything it
        touches belongs to its team.
    consoleSession:
      type: apiKey
      in: cookie
      name: oc_session
      description: >-
        The console's session cookie (httpOnly, SameSite=Lax, 30 days), set by
        `signup` and `login`.

````

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