---
title: "Create task"
method: POST
path: "/v2/tasks"
tags: ["Tasks"]
---

# Create task

`POST /v2/tasks`

Creates a new task. Supported task types:

| `type` | Data source | Notes |
|---|---|---|
| `TEMPLATE_EVALUATION` | `project_id` or `dataset_id` | Requires `evaluators`. Supports continuous operation. |
| `CODE_EVALUATION` | `project_id` or `dataset_id` | Requires `evaluators`. Supports continuous operation. |
| `RUN_EXPERIMENT` | `dataset_id` only | Requires `run_configuration`. Never continuous. |

For `RUN_EXPERIMENT` tasks the run configuration is stored on the task.
Each trigger (`POST /v2/tasks/{task_id}/trigger`) supplies per-run fields
(`experiment_name`, optional example subset, etc.) and starts an async run.
Poll `GET /v2/task-runs/{run_id}` until `status` reaches a terminal state.

**Payload Requirements (template_evaluation / code_evaluation)**
- At least one evaluator is required.
- Duplicate evaluator IDs are not allowed.
- When `dataset_id` is provided, `experiment_ids` must contain at least one entry.
- `sampling_rate` and `is_continuous` are only supported on project-based tasks.
- System-managed fields (`id`, `created_at`, `updated_at`) are rejected on input.
- `evaluator_version_id` pins an evaluator to one version. Omit it (or send null)
  to run that evaluator's latest version, which is the default. The version must
  belong to the evaluator named by `evaluator_id`, and every evaluator on the task
  must resolve to the same data scope — both return 422. List an evaluator's
  versions with `GET /v2/evaluators/{evaluator_id}/versions`.

**Payload Requirements (run_experiment)**
- `dataset_id` is required; `project_id` must be omitted.
- `run_configuration` is required; `evaluators`, `experiment_ids`, `sampling_rate`,
  `is_continuous`, and `query_filter` must be omitted.

**Valid example** (template_evaluation, project-based)
```json
{
  "name": "Production Hallucination Check",
  "type": "TEMPLATE_EVALUATION",
  "project_id": "TW9kZWw6MTIzOmFCY0Q=",
  "sampling_rate": 1.0,
  "is_continuous": true,
  "evaluators": [
    {
      "evaluator_id": "RXZhbHVhdG9yOjEyOmFCY0Q=",
      "column_mappings": {"input": "attributes.input.value", "output": "attributes.output.value"}
    }
  ]
}
```

**Valid example** (pinned to a specific evaluator version)
```json
{
  "name": "Hallucination Check v3",
  "type": "TEMPLATE_EVALUATION",
  "project_id": "TW9kZWw6MTIzOmFCY0Q=",
  "evaluators": [
    {
      "evaluator_id": "RXZhbHVhdG9yOjEyOmFCY0Q=",
      "evaluator_version_id": "RXZhbHVhdG9yVmVyc2lvbjo5OTphQmNE",
      "column_mappings": {"input": "attributes.input.value"}
    }
  ]
}
```

**Invalid example** (run_experiment missing `run_configuration`)
```json
{
  "name": "My Experiment",
  "type": "RUN_EXPERIMENT",
  "dataset_id": "RGF0YXNldDo1NjpxUndY"
}
```

**Invalid example** (422 — the version belongs to a different evaluator)
```json
{
  "name": "Mismatched Pin",
  "type": "TEMPLATE_EVALUATION",
  "project_id": "TW9kZWw6MTIzOmFCY0Q=",
  "evaluators": [
    {
      "evaluator_id": "RXZhbHVhdG9yOjEyOmFCY0Q=",
      "evaluator_version_id": "RXZhbHVhdG9yVmVyc2lvbjo3OmFCY0Q="
    }
  ]
}
```

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

## Request body

