BAMF.ai Runs API

openapi: 3.2.0
info:
  title: BAMF Developer Platform Runs API
  version: 0.1.0
servers:
- url: https://api.bamf.ai/v1
security:
- BearerAuth: []
tags:
- name: Runs
paths:
  /runs/{run_id}/events:
    get:
      summary: Get run status events
      description: 'Returns the live, named status of an agent run or API job: the run, its sub-agents, tool and model calls, each with status, partial result, cost, and timing. Requires agent_sessions:read. Pass after_sequence to fetch only events after a given sequence, or set Accept to text/event-stream for a resumable live stream instead of a single snapshot.'
      parameters:
      - name: run_id
        in: path
        required: true
        schema:
          type: string
        description: A chat turn id or an API job id (returned by POST /jobs).
      - name: after_sequence
        in: query
        schema:
          type: integer
          minimum: -1
        description: Only return events with a sequence greater than this value. Ignored (but still accepted) alongside Last-Event-ID.
      - name: Last-Event-ID
        in: header
        schema:
          type: string
        description: Resumes an SSE stream after the given sequence; takes precedence over after_sequence.
      responses:
        '200':
          description: Run status snapshot and events, or (when Accept is text/event-stream) a live SSE stream of run.node events whose id is the sequence, ending with a run.end event carrying the final snapshot. The SSE stream closes after roughly 55 seconds so clients reconnect with Last-Event-ID.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: object
                    properties:
                      run:
                        $ref: '#/components/schemas/RunStatusSnapshot'
                      events:
                        type: array
                        items:
                          $ref: '#/components/schemas/RunNodeEvent'
            text/event-stream:
              schema:
                type: string
                description: 'SSE stream: repeated run.node events (data is a RunNodeEvent, id is its sequence), followed by a final run.end event whose data is a RunStatusSnapshot.'
        '400':
          description: run_id is not a valid run identifier.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Missing or invalid bearer token.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: agent_sessions:read scope required.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: Run not found.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      tags:
      - Runs
      operationId: getRunsByRunIdEvents
      x-operation-id-source: derived
components:
  schemas:
    Error:
      type: object
      properties:
        error:
          type: object
          properties:
            code:
              type: string
            message:
              type: string
            request_id:
              type: string
    RunNodeEvent:
      type: object
      description: One status transition for a run node (the run itself, a sub-agent, a tool call, a model call, a responder, or a router). The latest event per node_id is that node's current state.
      properties:
        schema_version:
          type: string
          enum:
          - bamf.agent-stream/v1
        type:
          type: string
          enum:
          - run.node
        turn_id:
          type: string
        sequence:
          type: integer
          minimum: 0
        run_id:
          type: string
        node_id:
          type: string
        parent_node_id:
          type:
          - string
          - 'null'
        node_kind:
          type: string
          enum:
          - run
          - subagent
          - tool
          - model
          - responder
          - router
        name:
          type: string
          description: User-facing name, e.g. "Researcher", "Analytics".
        role:
          type:
          - string
          - 'null'
        task:
          type:
          - string
          - 'null'
        status:
          type: string
          enum:
          - queued
          - running
          - waiting_approval
          - succeeded
          - failed
          - cancelled
          - skipped
        partial:
          type:
          - string
          - 'null'
        cost:
          type:
          - object
          - 'null'
          properties:
            input_tokens:
              type: integer
              minimum: 0
            output_tokens:
              type: integer
              minimum: 0
            usd:
              type:
              - number
              - 'null'
        timing:
          type: object
          properties:
            started_at:
              type:
              - string
              - 'null'
              format: date-time
            ended_at:
              type:
              - string
              - 'null'
              format: date-time
            ttft_ms:
              type:
              - number
              - 'null'
        route_decision_id:
          type:
          - string
          - 'null'
    RunNodeState:
      type: object
      description: The folded current state of one run node, with its children nested under it.
      properties:
        run_id:
          type: string
        node_id:
          type: string
        parent_node_id:
          type:
          - string
          - 'null'
        node_kind:
          type: string
          enum:
          - run
          - subagent
          - tool
          - model
          - responder
          - router
        name:
          type: string
        role:
          type:
          - string
          - 'null'
        task:
          type:
          - string
          - 'null'
        status:
          type: string
          enum:
          - queued
          - running
          - waiting_approval
          - succeeded
          - failed
          - cancelled
          - skipped
        partial:
          type:
          - string
          - 'null'
        cost:
          type:
          - object
          - 'null'
          properties:
            input_tokens:
              type: integer
              minimum: 0
            output_tokens:
              type: integer
              minimum: 0
            usd:
              type:
              - number
              - 'null'
        timing:
          type: object
          properties:
            started_at:
              type:
              - string
              - 'null'
              format: date-time
            ended_at:
              type:
              - string
              - 'null'
              format: date-time
            ttft_ms:
              type:
              - number
              - 'null'
        route_decision_id:
          type:
          - string
          - 'null'
        last_sequence:
          type: integer
          minimum: 0
        children:
          type: array
          items:
            $ref: '#/components/schemas/RunNodeState'
    RunStatusSnapshot:
      type: object
      description: The current folded tree for a run, produced from its run.node events.
      properties:
        run_id:
          type: string
        status:
          type:
          - string
          - 'null'
          enum:
          - queued
          - running
          - waiting_approval
          - succeeded
          - failed
          - cancelled
          - skipped
          - null
        last_sequence:
          type: integer
        nodes:
          type: array
          items:
            $ref: '#/components/schemas/RunNodeState'
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer