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

# List simulation batches

> Requires `read` in the explicit project/environment. Returns retained batch metadata; a listed batch is not proof its target ran. Cursor belongs to the exact selection and filters.



## OpenAPI

````yaml /api-reference/openapi.json get /v1/batches
openapi: 3.1.0
info:
  title: Firedrill API
  version: '2026-10-14'
  description: >-
    Authenticated simulation coordination, retained evidence and controlled
    Tools. Your customer-owned runner executes the target. This reference covers
    the documented JSON workflows; Tool-native HTTP routes and MCP methods are
    discovered from the selected Tool. Structural schemas do not replace
    canonical validation or capability checks.
servers:
  - url: https://api.firedrill.run
security:
  - FiredrillCredential: []
tags:
  - name: discovery
    description: Capabilities, authority and structural authoring schemas.
  - name: projects
    description: Projects and their logical environment.
  - name: simulations
    description: Preparation, queued batches and cancellation.
  - name: runs
    description: Individual recorded executions.
  - name: reports
    description: Retained observations, distributions and descriptive comparisons.
  - name: assessment
    description: Optional semantic assessment and authored scenario ranking.
  - name: evidence
    description: Authenticated captured files.
  - name: runner-protocol
    description: Advanced customer-runner coordination; native SDKs manage this protocol.
  - name: scenarios
    description: Immutable retained versions of repository-authored scenarios.
  - name: credentials
    description: Expiring scoped CI credentials.
  - name: authentication
    description: Human-approved sign-in boundaries.
  - name: tools
    description: Tool releases, data, instances and observations.
  - name: tool-connections
    description: Bounded target/manual grants, separate from control authority.
  - name: tool-lifecycle
    description: Epoch-fenced reusable Tool actions and exact-key recovery.
paths:
  /v1/batches:
    get:
      tags:
        - simulations
      summary: List simulation batches
      description: >-
        Requires `read` in the explicit project/environment. Returns retained
        batch metadata; a listed batch is not proof its target ran. Cursor
        belongs to the exact selection and filters.
      operationId: batches_list
      parameters:
        - name: projectId
          in: query
          required: true
          schema:
            type: string
            minLength: 1
            maxLength: 160
        - name: environmentId
          in: query
          required: true
          schema:
            type: string
            minLength: 1
            maxLength: 160
        - name: cursor
          in: query
          required: false
          schema:
            type: string
          description: >-
            Continuation returned by this exact endpoint. Keep scope and filters
            unchanged.
        - name: limit
          in: query
          required: false
          schema:
            type: integer
            minimum: 1
            maximum: 100
      responses:
        '200':
          description: The retained resource or operation response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BatchPage'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '409':
          $ref: '#/components/responses/Conflict'
        '410':
          $ref: '#/components/responses/Gone'
        '413':
          $ref: '#/components/responses/PayloadTooLarge'
        '415':
          $ref: '#/components/responses/UnsupportedMediaType'
        '422':
          $ref: '#/components/responses/InvalidInput'
        '429':
          $ref: '#/components/responses/Capacity'
        '500':
          $ref: '#/components/responses/Internal'
        '503':
          $ref: '#/components/responses/Unavailable'
