Sign in

v2

latestOpenAPI 3.0.3Apache-2.02026-08-07119359591.9 KB
Tasks

Trigger a task run

Triggers a new run on an existing task. The run is queued and processed asynchronously. Poll GET /v2/task-runs/{run_id} until the run reaches a terminal status (completed, failed, or cancelled).

Payload Requirements

  • Fields must match the task's type; sending inapplicable fields returns 400.
  • For TEMPLATE_EVALUATION / CODE_EVALUATION tasks, all trigger fields are optional — an empty body uses server defaults.
  • For RUN_EXPERIMENT tasks, experiment_name is required.

For RUN_EXPERIMENT tasks

Supply experiment_name (required) plus any of the optional per-run fields: dataset_version_id, example_ids (exclusive with max_examples), max_examples, tracing_metadata, evaluation_task_ids.

The fields data_start_time, data_end_time, max_spans, override_evaluations, and experiment_ids are not applicable and will return 400 if supplied.

The response includes experiment_id once the experiment is provisioned.

For TEMPLATE_EVALUATION / CODE_EVALUATION tasks

Supply data_start_time, data_end_time, max_spans, override_evaluations, and/or experiment_ids as needed. RUN_EXPERIMENT-specific fields are not applicable for these task types.

Valid example (trigger a run_experiment run)

{
  "experiment_name": "GPT-4o Baseline v2",
  "max_examples": 50
}

Invalid example (run_experiment trigger missing required experiment_name)

{
  "max_examples": 50
}

<Note>This endpoint is in beta, read more here.</Note>

post/v2/tasks/{task_id}/trigger

Path parameters

task_idstring required

A universally unique identifier (base64-encoded opaque string).

Example:RW50aXR5OjEyMzQ1

The unique task identifier (base64)

Request body

OR

Response

Returns a single task run object

idstring required

The unique identifier for the task run.

task_idstring required

The parent task identifier (base64).

experiment_idstring nullable

Created experiment identifier (base64). Present only for RUN_EXPERIMENT task runs; null for all other task types.

status'PENDING' | 'RUNNING' | 'COMPLETED' | 'FAILED' | 'CANCELLED' required

Status of a task run.

  • PENDING - The run has been created but not yet started.
  • RUNNING - The run is currently in progress.
  • COMPLETED - The run finished successfully.
  • FAILED - The run encountered an error and stopped.
  • CANCELLED - The run was cancelled before completion.
run_started_atstring date-time nullable required

When the run started processing.

run_finished_atstring date-time nullable required

When the run finished processing.

data_start_timestring date-time nullable required

Start of the data window evaluated. Null for run_experiment runs.

data_end_timestring date-time nullable required

End of the data window evaluated. Null for run_experiment runs.

num_successesinteger required

Number of successfully evaluated items.

num_errorsinteger required

Number of items that errored during evaluation.

num_skippedinteger required

Number of items that were skipped.

created_atstring date-time required

When the run was created.

created_by_user_idstring nullable required

The unique identifier for the user who triggered the run.

failure_reasonstring nullable

Human-readable explanation of why the run failed or was cancelled; null for successful runs. For example, when all matching data already has evaluation labels from a previous run, the task cancels with zero successes, errors, and skipped items, and this field explains that the task must be re-triggered with override_evaluations enabled to re-evaluate it.