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

> ## Agent Instructions
> To set Ambral up in a project, run `npx ambral@latest skill install` in the project's root. It installs Ambral's skill, matched to the CLI's version, and the skill says how to do everything these pages describe with the `ambral` CLI. Prefer it to working from these pages. Never ask anyone for an Ambral API key, and never handle one: the person creates it in the web app and stores it where their app reads its secrets.

# Open an offline run

> Of a suite's taskset, `<workload>/<taskset>`, on `model`, any of the workload's pool (`RunSubjectNotInPool` when it isn't), or the workload's primary when it names none. The workload must exist (`WorkloadNotFound`); its first run of a taskset by that name creates it, and a replay taskset's name is `OfflineTasksetIsReplay`. Answers the run's id and the model it serves: send its `x-ambral-eval` header, `<run>; workload=<workload>; model=<model>`, and a session of its own, on each of a scenario's model calls.



## OpenAPI

````yaml /api-reference/report.json post /api/report/v1/runs
openapi: 3.1.0
info:
  title: Ambral Report API
  version: '1'
servers:
  - url: https://app.ambral.ai
security: []
tags:
  - name: Runs
    description: >-
      Offline runs: a suite's scenarios, run and scored by its own harness,
      reported as they finish
paths:
  /api/report/v1/runs:
    post:
      tags:
        - Runs
      summary: Open an offline run
      description: >-
        Of a suite's taskset, `<workload>/<taskset>`, on `model`, any of the
        workload's pool (`RunSubjectNotInPool` when it isn't), or the workload's
        primary when it names none. The workload must exist
        (`WorkloadNotFound`); its first run of a taskset by that name creates
        it, and a replay taskset's name is `OfflineTasksetIsReplay`. Answers the
        run's id and the model it serves: send its `x-ambral-eval` header,
        `<run>; workload=<workload>; model=<model>`, and a session of its own,
        on each of a scenario's model calls.
      operationId: runs.open
      parameters: []
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/OpenOfflineRun'
        required: true
      responses:
        '200':
          description: >-
            The run opened: its id, the model it serves its workload, and this
            open's opener, which closes it.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OfflineRunOpened'
        '400':
          description: >-
            The labels written are `count`, more than one object carries
            (`ceiling`).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/LabelsTooManyEncoded'
        '401':
          description: >-
            No API key, or one that is unknown or revoked, or whose org isn't
            active.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UnauthorizedEncoded'
        '404':
          description: No workload by this name exists in the caller's org.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WorkloadNotFoundEncoded'
        '409':
          description: >-
            The model named isn't in the workload's pool, and a run can only
            score a model that is. | The taskset named is a replay taskset,
            recorded traces picked by hand, which a suite can't report to.
          content:
            application/json:
              schema:
                anyOf:
                  - $ref: '#/components/schemas/RunSubjectNotInPoolEncoded'
                  - $ref: '#/components/schemas/OfflineTasksetIsReplayEncoded'
        '413':
          description: >-
            The request's body is larger than the report API takes, `limit`
            bytes: nothing in it was stored.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OfflineRequestTooLargeEncoded'
        '429':
          description: >-
            Too many requests. Send the request again after `retryAfter`
            seconds, which the `Retry-After` header also gives.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TooManyAttemptsEncoded'
        '503':
          description: Something the request needs couldn't be reached. Retry the request.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ServiceUnavailableEncoded'
      security:
        - bearer: []
