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

# Start Task Diagnostics

> Start diagnostics for up to 10 tasks in an existing benchmark after its images are ready.



## OpenAPI

````yaml /openapi.json post /api/v1/diagnostics/task/run
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/diagnostics/task/run:
    post:
      tags:
        - diagnostics
      summary: Start Task Diagnostics
      description: >-
        Start diagnostics for up to 10 tasks in an existing benchmark after its
        images are ready.
      operationId: startTaskDiagnostics
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/StartBenchmarkDiagnosticsRequest'
        required: true
      responses:
        '201':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StartBenchmarkDiagnosticsResponse'
        '429':
          description: >-
            The organization reached its concurrent evaluation or training run
            limit; retry after an active run finishes.
          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/ConcurrencyLimitExceededErrorResponse'
        default:
          $ref: '#/components/responses/ApiErrorResponse'
      security:
        - ApiKeyAuth: []
components:
  schemas:
    StartBenchmarkDiagnosticsRequest:
      properties:
        bench_id:
          type: string
          title: Bench Id
        base_model_slug:
          $ref: '#/components/schemas/BaseModelSlug'
          default: nvidia/NVIDIA-Nemotron-3.5-Lightning-30B-A3B-BF16
        options:
          anyOf:
            - $ref: '#/components/schemas/RunOptions'
            - type: 'null'
          description: >-
            Evaluation settings, as for createEvalRun, such as reasoning_effort
            and max_output_tokens_per_turn; the diagnostic sets its own sample
            counts.
      additionalProperties: false
      type: object
      required:
        - bench_id
      title: StartBenchmarkDiagnosticsRequest
    StartBenchmarkDiagnosticsResponse:
      properties:
        benchmark_diagnostic_id:
          type: string
          title: Benchmark Diagnostic Id
        bench_id:
          type: string
          title: Bench Id
        status:
          type: string
          const: pending
          title: Status
      type: object
      required:
        - benchmark_diagnostic_id
        - bench_id
        - status
      title: StartBenchmarkDiagnosticsResponse
    ConcurrencyLimitExceededErrorResponse:
      properties:
        error:
          $ref: '#/components/schemas/ConcurrencyLimitExceededErrorBody'
      type: object
      required:
        - error
      title: ConcurrencyLimitExceededErrorResponse
    BaseModelSlug:
      type: string
      enum:
        - thinkingmachines/Inkling-Small
        - Qwen/Qwen3.5-4B
        - Qwen/Qwen3.5-397B-A17B
        - Qwen/Qwen3.6-35B-A3B
        - Qwen/Qwen3.8-27B
        - nvidia/NVIDIA-Nemotron-3-Ultra-550B-A55B-BF16
        - nvidia/NVIDIA-Nemotron-3-Super-120B-A12B-BF16
        - nvidia/NVIDIA-Nemotron-3.5-Lightning-30B-A3B-BF16
        - nvidia/NVIDIA-Nemotron-3.5-Super-120B-A12B-BF16
        - openai/gpt-6.1-sol
        - openai/gpt-6-sol
        - openai/gpt-6-astra
        - openai/gpt-5.6-sol
        - openai/gpt-5.6-luna
        - anthropic/claude-opus-5.5
        - anthropic/claude-sonnet-5.5
        - openai/gpt-5-mini
        - openai/gpt-5.4-mini
        - openai/gpt-5.5
        - anthropic/claude-sonnet-4.6
        - google/gemini-3.1-pro-preview
        - z-ai/glm-5.3
        - z-ai/glm-5.3-flash
        - moonshotai/kimi-k3
      title: BaseModelSlug
    RunOptions:
      properties:
        load_weights_only:
          anyOf:
            - type: boolean
            - type: 'null'
          title: Load Weights Only
          description: >-
            Load parent checkpoint weights with fresh training state. Defaults
            to false, which resumes the optimizer, LR schedule, and global step.
            With validation enabled, evaluate the starting policy, run
            validation when global_step % val_interval_steps == 0, and evaluate
            the final policy on normal completion. Resuming preserves the global
            step and validation cadence.
        density_aware_training:
          anyOf:
            - type: boolean
            - type: 'null'
          title: Density Aware Training
          description: >-
            Train each task at four output-token budgets, with group_size
            trajectories per budget. Turns on train_on_truncation, which must
            stay true except when resuming a checkpoint with its training state.
            batch_size sets the total number of task groups per batch; each
            budget counts as a separate group. Learn more:
            https://www.trajectory.ai/field-notes/intelligence-density
        algorithm:
          anyOf:
            - $ref: '#/components/schemas/TrainingAlgorithm'
            - type: 'null'
          description: Training algorithm; omit to preserve the model default.
        train_on_truncation:
          anyOf:
            - type: boolean
            - type: 'null'
          title: Train On Truncation
          description: >-
            Include trajectories that hit token or turn limits in training, with
            reward 0. Defaults to false, or true with density_aware_training;
            set to true to discourage reward hacking through truncated
            submissions.
        train_on_error:
          anyOf:
            - type: boolean
            - type: 'null'
          title: Train On Error
          description: >-
            Train on errored trajectories, including execution errors, grading
            errors, and missing grades, with reward 0.
        train_on_timeout:
          anyOf:
            - type: boolean
            - type: 'null'
          title: Train On Timeout
          description: >-
            Include timed-out trajectories in training, with reward 0. Defaults
            to false; set to true to discourage reward hacking through timed-out
            submissions.
        val_enabled:
          anyOf:
            - type: boolean
            - type: 'null'
          title: Val Enabled
          description: Enable validation during training.
        val_interval_steps:
          anyOf:
            - type: integer
              maximum: 100
              minimum: 0
            - type: 'null'
          title: Val Interval Steps
          description: Training steps between validations; 0 disables validation.
        val_num_tasks:
          anyOf:
            - type: integer
              minimum: 1
            - type: 'null'
          title: Val Num Tasks
          description: >-
            Maximum distinct tasks per evaluation. Standalone evals run every
            task in the selected scope when omitted.
        val_trajectories_per_task:
          anyOf:
            - type: integer
              minimum: 1
            - type: 'null'
          title: Val Trajectories Per Task
          description: >-
            Number of trajectories generated for each task in a validation
            round.
        val_max_concurrent_trajectories:
          anyOf:
            - type: integer
              minimum: 1
            - type: 'null'
          title: Val Max Concurrent Trajectories
          description: Maximum number of validation trajectories running concurrently.
        val_final_wait_timeout_seconds:
          anyOf:
            - type: number
              minimum: 0
            - type: 'null'
          title: Val Final Wait Timeout Seconds
          description: >-
            Maximum seconds to wait for outstanding validation rounds at
            training end.
        learning_rate:
          anyOf:
            - type: number
              maximum: 0.01
              minimum: 1.e-8
            - type: 'null'
          title: Learning Rate
          description: Base optimizer learning rate.
        lr_warmup_steps:
          anyOf:
            - type: integer
              maximum: 100000
              minimum: 0
            - type: 'null'
          title: Lr Warmup Steps
          description: >-
            Reported training steps used for warmup, including skipped optimizer
            updates.
        lr_hold_steps:
          anyOf:
            - type: integer
              maximum: 100000
              minimum: 0
            - type: 'null'
          title: Lr Hold Steps
          description: >-
            Training steps to hold the base rate after warmup, including skipped
            updates, before cosine decay.
        lr_min_ratio:
          anyOf:
            - type: number
              maximum: 1
              minimum: 0
            - type: 'null'
          title: Lr Min Ratio
          description: Cosine decay floor as a fraction of the base learning rate.
        reasoning_effort:
          anyOf:
            - type: string
              enum:
                - 'off'
                - 'on'
                - minimal
                - low
                - medium
                - high
                - xhigh
                - max
            - type: 'null'
          title: Reasoning Effort
          description: >-
            Model reasoning effort. null selects the lowest supported thinking
            level; off disables thinking where supported. Levels: minimal, low,
            medium, high, xhigh, max, depending on the model. Qwen3.5-4B,
            Qwen3.6-35B-A3B, Qwen3.5-397B-A17B, and
            Nemotron-3.5-Lightning-30B-A3B support only on/off; null selects on.
        temperature:
          anyOf:
            - type: number
              maximum: 2
              minimum: 0
            - type: 'null'
          title: Temperature
          description: Sampling temperature; defaults to 1.0.
        top_p:
          anyOf:
            - type: number
              maximum: 1
              minimum: 0
            - type: 'null'
          title: Top P
          description: Nucleus sampling probability; null preserves the model default.
        top_k:
          anyOf:
            - type: integer
              minimum: -1
            - type: 'null'
          title: Top K
          description: >-
            Sample from the top k tokens; -1 disables the limit, and null
            preserves the model default.
        val_reasoning_effort:
          anyOf:
            - type: string
              enum:
                - 'off'
                - 'on'
                - minimal
                - low
                - medium
                - high
                - xhigh
                - max
            - type: 'null'
          title: Val Reasoning Effort
          description: >-
            Validation reasoning effort. null inherits training defaults.
            Supports the same model-specific levels and on/off options as
            reasoning_effort.
        val_temperature:
          anyOf:
            - type: number
              maximum: 2
              minimum: 0
            - type: 'null'
          title: Val Temperature
          description: Validation sampling temperature. null inherits training defaults.
        val_top_p:
          anyOf:
            - type: number
              maximum: 1
              minimum: 0
            - type: 'null'
          title: Val Top P
          description: >-
            Validation nucleus sampling probability. null inherits training
            defaults.
        val_top_k:
          anyOf:
            - type: integer
              minimum: -1
            - type: 'null'
          title: Val Top K
          description: >-
            Validation top-k token limit. null inherits training defaults; -1
            disables it.
        val_max_output_tokens_per_turn:
          anyOf:
            - type: integer
              maximum: 262144
              minimum: 1
            - type: 'null'
          title: Val Max Output Tokens Per Turn
          description: >-
            Maximum output tokens per turn in each validation trajectory. null
            inherits training defaults.
        val_max_output_tokens_per_trajectory:
          anyOf:
            - type: integer
              maximum: 2097152
              minimum: 1
            - type: 'null'
          title: Val Max Output Tokens Per Trajectory
          description: >-
            Maximum output tokens across one validation trajectory. null
            inherits training defaults.
        val_max_turns_per_trajectory:
          anyOf:
            - type: integer
              maximum: 500
              minimum: 1
            - type: 'null'
          title: Val Max Turns Per Trajectory
          description: >-
            Maximum agent and environment turns per validation trajectory. null
            inherits training defaults.
        val_trajectory_timeout_seconds:
          anyOf:
            - type: integer
              maximum: 36000
              minimum: 1
            - type: 'null'
          title: Val Trajectory Timeout Seconds
          description: >-
            Maximum execution seconds per validation trajectory, including
            grading. null inherits training defaults.
        num_steps:
          anyOf:
            - type: integer
              maximum: 100000
              minimum: 1
            - type: 'null'
          title: Num Steps
          description: Number of optimizer steps to run.
        batch_size:
          anyOf:
            - type: integer
              maximum: 256
              minimum: 1
            - type: 'null'
          title: Batch Size
          description: Eligible task-instance groups per optimizer update.
        group_size:
          anyOf:
            - type: integer
              maximum: 32
              minimum: 1
            - type: 'null'
          title: Group Size
          description: >-
            Trajectories generated for each training instance; GSPO and GRPO
            require at least 2.
        min_trajectories_per_group:
          anyOf:
            - type: integer
              maximum: 32
              minimum: 1
            - type: 'null'
          title: Min Trajectories Per Group
          description: >-
            Minimum eligible trajectories per training group. null uses half of
            group_size, rounded down.
        max_concurrent_trajectories:
          anyOf:
            - type: integer
              maximum: 1024
              minimum: 1
            - type: 'null'
          title: Max Concurrent Trajectories
          description: >-
            Maximum active training trajectories. null uses batch_size ×
            group_size × 2, allowing 2× batch oversampling for throughput and
            asynchronous RL. Recommended: set above batch_size × group_size to
            keep collection ahead of training.
        max_staleness:
          anyOf:
            - type: integer
              maximum: 100
              minimum: 0
            - type: 'null'
          title: Max Staleness
          description: >-
            Maximum optimizer steps a training rollout’s starting policy may
            trail the current policy. Older in-flight rollouts are cancelled and
            older completed rollouts are discarded; 0 trains only on rollouts
            started from the current policy.
        train_on_all_fail:
          anyOf:
            - type: boolean
            - type: 'null'
          title: Train On All Fail
          description: >-
            Train on groups whose eligible rewards are all at or below zero;
            false excludes them.
        train_on_all_pass:
          anyOf:
            - type: boolean
            - type: 'null'
          title: Train On All Pass
          description: >-
            Train on groups whose eligible rewards are all at or above one;
            false excludes them.
        train_on_zero_advantage:
          anyOf:
            - type: boolean
            - type: 'null'
          title: Train On Zero Advantage
          description: >-
            Train on groups with identical eligible rewards; false excludes
            them.
        trajectory_timeout_seconds:
          anyOf:
            - type: integer
              maximum: 36000
              minimum: 1
            - type: 'null'
          title: Trajectory Timeout Seconds
          description: >-
            Maximum execution seconds per trajectory, including grading.
            Excludes queueing and sandbox startup. Collection timeouts must
            cover this budget.
        batch_timeout_seconds:
          anyOf:
            - type: integer
              maximum: 38400
              minimum: 1
            - type: 'null'
          title: Batch Timeout Seconds
          description: >-
            Maximum wall-clock time to assemble one training batch. The clock
            starts when collection begins and does not reset as groups or
            in-flight trajectories arrive. Must cover trajectory execution and
            is not adjusted automatically.
        max_output_tokens_per_turn:
          anyOf:
            - type: integer
              maximum: 262144
              minimum: 1
            - type: 'null'
          title: Max Output Tokens Per Turn
          description: >-
            Maximum output tokens per model response. null uses the model’s
            maximum, bounded by remaining context.
        max_output_tokens_per_trajectory:
          anyOf:
            - type: integer
              maximum: 2097152
              minimum: 1
            - type: 'null'
          title: Max Output Tokens Per Trajectory
          description: >-
            Maximum output tokens across one trajectory, including after context
            compaction. null uses the model’s maximum supported context length.
        max_turns_per_trajectory:
          anyOf:
            - type: integer
              maximum: 500
              minimum: 1
            - type: 'null'
          title: Max Turns Per Trajectory
          description: Maximum agent and environment turns allowed in each trajectory.
      additionalProperties: false
      type: object
      title: RunOptions
    ConcurrencyLimitExceededErrorBody:
      properties:
        type:
          type: string
          const: rate_limit_error
          title: Type
        code:
          type: string
          const: concurrency_limit_exceeded
          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/ConcurrencyLimitContext'
      type: object
      required:
        - type
        - code
        - message
        - doc_url
        - context
      title: ConcurrencyLimitExceededErrorBody
    ApiErrorEnvelope:
      properties:
        error:
          $ref: '#/components/schemas/ApiErrorBody'
      required:
        - error
      title: ApiErrorEnvelope
      type: object
    TrainingAlgorithm:
      type: string
      enum:
        - gspo
        - grpo
      title: TrainingAlgorithm
    ConcurrencyLimitContext:
      properties:
        resource:
          $ref: '#/components/schemas/ConcurrencyResource'
        limit:
          type: integer
          title: Limit
        usage:
          type: integer
          title: Usage
      additionalProperties: false
      type: object
      required:
        - resource
        - limit
        - usage
      title: ConcurrencyLimitContext
    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
    ConcurrencyResource:
      type: string
      enum:
        - evaluation
        - training
      title: ConcurrencyResource
    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.