---
title: "Trigger a task run"
method: POST
path: "/v2/tasks/{task_id}/trigger"
tags: ["Tasks"]
---

# Trigger a task run

`POST /v2/tasks/{task_id}/trigger`

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)
```json
{
  "experiment_name": "GPT-4o Baseline v2",
  "max_examples": 50
}
```

**Invalid example** (run_experiment trigger missing required `experiment_name`)
```json
{
  "max_examples": 50
}
```

<Note>This endpoint is in beta, read more [here](https://arize.com/docs/ax/rest-reference#api-version-stages).</Note>

## Path parameters

- `task_id` string, required — A universally unique identifier (base64-encoded opaque string).

## Request body

- union — Trigger body for `POST /v2/tasks/{task_id}/trigger`. The server derives the task type from the URL's task record and selects the appropriate schema; the body itself does not carry a `task_type` field. | Task type | Schema | |---|---| | `TEMPLATE_EVALUATION` | `TriggerEvaluationTaskRunRequest` | | `CODE_EVALUATION` | `TriggerEvaluationTaskRunRequest` | | `RUN_EXPERIMENT` | `TriggerRunExperimentTaskRunRequest` | Sending a field that is not valid for the resolved task type returns 400. For `TEMPLATE_EVALUATION` and `CODE_EVALUATION` tasks all trigger fields are optional — an empty body is valid and uses server defaults.
  - TriggerEvaluationTaskRunRequest — Trigger request for `TEMPLATE_EVALUATION` or `CODE_EVALUATION` tasks. `data_start_time` and `data_end_time` together must span no more than 30 days. `data_start_time` must be before `data_end_time`.
    - `data_start_time` string, date-time — ISO 8601 start of the data window to evaluate. For model-based tasks, defaults to the task's last run time. Required on the first run (when no previous run exists). Not applicable to dataset-based tasks.
    - `data_end_time` string, date-time — ISO 8601 end of the data window to evaluate. For model-based tasks, defaults to now. Not applicable to dataset-based tasks.
    - `max_spans` integer — Maximum number of spans to process (default 10000).
    - `override_evaluations` boolean — Whether to re-evaluate data that already has evaluation labels (default `false`).
    - `experiment_ids` string[] — Experiment identifiers (base64) to run against. Only for dataset-based `TEMPLATE_EVALUATION` / `CODE_EVALUATION` tasks.
  - TriggerRunExperimentTaskRunRequest — Trigger request for `RUN_EXPERIMENT` tasks. `example_ids` and `max_examples` are mutually exclusive; at most one may be provided.
    - `experiment_name` string, required — Display name for the experiment to be created. Must be unique within the dataset.
    - `dataset_version_id` string — Dataset version identifier (base64). Defaults to the latest version when omitted.
    - `example_ids` string[] — Specific example IDs to run against. Mutually exclusive with `max_examples`. When both are omitted, all examples are used.
    - `max_examples` integer — Maximum number of examples to run (dataset order). Mutually exclusive with `example_ids`. When both are omitted, all examples are used.
    - `tracing_metadata` object — Arbitrary key-value metadata. Providing this enables tracing for the run.
    - `evaluation_task_ids` string[] — Task identifiers (base64) of evaluation tasks to trigger after the experiment run completes. Supported for all `RUN_EXPERIMENT` experiment types.

## Response `201`

Returns a single task run object

- TaskRun — A task run is an async job that executes the work defined on a task. Runs are created by triggering an existing task (`POST /v2/tasks/{task_id}/trigger`). For `RUN_EXPERIMENT` tasks, `experiment_id` is populated after the experiment is provisioned; poll `GET /v2/task-runs/{run_id}` until `status` reaches a terminal state.
  - `id` string, required — The unique identifier for the task run.
  - `task_id` string, required — The parent task identifier (base64).
  - `experiment_id` string, 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_at` string, date-time, nullable, required — When the run started processing.
  - `run_finished_at` string, date-time, nullable, required — When the run finished processing.
  - `data_start_time` string, date-time, nullable, required — Start of the data window evaluated. Null for run_experiment runs.
  - `data_end_time` string, date-time, nullable, required — End of the data window evaluated. Null for run_experiment runs.
  - `num_successes` integer, required — Number of successfully evaluated items.
  - `num_errors` integer, required — Number of items that errored during evaluation.
  - `num_skipped` integer, required — Number of items that were skipped.
  - `created_at` string, date-time, required — When the run was created.
  - `created_by_user_id` string, nullable, required — The unique identifier for the user who triggered the run.
  - `failure_reason` string, 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.

## Other responses

- `400` — Invalid request
- `401` — Authentication is required
- `403` — Insufficient permissions to access this resource
- `404` — Not found
- `409` — Resource conflict
- `422` — Unprocessable entity
- `429` — Rate limit exceeded

---

[API](https://skmtc.net/arize-ai/apis/arize-rest-api.md) · [All operations](https://skmtc.net/arize-ai/apis/arize-rest-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/arize-ai/arize-rest-api/versions/2ce448f1de13/schema)