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

# Get Training Step Metrics

> Trainer timing, throughput, sequences per trajectory and k3 KL estimates for each committed update of a training run, in ascending training-step order. Steps trained before these metrics were recorded do not appear, and fields added later are null on earlier steps.



## OpenAPI

````yaml /openapi.json get /api/v1/train/{run_id}/step-metrics
openapi: 3.1.0
info:
  title: Trajectory API
  version: 0.1.0
  x-trajectory-api-version: '2026-10-14'
  description: >-
    This contract is API version 2026-10-14. The optional Trajectory-API-Version
    header pins it, and tmp-contract is accepted as an alias. Requests without
    the header get this version. Version 2026-10-07 and the pre-launch legacy
    response formats are retired.
servers:
  - url: https://api.trajectory.ai
security: []
tags:
  - name: agents
    x-group: Agents
  - name: benchmarks
    x-group: Specs (benchmarks)
  - name: diagnostics
    x-group: Diagnostics
  - name: benchmark-ingestion
    x-group: Spec (benchmark) submissions
  - name: eval
    x-group: Evaluations
  - name: training
    x-group: Training
  - name: deployments
    x-group: Deployments
  - name: model-endpoints
    x-group: Model endpoints
  - name: inference
    x-group: Inference
  - name: trajectories
    x-group: Trajectories
  - name: artifacts
    x-group: Artifacts
  - name: telemetry
    x-group: Telemetry
  - name: supported-models
    x-group: Supported models
  - name: organizations
    x-group: Organizations
  - name: secrets
    x-group: Secrets
paths:
  /api/v1/train/{run_id}/step-metrics:
    get:
      tags:
        - training
      summary: Get Training Step Metrics
      description: >-
        Trainer timing, throughput, sequences per trajectory and k3 KL estimates
        for each committed update of a training run, in ascending training-step
        order. Steps trained before these metrics were recorded do not appear,
        and fields added later are null on earlier steps.
      operationId: getTrainingStepMetrics
      parameters:
        - name: run_id
          in: path
          required: true
          schema:
            type: string
            title: Run Id
        - name: cursor
          in: query
          required: false
          schema:
            anyOf:
              - type: string
              - type: 'null'
            title: Cursor
        - name: limit
          in: query
          required: false
          schema:
            type: integer
            maximum: 200
            minimum: 1
            default: 25
            title: Limit
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TrainingStepMetricsPage'
        '400':
          description: >-
            The cursor is malformed, unsupported, or belongs to a different
            collection scope.
          headers:
            X-Request-ID:
              $ref: '#/components/headers/RequestId'
            Trajectory-Should-Retry:
              $ref: '#/components/headers/TrajectoryShouldRetry'
            Retry-After:
              $ref: '#/components/headers/RetryAfter'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InvalidCursorErrorResponse'
        '404':
          description: >-
            The requested resource does not exist or is not visible to the
            caller.
          headers:
            X-Request-ID:
              $ref: '#/components/headers/RequestId'
            Trajectory-Should-Retry:
              $ref: '#/components/headers/TrajectoryShouldRetry'
            Retry-After:
              $ref: '#/components/headers/RetryAfter'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ResourceNotFoundErrorResponse'
        '409':
          description: >-
            The operation conflicts with the current state or an idempotent
            request.
          headers:
            X-Request-ID:
              $ref: '#/components/headers/RequestId'
            Trajectory-Should-Retry:
              $ref: '#/components/headers/TrajectoryShouldRetry'
            Retry-After:
              $ref: '#/components/headers/RetryAfter'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ConflictErrorResponse'
        default:
          $ref: '#/components/responses/ApiErrorResponse'
      security:
        - ApiKeyAuth: []
