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

# Tasks

> Create and run evaluation tasks over project spans or dataset examples using the Arize TypeScript SDK.

<Note>
  The `tasks` functions are currently in **ALPHA**. The API may change without notice. A one-time warning is emitted on first use.
</Note>

## List Tasks

```typescript theme={null}
import { listTasks } from "@arizeai/ax-client";

const { data: tasks, pagination } = await listTasks({
  space: "my-space",    // space name or ID (optional)
  name: "quality",      // substring filter on task name (optional)
  project: "my-project",  // project name or ID (optional)
  dataset: "my-dataset",  // dataset name or ID (optional)
  type: "template_evaluation",  // optional
  limit: 10,
});
```

## Create a Task

Tasks run LLM-as-judge evaluators over project spans (online monitoring) or dataset examples (offline batch evaluation). Exactly one of `project` or `dataset` must be provided.

### Project-scoped task (continuous monitoring)

```typescript theme={null}
import { createTask } from "@arizeai/ax-client";

const task = await createTask({
  name: "Production Quality Monitor",
  type: "template_evaluation",
  space: "my-space",    // required when project is a name
  project: "my-project",
  isContinuous: true,
  samplingRate: 0.1,    // sample 10% of spans
  evaluators: [
    {
      evaluatorId: "your_evaluator_id",
      columnMappings: { input: "question", output: "answer" },
    },
  ],
});
```

### Dataset-scoped task (batch evaluation)

```typescript theme={null}
import { createTask, triggerTaskRun, waitForTaskRun } from "@arizeai/ax-client";

const task = await createTask({
  name: "Weekly Quality Check",
  type: "template_evaluation",
  space: "my-space",
  dataset: "my-dataset",
  evaluators: [
    {
      evaluatorId: "your_evaluator_id",
      columnMappings: { input: "question", output: "answer" },
    },
  ],
});

// Immediately trigger a run and wait for it to finish
const run = await triggerTaskRun({ task: task.id });
const finalRun = await waitForTaskRun({ runId: run.id });
console.log(finalRun.status); // "completed" | "failed" | "cancelled"
```

## Create an Evaluation Task

Ergonomic helper for creating `template_evaluation` or `code_evaluation` tasks. Equivalent to `createTask` but rejects unsupported types up-front.

```typescript theme={null}
import { createEvaluationTask, triggerTaskRun, waitForTaskRun } from "@arizeai/ax-client";

const task = await createEvaluationTask({
  name: "Weekly Quality Check",
  type: "template_evaluation",
  space: "my-space",
  project: "my-project",
  evaluators: [
    {
      evaluatorId: "your_evaluator_id",
      columnMappings: { input: "question", output: "answer" },
    },
  ],
});

const run = await triggerTaskRun({ task: task.id });
const finalRun = await waitForTaskRun({ runId: run.id });
```

## Create a Run Experiment Task

Ergonomic helper for creating `run_experiment` tasks. The server drives all LLM calls using the AI integration specified in `runConfiguration`. Resolves `aiIntegration` by name (use `ai_integration_id` directly when calling `createTask`).

```typescript theme={null}
import { createRunExperimentTask, triggerTaskRun, waitForTaskRun } from "@arizeai/ax-client";

const task = await createRunExperimentTask({
  name: "GPT-4o Baseline Task",
  dataset: "my-dataset",
  space: "my-space",
  runConfiguration: {
    experiment_type: "llm_generation",
    aiIntegration: "my-openai-integration",
    model_name: "gpt-4o",
    input_variable_format: "f_string",
    messages: [
      { role: "system", content: "You are a helpful assistant." },
      { role: "user", content: "Answer: {question}" },
    ],
  },
});

const run = await triggerTaskRun({ task: task.id });
const finalRun = await waitForTaskRun({ runId: run.id });
```

## Get a Task

```typescript theme={null}
import { getTask } from "@arizeai/ax-client";

// By task ID
const task = await getTask({ task: "your_task_id" });

// By task name (requires space)
const task = await getTask({ task: "My Task", space: "my-space" });
```

## Update a Task

```typescript theme={null}
import { updateTask } from "@arizeai/ax-client";

const updated = await updateTask({
  task: "My Task",     // task name or ID
  space: "my-space",   // required when task is a name
  name: "Renamed Task",
  samplingRate: 0.25,  // project-scoped tasks only
});
```

## Delete a Task

```typescript theme={null}
import { deleteTask } from "@arizeai/ax-client";

await deleteTask({
  task: "My Task",     // task name or ID
  space: "my-space",   // required when task is a name
});
```

## Trigger a Task Run

```typescript theme={null}
import { triggerTaskRun } from "@arizeai/ax-client";

const run = await triggerTaskRun({
  task: "My Task",     // task name or ID
  space: "my-space",  // required when task is a name
  dataStartTime: new Date("2026-03-01T00:00:00Z"),
  dataEndTime: new Date("2026-03-08T00:00:00Z"),
  maxSpans: 5000,
  overrideEvaluations: false,  // skip already-evaluated spans
});
```

## List Task Runs

```typescript theme={null}
import { listTaskRuns } from "@arizeai/ax-client";

const { data: runs, pagination } = await listTaskRuns({
  task: "My Task",     // task name or ID
  space: "my-space",  // required when task is a name
  status: "completed",  // optional status filter
  limit: 10,
});

for (const run of runs) {
  console.log(run.id, run.numSuccesses, run.numErrors);
}
```

## Get a Task Run

```typescript theme={null}
import { getTaskRun } from "@arizeai/ax-client";

const run = await getTaskRun({ runId: "your_run_id" });
console.log(run.status);       // e.g. "running"
console.log(run.numSuccesses); // spans evaluated so far
```

## Wait for a Task Run

Poll until the run reaches a terminal status (`completed`, `failed`, or `cancelled`).

```typescript theme={null}
import { triggerTaskRun, waitForTaskRun } from "@arizeai/ax-client";

const run = await triggerTaskRun({ task: "your_task_id" });
const finalRun = await waitForTaskRun({
  runId: run.id,
  pollInterval: 3_000,      // poll every 3 seconds (default: 5000)
  timeout: 5 * 60_000,      // give up after 5 minutes (default: 10 minutes)
});

if (finalRun.status === "completed") {
  console.log(`${finalRun.numSuccesses} spans evaluated successfully`);
} else {
  console.error(`Run ended with status: ${finalRun.status}`);
}
```

## Cancel a Task Run

Only valid for runs with status `pending` or `running`.

```typescript theme={null}
import { cancelTaskRun } from "@arizeai/ax-client";

const run = await cancelTaskRun({ runId: "your_run_id" });
console.log(run.status); // "cancelled"
```