- union — Request body for creating a task. The `type` field is the discriminator. | `type` | Schema | |---|---| | `TEMPLATE_EVALUATION` | `CreateTemplateEvaluationTaskRequest` | | `CODE_EVALUATION` | `CreateCodeEvaluationTaskRequest` | | `RUN_EXPERIMENT` | `CreateRunExperimentTaskRequest` | `RUN_EXPERIMENT` tasks do not run continuously — they must be triggered explicitly via `POST /v2/tasks/{task_id}/trigger` each time.
  - CreateTemplateEvaluationTaskRequest — Request body for creating a `TEMPLATE_EVALUATION` task. Requires `evaluators` and exactly one of `project_id` or `dataset_id`. When `dataset_id` is provided, `experiment_ids` must contain at least one entry.
    - `name` string, required — Task name
    - `project_id` string — Project identifier (base64). Required when `dataset_id` is not provided. Mutually exclusive with `dataset_id`.
    - `dataset_id` string — Dataset identifier (base64). Required when `project_id` is not provided. Mutually exclusive with `project_id`.
    - `experiment_ids` string[] — Experiment identifiers (base64). Required when `dataset_id` is provided (at least one entry). Must be omitted or empty for project-based tasks.
    - `sampling_rate` number — Sampling rate between 0 and 1. Only supported on project-based tasks.
    - `is_continuous` boolean — Whether the task runs continuously. Only supported on project-based tasks. Must be `false` or omitted for dataset-based tasks.
    - `query_filter` string — Task-level query filter applied to all evaluated data (span shape). Mutually exclusive with `query_filters`.
    - `query_filters` TaskQueryFiltersInput — Combined named-query filters and boolean expression for create/update requests (trace/session shape). Supply this object OR `query_filter` (span shape) — not both.
      - `filters` TaskQueryFilterInput[], required — Named query filters (1-5 entries) with unique `A`-`E` ids. Each entry pairs a single-letter id with a filter expression.
        - `id` string, required — Single-letter query id, one of `A`-`E`. Unique within the task. Referenced by `query_filters.expression` and by each evaluator's `query_mappings`.
        - `filter` string, required — The query filter expression for this named query.
      - `expression` string — Boolean expression combining the `filters` ids (e.g. `A AND B`). Optional when exactly one filter is declared; required when two or more are declared.
    - `evaluators` TaskEvaluatorInput[], required — Evaluators to attach (at least one required). Evaluators use one of two mutually exclusive shapes by data granularity. Span evaluators use `query_filter` + per-evaluator `column_mappings`/`query_filter`. Trace/session evaluators use task-level `query_filters` plus per-evaluator `query_mappings`. Mixing the two shapes returns 400. The granularity must match the chosen shape (enforced server-side).
      - union — An evaluator attachment supplied when creating or updating a task. At least one entry is required on evaluation-task requests. Evaluators carry one of two mutually exclusive shapes: span evaluators use `query_filter` + `column_mappings`; trace/session evaluators use `query_mappings`.
        - SpanEvaluatorInput — Span-granularity evaluator input. Uses `query_filter` and `column_mappings`.
          - `evaluator_id` string, required — Evaluator identifier (base64). Duplicates are not allowed.
          - `evaluator_version_id` string, nullable — Pin this evaluator to a specific version (base64). Defaults to null, which always runs the evaluator's latest version; omitting the field and sending null are equivalent. Must be a version of the evaluator named by `evaluator_id`, otherwise the request returns 422.
          - `query_filter` string — Per-evaluator query filter (span shape). Combined with the task-level filter (AND).
          - `column_mappings` object — Maps evaluator template variable names to data source column names (span shape).
        - TraceOrSessionEvaluatorInput — Trace/session-granularity evaluator input. Uses `query_mappings`.
          - `evaluator_id` string, required — Evaluator identifier (base64). Duplicates are not allowed.
          - `evaluator_version_id` string, nullable — Pin this evaluator to a specific version (base64). Defaults to null, which always runs the evaluator's latest version; omitting the field and sending null are equivalent. Must be a version of the evaluator named by `evaluator_id`, otherwise the request returns 422.
          - `query_mappings` TaskQueryMappingInput[], required — Per-evaluator variable-to-query mappings (trace/session shape).
            - `variable_name` string, required — The evaluator template variable this mapping populates.
            - `query_ids` string[], required — Declared query ids (`A`-`E`) whose matching units feed this variable. An empty list means "any declared query" (valid for session-level variables that match all spans in the conversation). Every id must be declared in the task's `query_filters.filters`.
            - `attribute_path` string, required — Span attribute path (e.g. `attributes.input.value`) resolved within each admitted unit to populate `variable_name`.
    - `type` 'TEMPLATE_EVALUATION', required — Task type discriminator. Must be `"TEMPLATE_EVALUATION"`.
  - CreateCodeEvaluationTaskRequest — Request body for creating a `CODE_EVALUATION` task. Requires `evaluators` and exactly one of `project_id` or `dataset_id`. When `dataset_id` is provided, `experiment_ids` must contain at least one entry. Supports the same span and trace/session evaluator shapes as `CreateTemplateEvaluationTaskRequest`.
    - `name` string, required — Task name
    - `project_id` string — Project identifier (base64). Required when `dataset_id` is not provided. Mutually exclusive with `dataset_id`.
    - `dataset_id` string — Dataset identifier (base64). Required when `project_id` is not provided. Mutually exclusive with `project_id`.
    - `experiment_ids` string[] — Experiment identifiers (base64). Required when `dataset_id` is provided (at least one entry). Must be omitted or empty for project-based tasks.
    - `sampling_rate` number — Sampling rate between 0 and 1. Only supported on project-based tasks.
    - `is_continuous` boolean — Whether the task runs continuously. Only supported on project-based tasks. Must be `false` or omitted for dataset-based tasks.
    - `query_filter` string — Task-level query filter applied to all evaluated data (span shape). Mutually exclusive with `query_filters`.
    - `query_filters` TaskQueryFiltersInput — Combined named-query filters and boolean expression for create/update requests (trace/session shape). Supply this object OR `query_filter` (span shape) — not both.
      - `filters` TaskQueryFilterInput[], required — Named query filters (1-5 entries) with unique `A`-`E` ids. Each entry pairs a single-letter id with a filter expression.
        - `id` string, required — Single-letter query id, one of `A`-`E`. Unique within the task. Referenced by `query_filters.expression` and by each evaluator's `query_mappings`.
        - `filter` string, required — The query filter expression for this named query.
      - `expression` string — Boolean expression combining the `filters` ids (e.g. `A AND B`). Optional when exactly one filter is declared; required when two or more are declared.
    - `evaluators` TaskEvaluatorInput[], required — Evaluators to attach (at least one required). Evaluators use one of two mutually exclusive shapes by data granularity. Span evaluators use `query_filter` + per-evaluator `column_mappings`/`query_filter`. Trace/session evaluators use task-level `query_filters` plus per-evaluator `query_mappings`. Mixing the two shapes returns 400. The granularity must match the chosen shape (enforced server-side).
      - union — An evaluator attachment supplied when creating or updating a task. At least one entry is required on evaluation-task requests. Evaluators carry one of two mutually exclusive shapes: span evaluators use `query_filter` + `column_mappings`; trace/session evaluators use `query_mappings`.
        - SpanEvaluatorInput — Span-granularity evaluator input. Uses `query_filter` and `column_mappings`.
          - `evaluator_id` string, required — Evaluator identifier (base64). Duplicates are not allowed.
          - `evaluator_version_id` string, nullable — Pin this evaluator to a specific version (base64). Defaults to null, which always runs the evaluator's latest version; omitting the field and sending null are equivalent. Must be a version of the evaluator named by `evaluator_id`, otherwise the request returns 422.
          - `query_filter` string — Per-evaluator query filter (span shape). Combined with the task-level filter (AND).
          - `column_mappings` object — Maps evaluator template variable names to data source column names (span shape).
        - TraceOrSessionEvaluatorInput — Trace/session-granularity evaluator input. Uses `query_mappings`.
          - `evaluator_id` string, required — Evaluator identifier (base64). Duplicates are not allowed.
          - `evaluator_version_id` string, nullable — Pin this evaluator to a specific version (base64). Defaults to null, which always runs the evaluator's latest version; omitting the field and sending null are equivalent. Must be a version of the evaluator named by `evaluator_id`, otherwise the request returns 422.
          - `query_mappings` TaskQueryMappingInput[], required — Per-evaluator variable-to-query mappings (trace/session shape).
            - `variable_name` string, required — The evaluator template variable this mapping populates.
            - `query_ids` string[], required — Declared query ids (`A`-`E`) whose matching units feed this variable. An empty list means "any declared query" (valid for session-level variables that match all spans in the conversation). Every id must be declared in the task's `query_filters.filters`.
            - `attribute_path` string, required — Span attribute path (e.g. `attributes.input.value`) resolved within each admitted unit to populate `variable_name`.
    - `type` 'CODE_EVALUATION', required — Task type discriminator. Must be `"CODE_EVALUATION"`.
  - CreateRunExperimentTaskRequest — Request body for creating a `RUN_EXPERIMENT` task. Requires `dataset_id` and `run_configuration`. Does not support continuous execution — runs are triggered explicitly via `POST /v2/tasks/{task_id}/trigger`.
    - `name` string, required — Task name
    - `type` 'RUN_EXPERIMENT', required — Task type discriminator. Must be `"RUN_EXPERIMENT"`.
    - `dataset_id` string, required — Dataset identifier (base64). Required for `RUN_EXPERIMENT` tasks.
    - `run_configuration` union, required — Strict request form of an experiment execution configuration. Exactly one variant must be supplied, identified by `experiment_type`.
      - LlmGenerationRunConfigRequest — Strict request configuration for running an LLM prompt against each dataset example.
        - `experiment_type` 'LLM_GENERATION', required — Discriminator. Must be `"LLM_GENERATION"`.
        - `ai_integration_id` string, required — AI integration identifier (base64).
        - `model_name` string — Model name (e.g. `gpt-4o`). Falls back to the integration's default if omitted.
        - `messages` LLMMessageRequest[], required — Array of message objects (at least one).
          - `role` 'USER' | 'ASSISTANT' | 'SYSTEM' | 'TOOL', required — The role of the message author
          - `content` string, nullable — The content of the message
          - `tool_call_id` string — The ID of the tool call this message is responding to
          - `tool_calls` ToolCallRequest[] — Tool calls generated by the model
            - `id` string — The ID of the tool call
            - `type` 'FUNCTION', required — The type of tool call
            - `function` ToolCallFunctionRequest, required — The function to call (strict request form of ToolCallFunction)
              - …
        - `input_variable_format` 'F_STRING' | 'MUSTACHE' | 'NONE', required — The format for input variables in the prompt messages. Defaults to `F_STRING` if not provided. - `F_STRING`: Single curly braces ({variable_name}) - `MUSTACHE`: Double curly braces ({{variable_name}}) - `NONE`: **Deprecated.** Treated as `F_STRING`. Will be removed in a future version.
        - `invocation_parameters` InvocationParamsRequest — Parameters for the LLM invocation in a write request (strict form of InvocationParams; leaf schemas use *Request variants)
          - `temperature` number — Sampling temperature (higher = more random)
          - `max_tokens` integer — Maximum number of tokens to generate
          - `max_completion_tokens` integer — Maximum number of completion tokens to generate
          - `top_p` number — Nucleus sampling parameter
          - `frequency_penalty` number — Frequency penalty (-2.0 to 2.0)
          - `presence_penalty` number — Presence penalty (-2.0 to 2.0)
          - `stop` string[] — Stop sequences
          - `response_format` ResponseFormatRequest — Response format configuration in a write request (strict form of ResponseFormat)
            - `type` 'TEXT' | 'JSON_OBJECT' | 'JSON_SCHEMA' — The response format type
            - `json_schema` JsonSchemaConfigRequest — JSON schema configuration in a write request (strict form of JsonSchemaConfig)
              - …
          - `tool_config` ToolConfigRequest — Tool configuration in a write request (strict form of ToolConfig)
            - `tools` ToolDefinition[] — List of tool definitions available to the model
              - …
            - `tool_choice` unknown
          - `top_k` integer — Top-K sampling parameter. A top-K of 1 means the next selected token is the most probable (greedy decoding).
          - `thinking_level` string — Controls how much reasoning the model performs before responding. Supported by Gemini 3.x models. Accepted values: 'low', 'high'.
          - `thinking_budget` integer — Maximum tokens the model may use for internal reasoning. Supported by Gemini 2.5 models. Range: 0-24576 (Flash/Flash-Lite) or 128-32768 (Pro). Set 0 to disable thinking on Flash models.
          - `reasoning_effort` string — Controls how much reasoning the model performs before responding. Supported by OpenAI o-series and GPT-5 models. o-series: 'low' | 'medium' | 'high'. GPT-5: 'none' | 'low' | 'medium' | 'high' | 'xhigh'.
          - `verbosity` string — Controls the verbosity of model output. Supported by OpenAI GPT-5 series. Accepted values: 'low' | 'medium' | 'high'.
        - `provider_parameters` object — Provider-specific parameters. Defaults to `{}` (no overrides) if omitted.
        - `tool_config` ToolConfigRequest — Tool configuration in a write request (strict form of ToolConfig)
          - `tools` ToolDefinition[] — List of tool definitions available to the model
          - `tool_choice` unknown
        - `prompt_version_id` string, nullable — Prompt version identifier (base64). Links to a Prompt Hub version for traceability.
      - TemplateEvaluationRunConfigRequest — Strict request configuration for running a template-based LLM evaluator.
        - `experiment_type` 'TEMPLATE_EVALUATION', required — Discriminator. Must be `"TEMPLATE_EVALUATION"`.
        - `ai_integration_id` string, required — AI integration identifier (base64). The LLM that judges each example.
        - `model_name` string — Model name (e.g. `gpt-4o`). Falls back to the integration's default if omitted.
        - `template` string, required — The evaluation prompt template. Use `{{variable}}` placeholders that map to dataset column paths via `column_mapping`.
        - `provide_explanation` boolean, required — Whether to ask the LLM to include a written explanation alongside the score/label.
        - `classification_choices` object — Map of choice label to numeric score (e.g. `{"relevant": 1, "irrelevant": 0}`).
        - `column_mapping` object — Maps template variable names to dataset column paths.
        - `evaluator_version_id` string, nullable — EvaluatorVersion identifier (base64). Links this run to an Eval Hub evaluator version.
        - `invocation_parameters` InvocationParamsRequest — Parameters for the LLM invocation in a write request (strict form of InvocationParams; leaf schemas use *Request variants)
          - `temperature` number — Sampling temperature (higher = more random)
          - `max_tokens` integer — Maximum number of tokens to generate
          - `max_completion_tokens` integer — Maximum number of completion tokens to generate
          - `top_p` number — Nucleus sampling parameter
          - `frequency_penalty` number — Frequency penalty (-2.0 to 2.0)
          - `presence_penalty` number — Presence penalty (-2.0 to 2.0)
          - `stop` string[] — Stop sequences
          - `response_format` ResponseFormatRequest — Response format configuration in a write request (strict form of ResponseFormat)
            - `type` 'TEXT' | 'JSON_OBJECT' | 'JSON_SCHEMA' — The response format type
            - `json_schema` JsonSchemaConfigRequest — JSON schema configuration in a write request (strict form of JsonSchemaConfig)
              - …
          - `tool_config` ToolConfigRequest — Tool configuration in a write request (strict form of ToolConfig)
            - `tools` ToolDefinition[] — List of tool definitions available to the model
              - …
            - `tool_choice` unknown
          - `top_k` integer — Top-K sampling parameter. A top-K of 1 means the next selected token is the most probable (greedy decoding).
          - `thinking_level` string — Controls how much reasoning the model performs before responding. Supported by Gemini 3.x models. Accepted values: 'low', 'high'.
          - `thinking_budget` integer — Maximum tokens the model may use for internal reasoning. Supported by Gemini 2.5 models. Range: 0-24576 (Flash/Flash-Lite) or 128-32768 (Pro). Set 0 to disable thinking on Flash models.
          - `reasoning_effort` string — Controls how much reasoning the model performs before responding. Supported by OpenAI o-series and GPT-5 models. o-series: 'low' | 'medium' | 'high'. GPT-5: 'none' | 'low' | 'medium' | 'high' | 'xhigh'.
          - `verbosity` string — Controls the verbosity of model output. Supported by OpenAI GPT-5 series. Accepted values: 'low' | 'medium' | 'high'.
        - `provider_parameters` object — Provider-specific parameters. Defaults to `{}` (no overrides) if omitted.
      - AgentCallRunConfigRequest — Strict request configuration for running an agent integration.
        - `experiment_type` 'AGENT_CALL', required — Discriminator. Must be `"AGENT_CALL"`.
        - `integration_id` string, required — Agent integration identifier (base64). The agent invoked for each dataset example. Must reference an integration of `type` `AGENT`; other integration types are rejected.
        - `input_template` object, required — JSON request body sent to the agent for each dataset example. Must be a JSON object whose values conform to the agent integration's input schema. Mustache placeholders (`{{column}}`) are substituted with each dataset row's values before the request is sent.