components:
  schemas:
    OpenOfflineRun:
      type: object
      properties:
        taskset:
          $ref: '#/components/schemas/TasksetAddressEncoded'
        model:
          anyOf:
            - $ref: '#/components/schemas/ModelId'
            - type: 'null'
          allOf:
            - description: >-
                The model the run's agent is served, any of the workload's pool.
                Absent, the workload's primary as the run opens.
        labels:
          anyOf:
            - $ref: '#/components/schemas/Labels'
            - type: 'null'
        key:
          anyOf:
            - $ref: '#/components/schemas/OfflineRunKey'
            - type: 'null'
          allOf:
            - description: >-
                The key the suite's processes share the run by. Opened with the
                same key, taskset and model, each opens the same run, one opener
                more, open again if it had completed; it completes once each has
                closed it. Absent, the run is this opener's alone.
        source:
          anyOf:
            - $ref: '#/components/schemas/OfflineRunSource'
            - type: 'null'
          allOf:
            - description: >-
                Where the suite ran: `ci`, or `local` for anywhere else. A
                suite's history leaves local runs out unless asked for them.
                Absent, it counts as not local.
      required:
        - taskset
      additionalProperties: false
    OfflineRunOpened:
      type: object
      properties:
        run:
          $ref: '#/components/schemas/RunId'
        model:
          $ref: '#/components/schemas/ModelId'
        opener:
          allOf:
            - $ref: '#/components/schemas/OfflineRunOpenerId'
            - description: >-
                This open's opener: send it to close the run. A run opened by
                key completes once each of its openers has closed it.
      required:
        - run
        - model
        - opener
      additionalProperties: false
      description: >-
        The run opened: its id, the model it serves its workload, and this
        open's opener, which closes it.
    LabelsTooManyEncoded:
      type: object
      properties:
        _tag:
          type: string
          enum:
            - LabelsTooMany
        count:
          type: integer
          minimum: -9007199254740991
          maximum: 9007199254740991
        ceiling:
          type: integer
          minimum: -9007199254740991
          maximum: 9007199254740991
      required:
        - _tag
        - count
        - ceiling
      additionalProperties: false
    UnauthorizedEncoded:
      type: object
      properties:
        _tag:
          type: string
          enum:
            - Unauthorized
      required:
        - _tag
      additionalProperties: false
    WorkloadNotFoundEncoded:
      type: object
      properties:
        _tag:
          type: string
          enum:
            - WorkloadNotFound
        workload:
          $ref: '#/components/schemas/WorkloadName'
      required:
        - _tag
        - workload
      additionalProperties: false
    RunSubjectNotInPoolEncoded:
      type: object
      properties:
        _tag:
          type: string
          enum:
            - RunSubjectNotInPool
        workload:
          $ref: '#/components/schemas/WorkloadName'
        model:
          $ref: '#/components/schemas/ModelId'
      required:
        - _tag
        - workload
        - model
      additionalProperties: false
    OfflineTasksetIsReplayEncoded:
      type: object
      properties:
        _tag:
          type: string
          enum:
            - OfflineTasksetIsReplay
        taskset:
          $ref: '#/components/schemas/TasksetAddressEncoded'
      required:
        - _tag
        - taskset
      additionalProperties: false
    OfflineRequestTooLargeEncoded:
      type: object
      properties:
        _tag:
          type: string
          enum:
            - OfflineRequestTooLarge
        limit:
          type: integer
          minimum: -9007199254740991
          maximum: 9007199254740991
      required:
        - _tag
        - limit
      additionalProperties: false
    TooManyAttemptsEncoded:
      type: object
      properties:
        _tag:
          type: string
          enum:
            - TooManyAttempts
        message:
          type: string
        retryAfter:
          $ref: '#/components/schemas/Seconds'
      required:
        - _tag
        - message
        - retryAfter
      additionalProperties: false
    ServiceUnavailableEncoded:
      type: object
      properties:
        _tag:
          type: string
          enum:
            - ServiceUnavailable
      required:
        - _tag
      additionalProperties: false
    TasksetAddressEncoded:
      type: string
    ModelId:
      type: string
      minLength: 1
      maxLength: 256
    Labels:
      type: object
      propertyNames:
        type: string
        description: >-
          Lowercase letters, digits, `.`, `_` and `-`, starting with a letter or
          digit; at most 63 characters.
      additionalProperties:
        $ref: '#/components/schemas/LabelValue'
      description: >-
        Labels, each `key: value`; a bare tag's value is empty. A listing's
        `label` filter finds what carries them.
    OfflineRunKey:
      type: string
      minLength: 1
      maxLength: 200
    OfflineRunSource:
      type: string
      enum:
        - ci
        - local
    RunId:
      type: string
      pattern: >-
        ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-4[0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12})$
      format: uuid
    OfflineRunOpenerId:
      type: string
      pattern: >-
        ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-4[0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12})$
      format: uuid
    WorkloadName:
      type: string
    Seconds:
      type: integer
      minimum: 0
      maximum: 9007199254740991
      description: A duration, in whole seconds
    LabelValue:
      type: string
      description: >-
        Letters, digits, spaces and `. _ : / @ + -`, not starting or ending with
        a space; at most 128 characters. Empty for a bare tag.
  securitySchemes:
    bearer:
      description: 'The org''s API key: the one its agent calls the Gateway with.'
      type: http
      scheme: Bearer

````

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