components:
  schemas:
    BatchPage:
      type: object
      properties:
        items:
          type: array
          items:
            anyOf:
              - $ref: '#/components/schemas/UnavailableBatchListEntry'
              - type: object
                properties:
                  id:
                    type: string
                  projectId:
                    type: string
                  environmentId:
                    type: string
                  name:
                    type: string
                  targetKind:
                    type: string
                  createdAt:
                    type: string
                  total:
                    type: number
                  cancellationRequested:
                    type: boolean
                  counts:
                    type: object
                    properties: {}
                    required: []
                    additionalProperties:
                      type: number
                  assessments:
                    type: object
                    properties: {}
                    required: []
                    additionalProperties:
                      type: number
                  gates:
                    type: object
                    properties: {}
                    required: []
                    additionalProperties:
                      type: number
                  submission:
                    anyOf:
                      - type: 'null'
                      - $ref: '#/components/schemas/SubmissionMetadata'
                  overview:
                    anyOf:
                      - $ref: '#/components/schemas/BatchOverview'
                  metadataOnly:
                    anyOf:
                      - type: boolean
                        const: false
                  retention:
                    anyOf:
                      - $ref: '#/components/schemas/RetentionAvailability'
                required:
                  - id
                  - projectId
                  - environmentId
                  - name
                  - targetKind
                  - createdAt
                  - total
                  - cancellationRequested
                  - counts
                  - assessments
                  - gates
                  - submission
        nextCursor:
          anyOf:
            - type: 'null'
            - type: string
      required:
        - items
        - nextCursor
    UnavailableBatchListEntry:
      type: object
      properties:
        metadataOnly:
          type: boolean
          const: true
        retention:
          $ref: '#/components/schemas/RetentionAvailability'
        id:
          type: string
        projectId:
          type: string
        environmentId:
          type: string
        createdAt:
          type: string
        total:
          type: number
        cancellationRequested:
          type: boolean
        counts:
          type: object
          properties:
            error:
              anyOf:
                - type: number
            queued:
              anyOf:
                - type: number
            running:
              anyOf:
                - type: number
            completed:
              anyOf:
                - type: number
            interrupted:
              anyOf:
                - type: number
            cancelled:
              anyOf:
                - type: number
          required: []
        assessments:
          type: object
          properties:
            error:
              anyOf:
                - type: number
            completed:
              anyOf:
                - type: number
            not_requested:
              anyOf:
                - type: number
            pending:
              anyOf:
                - type: number
            partial:
              anyOf:
                - type: number
            unavailable:
              anyOf:
                - type: number
          required: []
        gates:
          type: object
          properties:
            not_configured:
              anyOf:
                - type: number
            allow:
              anyOf:
                - type: number
            block:
              anyOf:
                - type: number
            inconclusive:
              anyOf:
                - type: number
          required: []
      required:
        - metadataOnly
        - retention
        - id
        - projectId
        - environmentId
        - createdAt
        - total
        - cancellationRequested
        - counts
        - assessments
        - gates
    SubmissionMetadata:
      type: object
      properties:
        schemaVersion:
          type: string
          const: 2026-10-15-inspection.1
        origin:
          type: string
          enum:
            - cli
            - sdk
            - mcp
            - ci
            - api
        ci:
          anyOf:
            - $ref: '#/components/schemas/CiContext'
      required:
        - schemaVersion
        - origin
    BatchOverview:
      type: object
      properties:
        schemaVersion:
          type: string
          const: 2026-10-17-batch-overview.1
        timing:
          type: object
          properties:
            startedAt:
              anyOf:
                - type: 'null'
                - type: string
            finishedAt:
              anyOf:
                - type: 'null'
                - type: string
            durationMs:
              anyOf:
                - type: 'null'
                - type: number
            basis:
              type: string
              const: service_claim_to_finish
          required:
            - startedAt
            - finishedAt
            - durationMs
            - basis
        configurations:
          type: object
          properties:
            count:
              type: number
            ids:
              type: array
              items:
                type: string
            complete:
              type: boolean
          required:
            - count
            - ids
            - complete
        scoring:
          type: object
          properties:
            state:
              type: string
              enum:
                - not_requested
                - unavailable
                - single_dimension
                - mixed
            dimension:
              anyOf:
                - type: object
                  properties:
                    id:
                      type: string
                    description:
                      type: string
                    scale:
                      type: array
                      prefixItems:
                        - type: number
                          const: 0
                        - type: number
                          const: 4
                      minItems: 2
                      maxItems: 2
                  required:
                    - id
                    - description
                    - scale
            levels:
              anyOf:
                - type: array
                  prefixItems:
                    - type: number
                    - type: number
                    - type: number
                    - type: number
                    - type: number
                  minItems: 5
                  maxItems: 5
            providerScores:
              anyOf:
                - $ref: '#/components/schemas/ProviderScoreStats'
            coverage:
              anyOf:
                - type: object
                  properties:
                    total:
                      type: number
                    assessed:
                      type: number
                    notAssessable:
                      type: number
                    notApplicable:
                      type: number
                    pending:
                      type: number
                    missing:
                      type: number
                  required:
                    - total
                    - assessed
                    - notAssessable
                    - notApplicable
                    - pending
                    - missing
          required:
            - state
      required:
        - schemaVersion
        - timing
        - configurations
        - scoring
    RetentionAvailability:
      type: object
      properties:
        schemaVersion:
          type: string
          const: 2026-10-15-retention.1
        policyVersion:
          type: string
          enum:
            - historical_preserved
            - 2026-10-15-retention.1
        state:
          $ref: '#/components/schemas/ContentAvailability'
        payloadExpiresAt:
          anyOf:
            - type: 'null'
            - type: string
        metadataExpiresAt:
          anyOf:
            - type: 'null'
            - type: string
        removalId:
          anyOf:
            - type: 'null'
            - type: string
      required:
        - schemaVersion
        - policyVersion
        - state
        - payloadExpiresAt
        - metadataExpiresAt
        - removalId
    ApiError:
      type: object
      properties:
        error:
          type: object
          properties:
            code:
              type: string
            message:
              type: string
            repair:
              type: string
            requestId:
              type: string
            details:
              anyOf:
                - type: 'null'
                - type: string
                - type: number
                - type: boolean
                  const: false
                - type: boolean
                  const: true
                - type: array
                  items:
                    $ref: '#/components/schemas/JsonValue'
                - type: object
                  properties: {}
                  required: []
                  additionalProperties:
                    $ref: '#/components/schemas/JsonValue'
            validation:
              anyOf:
                - $ref: '#/components/schemas/ValidationDiagnostics'
          required:
            - code
            - message
            - repair
            - requestId
      required:
        - error
    CiContext:
      type: object
      properties:
        schemaVersion:
          type: string
          const: 2026-10-16-ci-context.1
        provider:
          type: string
          const: github
        serverUrl:
          type: string
        repository:
          type: string
        runId:
          type: string
        runAttempt:
          type: number
        commit:
          type: string
        ref:
          anyOf:
            - type: string
        workflow:
          anyOf:
            - type: string
        job:
          anyOf:
            - type: string
        event:
          anyOf:
            - type: string
        pullRequest:
          anyOf:
            - type: number
      required:
        - schemaVersion
        - provider
        - serverUrl
        - repository
        - runId
        - runAttempt
        - commit
    ProviderScoreStats:
      type: object
      properties:
        provider:
          type: string
          const: jev
        scale:
          type: array
          prefixItems:
            - type: number
              const: 0
            - type: number
              const: 4
          minItems: 2
          maxItems: 2
        ordinalConversion:
          type: string
          const: none
        count:
          type: number
        mean:
          anyOf:
            - type: 'null'
            - type: number
        median:
          anyOf:
            - type: 'null'
            - type: number
        range:
          anyOf:
            - type: 'null'
            - type: object
              properties:
                minimum:
                  type: number
                maximum:
                  type: number
              required:
                - minimum
                - maximum
      required:
        - provider
        - scale
        - ordinalConversion
        - count
        - mean
        - median
        - range
    ContentAvailability:
      type: string
      enum:
        - available
        - historical_preserved
        - expired
        - deletion_pending
        - deleted
    JsonValue:
      description: >-
        Any JSON value: null, boolean, finite number, string, array or object.
        The request transport must contain valid JSON; canonical validation
        rejects nonfinite numbers.
    ValidationDiagnostics:
      type: object
      properties:
        issues:
          type: array
          items:
            $ref: '#/components/schemas/ValidationIssue'
        totalIssues:
          type: number
        omittedIssues:
          type: number
      required:
        - issues
        - totalIssues
        - omittedIssues
    ValidationIssue:
      type: object
      properties:
        path:
          type: array
          items:
            anyOf:
              - type: string
              - type: number
        code:
          type: string
        message:
          type: string
        pathTruncated:
          anyOf:
            - type: boolean
              const: true
      required:
        - path
        - code
        - message
  responses:
    BadRequest:
      description: >-
        Malformed request or missing operation key. Repair the input before
        retrying.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ApiError'
    Unauthorized:
      description: >-
        Missing, expired or revoked authority. Complete supported sign-in or use
        an authorized credential.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ApiError'
    Forbidden:
      description: >-
        The current capability, actor, audience or ownership grant does not
        allow this operation.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ApiError'
    NotFound:
      description: The exact resource is unavailable under the current authority and scope.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ApiError'
    Conflict:
      description: >-
        Selected context, epoch, revision, lease or saved operation intent
        conflicts; inspect retained state.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ApiError'
    Gone:
      description: >-
        Retained content is expired, deleted or unavailable under its retention
        fence. Metadata is not a replacement payload.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ApiError'
    PayloadTooLarge:
      description: >-
        Request, response or retained-resource size exceeds this operation’s
        enforced bound.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ApiError'
    UnsupportedMediaType:
      description: Send the documented JSON or exact artifact media type.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ApiError'
    InvalidInput:
      description: >-
        Input failed canonical validation. Inspect error.validation and repair
        the indicated fields.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ApiError'
    Capacity:
      description: >-
        Bounded capacity or resource admission rejected the operation. Inspect
        retained work before retrying.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ApiError'
    Internal:
      description: >-
        The service could not complete the request. Inspect retained state
        before exact-key recovery.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ApiError'
    Unavailable:
      description: >-
        A required service, provider or authority check is unavailable. Existing
        evidence remains separate from this failure.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ApiError'
  securitySchemes:
    FiredrillCredential:
      type: http
      scheme: bearer
      description: >-
        Opaque Firedrill interactive or scoped machine credential. The CLI
        handles human-approved login; CI stores its scoped credential as
        FIREDRILL_TOKEN. Capabilities and project/environment ownership are
        rechecked at use.

````

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