## Response `201`

Returns a single task object

- Task — A task is a typed, configurable unit of work that ties one or more evaluators to a data source (project or dataset). `RUN_EXPERIMENT` tasks additionally carry a `run_configuration` that defines the LLM, evaluator, or agent settings for each triggered run. Evaluation tasks (`TEMPLATE_EVALUATION` and `CODE_EVALUATION`) use one of two mutually exclusive query-filter shapes depending on the granularity of the data each evaluator processes: - **Span shape** — `query_filter` (task-level) plus per-evaluator `column_mappings`/`query_filter`. For tasks where each evaluated unit is a single span. `query_filters` is null. - **Trace/session shape** — `query_filters` (named `filters` plus optional `expression`) at the task level, and per-evaluator `query_mappings`. For tasks where each evaluated unit is a complete trace or session. `query_filter` is null. All evaluators on a task must use the same shape; mixing shapes returns 400.
  - `id` string, required — The unique identifier for the task
  - `name` string, required — The name of the task
  - `type` 'TEMPLATE_EVALUATION' | 'CODE_EVALUATION' | 'RUN_EXPERIMENT', required — The task type. - TEMPLATE_EVALUATION - An LLM template-based evaluation task. - CODE_EVALUATION - A code-based evaluation task. - RUN_EXPERIMENT - A task that runs experiments.
  - `project_id` string, nullable — The project identifier (base64). Present for project-based tasks.
  - `dataset_id` string, nullable — The dataset identifier (base64). Present for dataset-based tasks.
  - `sampling_rate` number, nullable — Sampling rate between 0 and 1. Only applicable for project-based tasks.
  - `is_continuous` boolean, required — Whether the task runs continuously on incoming data.
  - `query_filter` string, nullable, required — Task-level query filter applied to all data. Span-granularity shape only. Null when the task uses the trace/session shape (`query_filters`). Mutually exclusive with `query_filters`.
  - `query_filters` TaskQueryFilters — Combined named-query filters and boolean expression for the trace/session shape. Supply this object OR `query_filter` (span shape) — not both.
    - `filters` TaskQueryFilter[], required — Named query filters (1-5 entries) with unique `A`-`E` ids. Each entry pairs a single-letter id with a filter expression.
      - `id` string, required — Single-letter query id, one of `A`-`E`. Unique within the task. Referenced by `query_filters.expression` and by each evaluator's `query_mappings`.
      - `filter` string, required — The query filter expression for this named query.
    - `expression` string — Boolean expression combining the `filters` ids (e.g. `A AND B`). Optional when exactly one filter is declared; required when two or more are declared. When a client omits `expression` on a single-filter create, GET echoes a synthesized expression equal to the lone query id (e.g. `A`).
  - `evaluators` TaskEvaluator[], required — The evaluators attached to this task. Empty for run_experiment tasks.
    - `evaluator_id` string, required — Evaluator identifier (base64).
    - `evaluator_name` string, required — The name of the attached evaluator.
    - `evaluator_version_id` string, nullable, required — The evaluator version this attachment is pinned to (base64). Null is the default and means the attachment is not pinned, so it runs the evaluator's latest version.
    - `query_filter` string, nullable, required — Per-evaluator query filter, combined with the task-level filter (AND). Span-granularity shape only; null for trace/session evaluators.
    - `column_mappings` object, nullable, required — Maps evaluator template variable names to data source column names. Span-granularity shape only; null for trace/session evaluators (which use `query_mappings`).
    - `query_mappings` TaskQueryMapping[], nullable — Maps each evaluator variable to one or more declared query ids plus an attribute path, for trace/session evaluators. Present only on trace/session tasks; null on span tasks (which use `column_mappings`).
      - `variable_name` string, required — The evaluator template variable this mapping populates.
      - `query_ids` string[], required — Declared query ids (`A`-`E`) whose matching units feed this variable. An empty list means "any declared query" (valid for session-level variables that match all spans in the conversation). Every id must be declared in the task's `query_filters.filters`.
      - `attribute_path` string, required — Span attribute path (e.g. `attributes.input.value`) resolved within each admitted unit to populate `variable_name`.
  - `experiment_ids` string[], required — Experiment identifiers (base64) for dataset-based tasks.
  - `run_configuration` union — Experiment execution configuration for a `RUN_EXPERIMENT` task. Exactly one variant must be supplied, identified by `experiment_type`. All fields sit at the top level alongside `experiment_type` (flat — no wrapper sub-object).
    - LlmGenerationRunConfig — Configuration for running an LLM prompt against each dataset example.
      - `experiment_type` 'LLM_GENERATION', required — Discriminator. Must be `"LLM_GENERATION"`.
      - `ai_integration_id` string, required — AI integration identifier (base64).
      - `model_name` string — Model name (e.g. `gpt-4o`). Falls back to the integration's default if omitted.
      - `messages` LLMMessage[], required — Array of message objects (at least one).
        - `role` 'USER' | 'ASSISTANT' | 'SYSTEM' | 'TOOL', required — The role of the message author
        - `content` string, nullable — The content of the message
        - `tool_call_id` string — The ID of the tool call this message is responding to
        - `tool_calls` ToolCall[] — Tool calls generated by the model
          - `id` string — The ID of the tool call
          - `type` 'FUNCTION', required — The type of tool call
          - `function` ToolCallFunction, required — The function to call
            - `name` string, required — The name of the function
            - `arguments` string, required — The arguments to the function as a JSON string
      - `input_variable_format` 'F_STRING' | 'MUSTACHE' | 'NONE', required — The format for input variables in the prompt messages. Defaults to `F_STRING` if not provided. - `F_STRING`: Single curly braces ({variable_name}) - `MUSTACHE`: Double curly braces ({{variable_name}}) - `NONE`: **Deprecated.** Treated as `F_STRING`. Will be removed in a future version.
      - `invocation_parameters` InvocationParams — Parameters for the LLM invocation
        - `temperature` number — Sampling temperature (higher = more random)
        - `max_tokens` integer — Maximum number of tokens to generate
        - `max_completion_tokens` integer — Maximum number of completion tokens to generate
        - `top_p` number — Nucleus sampling parameter
        - `frequency_penalty` number — Frequency penalty (-2.0 to 2.0)
        - `presence_penalty` number — Presence penalty (-2.0 to 2.0)
        - `stop` string[] — Stop sequences
        - `response_format` ResponseFormat — Response format configuration
          - `type` 'TEXT' | 'JSON_OBJECT' | 'JSON_SCHEMA' — The response format type
          - `json_schema` JsonSchemaConfig — JSON schema configuration (when type is JSON_SCHEMA)
            - `name` string — The name of the JSON schema
            - `description` string — A description of the JSON schema
            - `schema` object — The JSON schema object
            - `strict` boolean — Whether to enforce strict schema validation. Defaults to `false`.
        - `tool_config` ToolConfig — Tool configuration for the LLM invocation
          - `tools` ToolDefinition[] — List of tool definitions available to the model
          - `tool_choice` unknown
        - `top_k` integer — Top-K sampling parameter. A top-K of 1 means the next selected token is the most probable (greedy decoding).
        - `thinking_level` string — Controls how much reasoning the model performs before responding. Supported by Gemini 3.x models. Accepted values: 'low', 'high'.
        - `thinking_budget` integer — Maximum tokens the model may use for internal reasoning. Supported by Gemini 2.5 models. Range: 0-24576 (Flash/Flash-Lite) or 128-32768 (Pro). Set 0 to disable thinking on Flash models.
        - `reasoning_effort` string — Controls how much reasoning the model performs before responding. Supported by OpenAI o-series and GPT-5 models. o-series: 'low' | 'medium' | 'high'. GPT-5: 'none' | 'low' | 'medium' | 'high' | 'xhigh'.
        - `verbosity` string — Controls the verbosity of model output. Supported by OpenAI GPT-5 series. Accepted values: 'low' | 'medium' | 'high'.
        - `service_tier` string — Processing tier for the request. Supported by OpenAI only, and only for models eligible for Priority processing. Accepted value: 'priority'. Omit to use the project default.
      - `provider_parameters` object — Provider-specific parameters. Defaults to `{}` (no overrides) if omitted.
      - `tool_config` ToolConfig — Tool configuration for the LLM invocation
        - `tools` ToolDefinition[] — List of tool definitions available to the model
        - `tool_choice` unknown
      - `prompt_version_id` string, nullable — Prompt version identifier (base64). Links to a Prompt Hub version for traceability.
    - TemplateEvaluationRunConfig — Configuration for running a template-based LLM evaluator against each dataset example.
      - `experiment_type` 'TEMPLATE_EVALUATION', required — Discriminator. Must be `"TEMPLATE_EVALUATION"`.
      - `ai_integration_id` string, required — AI integration identifier (base64). The LLM that judges each example.
      - `model_name` string — Model name (e.g. `gpt-4o`). Falls back to the integration's default if omitted.
      - `template` string, required — The evaluation prompt template. Use `{{variable}}` placeholders that map to dataset column paths via `column_mapping`.
      - `provide_explanation` boolean, required — Whether to ask the LLM to include a written explanation alongside the score/label.
      - `classification_choices` object — Map of choice label to numeric score (e.g. `{"relevant": 1, "irrelevant": 0}`).
      - `column_mapping` object — Maps template variable names to dataset column paths.
      - `evaluator_version_id` string, nullable — EvaluatorVersion identifier (base64). Links this run to an Eval Hub evaluator version.
      - `invocation_parameters` InvocationParams — Parameters for the LLM invocation
        - `temperature` number — Sampling temperature (higher = more random)
        - `max_tokens` integer — Maximum number of tokens to generate
        - `max_completion_tokens` integer — Maximum number of completion tokens to generate
        - `top_p` number — Nucleus sampling parameter
        - `frequency_penalty` number — Frequency penalty (-2.0 to 2.0)
        - `presence_penalty` number — Presence penalty (-2.0 to 2.0)
        - `stop` string[] — Stop sequences
        - `response_format` ResponseFormat — Response format configuration
          - `type` 'TEXT' | 'JSON_OBJECT' | 'JSON_SCHEMA' — The response format type
          - `json_schema` JsonSchemaConfig — JSON schema configuration (when type is JSON_SCHEMA)
            - `name` string — The name of the JSON schema
            - `description` string — A description of the JSON schema
            - `schema` object — The JSON schema object
            - `strict` boolean — Whether to enforce strict schema validation. Defaults to `false`.
        - `tool_config` ToolConfig — Tool configuration for the LLM invocation
          - `tools` ToolDefinition[] — List of tool definitions available to the model
          - `tool_choice` unknown
        - `top_k` integer — Top-K sampling parameter. A top-K of 1 means the next selected token is the most probable (greedy decoding).
        - `thinking_level` string — Controls how much reasoning the model performs before responding. Supported by Gemini 3.x models. Accepted values: 'low', 'high'.
        - `thinking_budget` integer — Maximum tokens the model may use for internal reasoning. Supported by Gemini 2.5 models. Range: 0-24576 (Flash/Flash-Lite) or 128-32768 (Pro). Set 0 to disable thinking on Flash models.
        - `reasoning_effort` string — Controls how much reasoning the model performs before responding. Supported by OpenAI o-series and GPT-5 models. o-series: 'low' | 'medium' | 'high'. GPT-5: 'none' | 'low' | 'medium' | 'high' | 'xhigh'.
        - `verbosity` string — Controls the verbosity of model output. Supported by OpenAI GPT-5 series. Accepted values: 'low' | 'medium' | 'high'.
        - `service_tier` string — Processing tier for the request. Supported by OpenAI only, and only for models eligible for Priority processing. Accepted value: 'priority'. Omit to use the project default.
      - `provider_parameters` object — Provider-specific parameters. Defaults to `{}` (no overrides) if omitted.
    - AgentCallRunConfig — Configuration for running an agent integration against each dataset example. The `input_template` is sent to the agent after Mustache substitution.
      - `experiment_type` 'AGENT_CALL', required — Discriminator. Must be `"AGENT_CALL"`.
      - `integration_id` string, required — Agent integration identifier (base64). The agent invoked for each dataset example. Must reference an integration of `type` `AGENT`; other integration types are rejected.
      - `input_template` object, required — JSON request body sent to the agent for each dataset example. Must be a JSON object whose values conform to the agent integration's input schema. Mustache placeholders (`{{column}}`) are substituted with each dataset row's values before the request is sent. The `dataset.` prefix is optional — `{{column}}` and `{{dataset.column}}` are equivalent, and responses (create, update, and read) always echo the normalized `{{column}}` form.
  - `last_run_at` string, date-time, nullable, required — When the task was last run.
  - `created_at` string, date-time, required — When the task was created.
  - `updated_at` string, date-time, required — When the task was last updated.
  - `created_by_user_id` string, nullable, required — The unique identifier for the user who created the task.

