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

# Read a Tool dataset

> Requires `read`. Returns metadata unless includeRecords=true explicitly requests a bounded retained record page. Preserve the returned numeric cursor; metadata is not current instance state.



## OpenAPI

````yaml /api-reference/openapi.json get /v1/service-datasets/{datasetId}
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/service-datasets/{datasetId}:
    get:
      tags:
        - tools
      summary: Read a Tool dataset
      description: >-
        Requires `read`. Returns metadata unless includeRecords=true explicitly
        requests a bounded retained record page. Preserve the returned numeric
        cursor; metadata is not current instance state.
      operationId: tool_datasets_get
      parameters:
        - name: datasetId
          in: path
          required: true
          schema:
            type: string
            minLength: 1
            maxLength: 160
        - name: projectId
          in: query
          required: true
          schema:
            type: string
            minLength: 1
            maxLength: 160
        - name: environmentId
          in: query
          required: false
          schema:
            type: string
            minLength: 1
            maxLength: 160
          description: >-
            Authorization context for project-owned definitions. Required for an
            environment-restricted credential; keep your selected environment
            explicit.
        - name: cursor
          in: query
          required: false
          schema:
            type: integer
            minimum: 0
        - name: limit
          in: query
          required: false
          schema:
            type: integer
            minimum: 1
            maximum: 100
        - name: includeRecords
          in: query
          required: false
          schema:
            type: string
            enum:
              - 'true'
              - 'false'
            default: 'false'
      responses:
        '200':
          description: The retained resource or operation response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ServiceDatasetDetail'
        '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:
    ServiceDatasetDetail:
      type: object
      properties:
        recordPage:
          anyOf:
            - type: object
              properties:
                items:
                  type: array
                  items:
                    $ref: '#/components/schemas/ServiceSeedRecord'
                nextCursor:
                  anyOf:
                    - type: 'null'
                    - type: number
              required:
                - items
                - nextCursor
        schemaVersion:
          type: string
          enum:
            - 2026-10-15-dataset.1
        id:
          type: string
        projectId:
          type: string
        buildId:
          type: string
        version:
          type: string
        records:
          type: number
        initialVirtualTimeUs:
          anyOf:
            - type: number
        metadata:
          anyOf:
            - type: 'null'
            - $ref: '#/components/schemas/DatasetMetadata'
        validation:
          anyOf:
            - type: 'null'
            - $ref: '#/components/schemas/DatasetValidationReceipt'
        validationStatus:
          type: string
          enum:
            - not_recorded
            - validated
        createdAt:
          type: string
      required:
        - id
        - projectId
        - buildId
        - version
        - records
        - createdAt
    ServiceSeedRecord:
      type: object
      properties:
        namespace:
          type: string
        rowId:
          type: string
        value:
          type: object
          properties: {}
          required: []
          additionalProperties:
            $ref: '#/components/schemas/JsonValue'
      required:
        - namespace
        - rowId
        - value
    DatasetMetadata:
      type: object
      properties:
        schemaVersion:
          type: string
          const: 2026-10-15-dataset-metadata.1
        provenance:
          anyOf:
            - $ref: '#/components/schemas/DatasetProvenance'
        mappings:
          anyOf:
            - type: array
              items:
                $ref: '#/components/schemas/DatasetMapping'
      required:
        - schemaVersion
    DatasetValidationReceipt:
      type: object
      properties:
        schemaVersion:
          type: string
          const: 2026-10-15-dataset-validation.1
        state:
          type: string
          const: validated
        manifestDigest:
          type: string
        recordsDigest:
          type: string
        metadataDigest:
          anyOf:
            - type: 'null'
            - type: string
        policyDigest:
          anyOf:
            - type: 'null'
            - type: string
        checkedRecords:
          type: number
        schema:
          type: string
          const: valid
        domain:
          type: object
          properties:
            state:
              type: string
              enum:
                - satisfied
                - not_declared
            constraintIds:
              type: array
              items:
                type: string
          required:
            - state
            - constraintIds
        mappings:
          type: object
          properties:
            state:
              type: string
              enum:
                - satisfied
                - not_declared
            checks:
              type: array
              items:
                type: object
                properties:
                  id:
                    type: string
                  datasetId:
                    type: string
                  version:
                    type: string
                  recordsDigest:
                    type: string
                required:
                  - id
                  - datasetId
                  - version
                  - recordsDigest
          required:
            - state
            - checks
        provenance:
          type: object
          properties:
            state:
              type: string
              enum:
                - not_recorded
                - caller_declared
            kind:
              anyOf:
                - type: 'null'
                - type: string
                  const: authored
                - type: string
                  const: generated
                - type: string
                  const: imported
            sensitive:
              anyOf:
                - type: 'null'
                - type: boolean
                  const: false
                - type: boolean
                  const: true
            importAuthorization:
              type: string
              enum:
                - not_applicable
                - not_recorded
                - caller_asserted
          required:
            - state
            - kind
            - sensitive
            - importAuthorization
        fidelity:
          type: string
          const: not_established
        validatedAt:
          type: string
        digest:
          type: string
      required:
        - schemaVersion
        - state
        - manifestDigest
        - recordsDigest
        - metadataDigest
        - policyDigest
        - checkedRecords
        - schema
        - domain
        - mappings
        - provenance
        - fidelity
        - validatedAt
        - digest
    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
    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.
    DatasetProvenance:
      type: object
      properties:
        kind:
          type: string
          enum:
            - authored
            - generated
            - imported
        sensitive:
          type: boolean
        description:
          anyOf:
            - type: string
        authorizedImport:
          anyOf:
            - type: boolean
              const: true
      required:
        - kind
        - sensitive
    DatasetMapping:
      type: object
      properties:
        id:
          type: string
        namespace:
          type: string
        pointer:
          type: string
        target:
          type: object
          properties:
            datasetId:
              type: string
            version:
              type: string
            namespace:
              type: string
            pointer:
              anyOf:
                - type: string
          required:
            - datasetId
            - version
            - namespace
        optional:
          anyOf:
            - type: boolean
              const: false
            - type: boolean
              const: true
      required:
        - id
        - namespace
        - pointer
        - target
    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.