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

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

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

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




## OpenAPI

````yaml https://api.arize.com/v2/spec.yaml post /v2/tasks/{task_id}/trigger
openapi: 3.0.3
info:
  title: Arize REST API
  version: 2.0.0
  description: |
    API specification for the backend data server. The API is hosted globally
    at https://api.arize.com/v2 or in your own environment.
  license:
    name: Apache-2.0
    url: https://www.apache.org/licenses/LICENSE-2.0
servers:
  - description: Global
    url: https://api.arize.com
  - description: Regional
    url: https://api.{region}.arize.com
    variables:
      region:
        default: eu-west-1a
        enum:
          - eu-west-1a
          - ca-central-1a
  - description: Custom Host
    url: https://{host}
    variables:
      host:
        default: api.arize.com
security:
  - bearerAuth: []
tags:
  - name: AI Integrations
    description: |
      AI integrations configure access to external LLM providers (e.g. OpenAI,
      Azure OpenAI, AWS Bedrock, Vertex AI). Integrations can be scoped to the
      entire account, a specific organization, or a specific space.
  - name: Annotation Configs
    description: >
      Annotation configs allow you to define consistent annotation schemas that

      can be reused across your workspace, ensuring evaluations are structured
      and

      comparable over time.
  - name: Annotation Queues
    description: >
      Annotation queues help you organize and manage human evaluation workflows.

      Use queues to assign spans or examples to annotators for review and
      labeling.
  - name: API Keys
    description: >
      API keys are used to authenticate requests to the Arize API. List your
      keys

      to view metadata; the raw secret is never returned after creation.
  - name: Datasets
    description: |
      Datasets are structured, version-controlled example collections you use to
      run, evaluate, and track LLM experiments.
  - name: Evaluators
    description: >
      Evaluators are reusable evaluation configurations used to assess the
      quality

      of LLM outputs. They can be template-based (using LLM judges) or
      code-based.
  - name: Experiments
    description: >
      Experiments let you systematically test prompt/model changes using
      datasets,

      tasks, and evaluators.
  - name: Integrations
    description: >
      Integrations configure access to external LLM providers (e.g. OpenAI,

      Azure OpenAI, AWS Bedrock, Vertex AI), notifications services (e.g.
      PagerDuty, Slack), and

      your own agents. Integrations can be scoped to the entire account, a
      specific

      organization, or a specific space.
  - name: Organizations
    description: >
      Organizations are top-level containers within an Arize AX account for
      grouping spaces.
  - name: Projects
    description: |
      Projects represent LLM applications being monitored in Arize where you can
      observe traces and spans.
  - name: Prompts
    description: >
      Prompts are reusable, versioned templates for LLM interactions. Use
      prompts

      to standardize and manage how you interact with LLMs across your
      application.
  - name: Resource Restrictions
    description: |
      Endpoints for restricting and unrestricting resources (projects, models).
  - name: Role Bindings
    description: |
      Role bindings assign a role to a user on a resource. REST currently
      supports space- and project-scoped bindings.
  - name: Roles
    description: >
      Roles define sets of permissions that can be assigned to users within an

      account. Create custom roles to tailor access control to your team's
      needs.
  - name: Spaces
    description: >
      Spaces are containers within an organization for grouping related
      projects,

      datasets, and experiments, enabling collaboration or isolated
      experimentation

      with role-based access control.
  - name: Spans
    description: |
      Spans represent individual operations within a trace. A span captures the
      timing, status, and attributes of a single operation in your application.
  - name: Tasks
    description: |
      Tasks are configurable units of work that tie one or more evaluators to a
      data source (project or dataset). Use tasks to automate evaluation of LLM
      outputs, with support for continuous evaluation and backfill runs.
  - name: Users
    description: >
      Users represent members of an account. The Users endpoints allow creating,

      listing, updating (display name), and removing users from the account
      programmatically.
paths:
  /v2/tasks/{task_id}/trigger:
    post:
      tags:
        - Tasks
      summary: Trigger a task run
      description: >
        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
        }

        ```


        <Warning>This endpoint is in alpha, read more
        [here](https://arize.com/docs/ax/rest-reference#api-version-stages).</Warning>
      operationId: tasks_trigger_run
      parameters:
        - $ref: '#/components/parameters/TaskIdPathParam'
      requestBody:
        $ref: '#/components/requestBodies/TriggerTaskRunRequestBody'
      responses:
        '201':
          $ref: '#/components/responses/TaskRunCreated'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '409':
          $ref: '#/components/responses/Conflict'
        '422':
          $ref: '#/components/responses/UnprocessableEntity'
        '429':
          $ref: '#/components/responses/RateLimitExceeded'
components:
  parameters:
    TaskIdPathParam:
      name: task_id
      in: path
      required: true
      description: The unique task identifier (base64)
      schema:
        $ref: '#/components/schemas/Id'
      example: VGFzazoxMjM0NQ==
  requestBodies:
    TriggerTaskRunRequestBody:
      description: >
        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.
      required: false
      content:
        application/json:
          schema:
            anyOf:
              - $ref: '#/components/schemas/TriggerEvaluationTaskRunRequest'
              - $ref: '#/components/schemas/TriggerRunExperimentTaskRunRequest'
          examples:
            evaluation:
              summary: Trigger a template/code evaluation run
              value:
                data_start_time: '2026-03-01T00:00:00Z'
                data_end_time: '2026-03-07T00:00:00Z'
                max_spans: 5000
                override_evaluations: false
            run_experiment:
              summary: Trigger a run_experiment run
              value:
                experiment_name: GPT-4o Baseline v2
                max_examples: 50
                tracing_metadata:
                  source: api
  responses:
    TaskRunCreated:
      description: Returns the created task run
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/TaskRun'
          example:
            id: VGFza1J1bjo5OTpxUndY
            task_id: T25saW5lVGFzazo0NTpxUndY
            status: pending
            run_started_at: null
            run_finished_at: null
            data_start_time: '2026-03-01T00:00:00.000Z'
            data_end_time: '2026-03-07T00:00:00.000Z'
            num_successes: 0
            num_errors: 0
            num_skipped: 0
            created_at: '2026-03-07T10:30:00.000Z'
            created_by_user_id: VXNlcjoxOm5OYkM=
    BadRequest:
      description: Invalid request
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/Problem'
          example:
            status: 400
            title: Invalid request parameters
            detail: The 'name' field is required and must be a non-empty string.
            instance: /resource
            type: https://arize.com/docs/ax/rest-reference/errors#invalid-request
    Unauthorized:
      description: Authentication is required
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/Problem'
          example:
            status: 401
            title: Authentication required
            detail: You must be authenticated to access this resource.
            instance: /resource
            type: >-
              https://arize.com/docs/ax/rest-reference/errors#authentication-required
    Forbidden:
      description: Insufficient permissions to access this resource
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/Problem'
          example:
            status: 403
            title: Access forbidden
            detail: You do not have permission to access this resource.
            instance: /resource/12345
            type: https://arize.com/docs/ax/rest-reference/errors#access-forbidden
    NotFound:
      description: Not found
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/Problem'
          example:
            status: 404
            title: Resource not found
            detail: The requested resource with ID '12345' was not found.
            instance: /resource/12345
            type: https://arize.com/docs/ax/rest-reference/errors#resource-not-found
    Conflict:
      description: Resource conflict
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/Problem'
          example:
            status: 409
            title: Resource conflict
            detail: A resource with the given identifier already exists.
            instance: /resource
            type: https://arize.com/docs/ax/rest-reference/errors#resource-conflict
    UnprocessableEntity:
      description: Unprocessable entity
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/Problem'
          example:
            status: 422
            title: Unprocessable Entity
            detail: Minimum score must be less than maximum score.
            instance: /annotation-configs
            type: >-
              https://arize.com/docs/ax/rest-reference/errors#unprocessable-entity
    RateLimitExceeded:
      description: Rate limit exceeded
      headers:
        Retry-After:
          description: |
            When throttled (429), how long to wait before retrying. Value is
            either a delta-seconds integer.
          schema:
            type: integer
            minimum: 0
          example: 42
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/Problem'
          example:
            status: 429
            title: Rate limit exceeded
            detail: >-
              You have exceeded the allowed number of requests. Please try again
              later.
            instance: /resource
            type: >-
              https://arize.com/docs/ax/rest-reference/errors#rate-limit-exceeded
  schemas:
    Id:
      type: string
      description: A universally unique identifier (base64-encoded opaque string).
      example: RW50aXR5OjEyMzQ1
    TriggerEvaluationTaskRunRequest:
      type: object
      properties:
        data_start_time:
          type: string
          format: date-time
          description: >
            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:
          type: string
          format: date-time
          description: |
            ISO 8601 end of the data window to evaluate. For model-based tasks,
            defaults to now. Not applicable to dataset-based tasks.
        max_spans:
          type: integer
          minimum: 1
          description: Maximum number of spans to process (default 10000).
        override_evaluations:
          type: boolean
          description: |
            Whether to re-evaluate data that already has evaluation labels
            (default `false`).
        experiment_ids:
          type: array
          items:
            type: string
          description: >
            Experiment identifiers (base64) to run against. Only for
            dataset-based

            `template_evaluation` / `code_evaluation` tasks.
      additionalProperties: false
      description: >
        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`.
    TriggerRunExperimentTaskRunRequest:
      type: object
      required:
        - experiment_name
      properties:
        experiment_name:
          type: string
          description: |
            Display name for the experiment to be created. Must be unique within
            the dataset.
        dataset_version_id:
          type: string
          description: |
            Dataset version identifier (base64). Defaults to the latest version
            when omitted.
        example_ids:
          type: array
          items:
            type: string
          description: |
            Specific example IDs to run against. Mutually exclusive with
            `max_examples`. When both are omitted, all examples are used.
        max_examples:
          type: integer
          minimum: 1
          description: >
            Maximum number of examples to run (dataset order). Mutually
            exclusive

            with `example_ids`. When both are omitted, all examples are used.
        tracing_metadata:
          type: object
          additionalProperties:
            type: string
          description: |
            Arbitrary key-value metadata. Providing this enables tracing for
            the run.
        evaluation_task_ids:
          type: array
          items:
            type: string
          description: |
            Task identifiers (base64) of evaluation tasks to trigger after the
            experiment run completes. Supported for all `run_experiment`
            experiment types.
      additionalProperties: false
      description: >
        Trigger request for `run_experiment` tasks. `example_ids` and
        `max_examples`

        are mutually exclusive; at most one may be provided.
    TaskRun:
      type: object
      required:
        - id
        - task_id
        - status
        - run_started_at
        - run_finished_at
        - data_start_time
        - data_end_time
        - num_successes
        - num_errors
        - num_skipped
        - created_at
        - created_by_user_id
      properties:
        id:
          type: string
          description: The unique identifier for the task run.
        task_id:
          type: string
          description: The parent task identifier (base64).
        experiment_id:
          type: string
          nullable: true
          description: >
            Created experiment identifier (base64). Present only for
            `run_experiment`

            task runs; null for all other task types.
        status:
          $ref: '#/components/schemas/TaskRunStatus'
        run_started_at:
          type: string
          format: date-time
          nullable: true
          description: When the run started processing.
        run_finished_at:
          type: string
          format: date-time
          nullable: true
          description: When the run finished processing.
        data_start_time:
          type: string
          format: date-time
          nullable: true
          description: Start of the data window evaluated. Null for run_experiment runs.
        data_end_time:
          type: string
          format: date-time
          nullable: true
          description: End of the data window evaluated. Null for run_experiment runs.
        num_successes:
          type: integer
          description: Number of successfully evaluated items.
        num_errors:
          type: integer
          description: Number of items that errored during evaluation.
        num_skipped:
          type: integer
          description: Number of items that were skipped.
        created_at:
          type: string
          format: date-time
          description: When the run was created.
        created_by_user_id:
          type: string
          nullable: true
          description: The unique identifier for the user who triggered the run.
      description: >
        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.
      additionalProperties: false
    Problem:
      type: object
      description: RFC 9457 Problem Details
      properties:
        title:
          type: string
          description: A short, human-readable summary of the problem type
        status:
          type: integer
          description: >-
            The HTTP status code generated by the origin server for this
            occurrence of the problem
        type:
          type: string
          format: uri-reference
          description: A URI reference that identifies the problem type
        detail:
          type: string
          description: >-
            A human-readable explanation specific to this occurrence of the
            problem
        instance:
          type: string
          format: uri-reference
          description: >-
            A URI reference that identifies the specific occurrence of the
            problem
      required:
        - title
        - status
      additionalProperties: false
    TaskRunStatus:
      type: string
      enum:
        - pending
        - running
        - completed
        - failed
        - cancelled
      description: |
        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.
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: <api-key>
      description: >
        Most Arize AI endpoints require authentication. For those endpoints that
        require authentication, include your API key in the request header using
        the format

        ``` Authorization: Bearer <api-key>

        ```

````