## Other responses

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

## Changes

> 16 revisions in range; 1 not diffed.

- **2026-08-28** `f63ac334fd4a` — 2 breaking, 8 warning, 6 info
  - the `oneOf[#/components/schemas/CreateCodeEvaluationTaskRequest]/evaluators/items/` request property type/format changed from `object`/`` to ``/``
  - the `oneOf[#/components/schemas/CreateTemplateEvaluationTaskRequest]/evaluators/items/` request property type/format changed from `object`/`` to ``/``
  - removed the request property `oneOf[#/components/schemas/CreateCodeEvaluationTaskRequest]/evaluators/items/column_mappings`
  - removed the request property `oneOf[#/components/schemas/CreateCodeEvaluationTaskRequest]/evaluators/items/evaluator_id`
  - …12 more
- **2026-08-27** `9263b98aaefb` — 2 info
  - added the optional property `run_configuration/allOf[#/components/schemas/RunConfiguration]/oneOf[#/components/schemas/LlmGenerationRunConfig]/invocation_parameters/service_tier` to the response with the `201` status
  - added the optional property `run_configuration/allOf[#/components/schemas/RunConfiguration]/oneOf[#/components/schemas/TemplateEvaluationRunConfig]/invocation_parameters/service_tier` to the response with the `201` status
- …earlier changes not shown

[Full history](https://skmtc.dev/arize-ai/apis/arize-rest-api/changes/v2/tasks/post.md)

---

[API](https://skmtc.dev/arize-ai/apis/arize-rest-api.md) · [All operations](https://skmtc.dev/arize-ai/apis/arize-rest-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/arize-ai/arize-rest-api/revisions/6521535a37bb/schema)