components:
  schemas:
    TrainingStepMetricsPage:
      properties:
        items:
          items:
            $ref: '#/components/schemas/TrainingStepMetrics'
          type: array
          title: Items
        next_cursor:
          anyOf:
            - type: string
            - type: 'null'
          title: Next Cursor
        has_more:
          type: boolean
          title: Has More
        training_run_id:
          type: string
          title: Training Run Id
          description: Training run whose step metrics are returned.
      type: object
      required:
        - items
        - has_more
        - training_run_id
      title: TrainingStepMetricsPage
    InvalidCursorErrorResponse:
      properties:
        error:
          $ref: '#/components/schemas/InvalidCursorErrorBody'
      type: object
      required:
        - error
      title: InvalidCursorErrorResponse
    ResourceNotFoundErrorResponse:
      properties:
        error:
          $ref: '#/components/schemas/ResourceNotFoundErrorBody'
      type: object
      required:
        - error
      title: ResourceNotFoundErrorResponse
    ConflictErrorResponse:
      properties:
        error:
          $ref: '#/components/schemas/ConflictErrorBody'
      type: object
      required:
        - error
      title: ConflictErrorResponse
    TrainingStepMetrics:
      properties:
        step:
          type: integer
          title: Step
          description: >-
            Training step produced by this update; its checkpoint has the same
            step index.
        rollout_wait_seconds:
          anyOf:
            - type: number
            - type: 'null'
          title: Rollout Wait Seconds
          description: >-
            Seconds the trainer waited to collect this update's batch: rollouts
            for reinforcement learning, dataset reads for supervised
            fine-tuning. Rollouts run alongside training, so this is time the
            trainer was blocked, not total generation time.
        training_seconds:
          type: number
          title: Training Seconds
          description: >-
            Seconds the trainer spent on the update: forward/backward, the
            optimizer step, and any extra passes the algorithm needs, such as
            reference log-probabilities.
        forward_backward_seconds:
          anyOf:
            - type: number
            - type: 'null'
          title: Forward Backward Seconds
          description: >-
            Seconds until the forward/backward result arrived, including any
            provider queueing.
        optimizer_seconds:
          anyOf:
            - type: number
            - type: 'null'
          title: Optimizer Seconds
          description: >-
            Seconds the optimizer step added after the forward/backward result.
            Providers that run both in one batch can report close to zero.
        weight_sync_seconds:
          anyOf:
            - type: number
            - type: 'null'
          title: Weight Sync Seconds
          description: >-
            Seconds to export the updated weights for sampling. Near zero when
            the provider exports them in the same batch as the update.
        checkpoint_seconds:
          anyOf:
            - type: number
            - type: 'null'
          title: Checkpoint Seconds
          description: Seconds to save the step's training state.
        trainer_tokens_per_second:
          anyOf:
            - type: number
            - type: 'null'
          title: Trainer Tokens Per Second
          description: Trained input tokens divided by training_seconds.
        generated_tokens_per_second:
          anyOf:
            - type: number
            - type: 'null'
          title: Generated Tokens Per Second
          description: >-
            Generated tokens in the batch divided by the wall time since the
            previous batch. Null on the first step after training starts or
            resumes.
        learning_rate:
          anyOf:
            - type: number
            - type: 'null'
          title: Learning Rate
          description: >-
            Learning rate the update applied, after warmup and decay. Null for
            steps recorded before the trainer persisted it.
        kl_estimate_k3:
          anyOf:
            - type: number
            - type: 'null'
          title: Kl Estimate K3
          description: >-
            Mean k3 estimate of KL(sampler || learner) over the batch's action
            tokens with a nonzero advantage. Null for algorithms that do not
            estimate it.
        kl_estimate_k3_min:
          anyOf:
            - type: number
            - type: 'null'
          title: Kl Estimate K3 Min
          description: >-
            Lowest of the batch's per-sequence k3 estimates, each the mean over
            that sequence's action tokens with a nonzero advantage.
        kl_estimate_k3_max:
          anyOf:
            - type: number
            - type: 'null'
          title: Kl Estimate K3 Max
          description: Highest of the batch's per-sequence k3 estimates.
        kl_estimate_k3_p25:
          anyOf:
            - type: number
            - type: 'null'
          title: Kl Estimate K3 P25
          description: 25th percentile of the batch's per-sequence k3 estimates.
        kl_estimate_k3_p50:
          anyOf:
            - type: number
            - type: 'null'
          title: Kl Estimate K3 P50
          description: Median of the batch's per-sequence k3 estimates.
        kl_estimate_k3_p75:
          anyOf:
            - type: number
            - type: 'null'
          title: Kl Estimate K3 P75
          description: 75th percentile of the batch's per-sequence k3 estimates.
        kl_estimate_k3_by_staleness:
          items:
            $ref: '#/components/schemas/StalenessKlPart'
          type: array
          title: Kl Estimate K3 By Staleness
          description: >-
            kl_estimate_k3's part from each sample staleness in the batch, by
            ascending staleness. The parts add up to the estimate, less any
            hindsight copies, which no policy sampled. Empty when the batch's
            sample staleness is unknown.
        sequences_per_trajectory_mean:
          anyOf:
            - type: number
            - type: 'null'
          title: Sequences Per Trajectory Mean
          description: >-
            Mean trained sequences per trajectory in the batch. A trajectory
            starts another sequence whenever a turn does not extend the previous
            turn's context.
        sequences_per_trajectory_min:
          anyOf:
            - type: integer
            - type: 'null'
          title: Sequences Per Trajectory Min
          description: Fewest trained sequences of one trajectory in the batch.
        sequences_per_trajectory_max:
          anyOf:
            - type: integer
            - type: 'null'
          title: Sequences Per Trajectory Max
          description: Most trained sequences of one trajectory in the batch.
        sequences_per_trajectory_p25:
          anyOf:
            - type: number
            - type: 'null'
          title: Sequences Per Trajectory P25
          description: 25th percentile of trained sequences per trajectory in the batch.
        sequences_per_trajectory_p50:
          anyOf:
            - type: number
            - type: 'null'
          title: Sequences Per Trajectory P50
          description: Median trained sequences per trajectory in the batch.
        sequences_per_trajectory_p75:
          anyOf:
            - type: number
            - type: 'null'
          title: Sequences Per Trajectory P75
          description: 75th percentile of trained sequences per trajectory in the batch.
      type: object
      required:
        - step
        - rollout_wait_seconds
        - training_seconds
        - forward_backward_seconds
        - optimizer_seconds
        - weight_sync_seconds
        - checkpoint_seconds
        - trainer_tokens_per_second
        - generated_tokens_per_second
        - learning_rate
        - kl_estimate_k3
        - kl_estimate_k3_min
        - kl_estimate_k3_max
        - kl_estimate_k3_p25
        - kl_estimate_k3_p50
        - kl_estimate_k3_p75
        - kl_estimate_k3_by_staleness
        - sequences_per_trajectory_mean
        - sequences_per_trajectory_min
        - sequences_per_trajectory_max
        - sequences_per_trajectory_p25
        - sequences_per_trajectory_p50
        - sequences_per_trajectory_p75
      title: TrainingStepMetrics
    InvalidCursorErrorBody:
      properties:
        type:
          type: string
          const: invalid_request_error
          title: Type
        code:
          type: string
          const: invalid_cursor
          title: Code
        message:
          type: string
          title: Message
        param:
          anyOf:
            - type: string
            - type: 'null'
          title: Param
        doc_url:
          type: string
          title: Doc Url
        context:
          $ref: '#/components/schemas/EmptyErrorContext'
      type: object
      required:
        - type
        - code
        - message
        - doc_url
        - context
      title: InvalidCursorErrorBody
    ResourceNotFoundErrorBody:
      properties:
        type:
          type: string
          const: invalid_request_error
          title: Type
        code:
          type: string
          const: resource_not_found
          title: Code
        message:
          type: string
          title: Message
        param:
          anyOf:
            - type: string
            - type: 'null'
          title: Param
        doc_url:
          type: string
          title: Doc Url
        context:
          $ref: '#/components/schemas/EmptyErrorContext'
      type: object
      required:
        - type
        - code
        - message
        - doc_url
        - context
      title: ResourceNotFoundErrorBody
    ConflictErrorBody:
      properties:
        type:
          type: string
          const: conflict_error
          title: Type
        code:
          type: string
          const: conflict
          title: Code
        message:
          type: string
          title: Message
        param:
          anyOf:
            - type: string
            - type: 'null'
          title: Param
        doc_url:
          type: string
          title: Doc Url
        context:
          $ref: '#/components/schemas/EmptyErrorContext'
      type: object
      required:
        - type
        - code
        - message
        - doc_url
        - context
      title: ConflictErrorBody
    ApiErrorEnvelope:
      properties:
        error:
          $ref: '#/components/schemas/ApiErrorBody'
      required:
        - error
      title: ApiErrorEnvelope
      type: object
    StalenessKlPart:
      properties:
        staleness:
          type: integer
          title: Staleness
          description: >-
            Policy steps between the policy that sampled these sequences and the
            update.
        kl_estimate_k3:
          type: number
          title: Kl Estimate K3
          description: >-
            These sequences' k3 sum over their action tokens with a nonzero
            advantage, divided by all such tokens in the batch.
      type: object
      required:
        - staleness
        - kl_estimate_k3
      title: StalenessKlPart
    EmptyErrorContext:
      properties: {}
      additionalProperties: false
      type: object
      title: EmptyErrorContext
    ApiErrorBody:
      properties:
        type:
          $ref: '#/components/schemas/ErrorType'
        code:
          type: string
          title: Code
        message:
          type: string
          title: Message
        param:
          anyOf:
            - type: string
            - type: 'null'
          default: null
          title: Param
        doc_url:
          type: string
          title: Doc Url
        context:
          additionalProperties: true
          title: Context
          type: object
      required:
        - type
        - code
        - message
        - doc_url
        - context
      title: ApiErrorBody
      type: object
    ErrorType:
      enum:
        - invalid_request_error
        - authentication_error
        - permission_error
        - conflict_error
        - billing_error
        - rate_limit_error
        - dependency_error
        - api_error
      title: ErrorType
      type: string
  headers:
    RequestId:
      schema:
        type: string
    TrajectoryShouldRetry:
      schema:
        type: boolean
    RetryAfter:
      schema:
        type: string
  responses:
    ApiErrorResponse:
      description: >-
        Common API error. Possible codes: `authentication_required`,
        `permission_denied`, `validation_error`, `rate_limited`,
        `internal_error`, `service_unavailable`.
      headers:
        X-Request-ID:
          $ref: '#/components/headers/RequestId'
        Trajectory-Should-Retry:
          $ref: '#/components/headers/TrajectoryShouldRetry'
        Retry-After:
          $ref: '#/components/headers/RetryAfter'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ApiErrorEnvelope'
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: X-API-Key
      description: Organization API key

````

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