---
title: "Update task"
method: PATCH
path: "/v2/tasks/{task_id}"
tags: ["Tasks"]
---

# Update task

`PATCH /v2/tasks/{task_id}`

Update a task's mutable fields. At least one field must be provided.
Omitted fields are left unchanged.

**Payload Requirements**
- At least one mutable field must be provided.
- When `evaluators` is provided, the entire evaluator list is replaced.
- `sampling_rate` and `is_continuous` are only applicable for project-based tasks.
- Fields not valid for the task's type return 400 (e.g. `run_configuration` on an evaluation task).
- System-managed fields (`id`, `type`, `created_at`, `updated_at`) cannot be modified.
- `evaluator_version_id` pins an evaluator to one version. Because `evaluators`
  replaces the whole list, each entry states its own pin: send a version ID to pin,
  and omit the field or send null to run the latest version. Omit `evaluators`
  entirely to leave the existing attachments — and their pins — untouched.
- A pinned 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.

**Valid example** (update evaluation task)
```json
{
  "name": "Updated Hallucination Check",
  "sampling_rate": 0.5,
  "query_filter": "metadata.environment = 'staging'"
}
```

**Valid example** (pin one evaluator, leave the other on latest)
```json
{
  "evaluators": [
    {
      "evaluator_id": "RXZhbHVhdG9yOjEyOmFCY0Q=",
      "evaluator_version_id": "RXZhbHVhdG9yVmVyc2lvbjo5OTphQmNE"
    },
    {
      "evaluator_id": "RXZhbHVhdG9yOjEzOmFCY0Q="
    }
  ]
}
```

**Invalid example** (no fields provided)
```json
{}
```

<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 — PATCH body for `PATCH /v2/tasks/{task_id}`. The server derives the task type from the URL's task record and selects the appropriate schema; the body itself does not carry a `type` field. | Task type | Schema | |---|---| | `TEMPLATE_EVALUATION` | `UpdateEvaluationTaskRequest` | | `CODE_EVALUATION` | `UpdateEvaluationTaskRequest` | | `RUN_EXPERIMENT` | `UpdateRunExperimentTaskRequest` | Sending a field that is not valid for the resolved task type returns 400 (e.g. `evaluators` on a `RUN_EXPERIMENT` task, or `run_configuration` on an evaluation task).
  - UpdateEvaluationTaskRequest — PATCH body for `TEMPLATE_EVALUATION` and `CODE_EVALUATION` tasks. The two types share the same updatable shape; the server derives the task type from the URL's task record. At least one field must be provided.
    - `name` string — New task name.
    - `sampling_rate` number — Sampling rate between 0 and 1. Only applicable for project-based tasks.
    - `is_continuous` boolean — Whether the task runs continuously. Only applicable for project-based tasks.
    - `query_filter` string, nullable — Task-level query filter. Pass `null` to clear.
    - `evaluators` TaskEvaluatorInput[] — Replaces the entire evaluator list. At least one evaluator is required when provided.
      - `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. Combined with the task-level filter (AND).
      - `column_mappings` object — Maps evaluator template variable names to data source column names.
  - UpdateRunExperimentTaskRequest — PATCH body for `RUN_EXPERIMENT` tasks. The server derives the task type from the URL's task record. At least one of `name` or `run_configuration` must be provided. When `run_configuration` is provided the stored config is fully replaced (existing configs are marked inactive and the new config is inserted atomically in a transaction).
    - `name` string — New task name.
    - `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
              - …
        - `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)
              - …
          - `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'.
        - `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)
              - …
          - `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'.
        - `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.

## Response `200`

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.
  - `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.
  - `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).
    - `column_mappings` object, nullable, required — Maps evaluator template variable names to data source column names.
  - `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'.
      - `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'.
      - `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

---

[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)