> ## 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.

# Tasks

> List, get, create, update, delete, and manage runs of tasks (evaluation and run-experiment) using the Arize Go SDK.

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

A task is an automated job that either evaluates data on a project or dataset (`template_evaluation`, `code_evaluation`) or runs an experiment over a dataset (`run_experiment`). The `Get`, `Update`, `Delete`, `TriggerRun`, and `ListRuns` methods accept either a task name or an ID — when a name is passed, the parent `Space` (name or ID) is also required so the SDK can resolve the name to a unique ID. `GetRun`, `CancelRun`, and `WaitForRun` take strict run IDs. Task types use different create methods: `CreateEvaluationTask` for `template_evaluation` and `code_evaluation` tasks, `CreateRunExperimentTask` for `run_experiment` tasks. An update with no patch fields returns `tasks.ErrNoUpdateFields`; a `WaitForRun` that exceeds its timeout returns an error wrapping `tasks.ErrWaitTimeout`.

## List Tasks

`List` returns a paginated list of tasks. `Space`, when non-empty, accepts a space name or ID and restricts results to that space. `Project` and `Dataset`, when non-empty, accept a name or ID and restrict results to tasks attached to that project or dataset.

**Signature:**

```go theme={null}
func (c *Client) List(ctx context.Context, req ListRequest) (*TaskList, error)
```

**Usage Example:**

```go theme={null}
package main

import (
    "context"
    "errors"
    "fmt"
    "log"

    "github.com/Arize-ai/client-go-v2/arize"
    "github.com/Arize-ai/client-go-v2/arize/tasks"
)

func main() {
    client, err := arize.NewClient(arize.Config{APIKey: "your-api-key"})
    if err != nil {
        log.Fatal(err)
    }

    resp, err := client.Tasks.List(context.Background(), tasks.ListRequest{
        Space: "your-space-name-or-id",
        Type:  tasks.TaskTypeTemplateEvaluation,
        Limit: 25,
    })
    if err != nil {
        var unauthorized *arize.UnauthorizedError
        if errors.As(err, &unauthorized) {
            log.Fatalf("unauthorized: %v", unauthorized)
        }
        log.Fatal(err)
    }

    for _, t := range resp.Tasks {
        fmt.Printf("%s: %s (type=%s)\n", t.Id, t.Name, t.Type)
    }
}
```

## Get a Task

`Get` returns a single task, resolving by name or ID. `Space` is required when `Task` is a name.

**Signature:**

```go theme={null}
func (c *Client) Get(ctx context.Context, req GetRequest) (*Task, error)
```

**Usage Example:**

```go theme={null}
package main

import (
    "context"
    "errors"
    "fmt"
    "log"

    "github.com/Arize-ai/client-go-v2/arize"
    "github.com/Arize-ai/client-go-v2/arize/tasks"
)

func main() {
    client, err := arize.NewClient(arize.Config{APIKey: "your-api-key"})
    if err != nil {
        log.Fatal(err)
    }

    t, err := client.Tasks.Get(
        context.Background(),
        tasks.GetRequest{
            Task:  "your-task-name-or-id",
            Space: "your-space-name-or-id",
        },
    )
    if err != nil {
        var notFound *arize.NotFoundError
        if errors.As(err, &notFound) {
            log.Fatalf("task not found: %v", notFound)
        }
        log.Fatal(err)
    }

    fmt.Printf("task %s: %s (type=%s)\n", t.Id, t.Name, t.Type)
}
```

## Create an Evaluation Task

`CreateEvaluationTask` creates a new `template_evaluation` or `code_evaluation` task and returns it. Exactly one of `Project` or `Dataset` must be set (name or ID; `Space` is required when either is a name). At least one evaluator is required. Dataset-based tasks require at least one entry in `ExperimentIDs`; `SamplingRate` and `IsContinuous` apply only to project-based tasks.

**Signature:**

```go theme={null}
func (c *Client) CreateEvaluationTask(
    ctx context.Context,
    req CreateEvaluationTaskRequest,
) (*Task, error)
```

**Usage Example:**

```go theme={null}
package main

import (
    "context"
    "errors"
    "fmt"
    "log"

    "github.com/Arize-ai/client-go-v2/arize"
    "github.com/Arize-ai/client-go-v2/arize/tasks"
)

func main() {
    client, err := arize.NewClient(arize.Config{APIKey: "your-api-key"})
    if err != nil {
        log.Fatal(err)
    }

    t, err := client.Tasks.CreateEvaluationTask(
        context.Background(),
        tasks.CreateEvaluationTaskRequest{
            Name:    "hallucination-eval",
            Type:    tasks.TaskTypeTemplateEvaluation,
            Project: "your-project-name-or-id",
            Space:   "your-space-name-or-id",
            Evaluators: []tasks.EvaluatorInput{
                {EvaluatorID: "your-evaluator-id"},
            },
            SamplingRate: 0.1,
            IsContinuous: true,
        },
    )
    if err != nil {
        var conflict *arize.ConflictError
        if errors.As(err, &conflict) {
            log.Fatalf("task already exists: %v", conflict)
        }
        log.Fatal(err)
    }

    fmt.Printf("created task %s\n", t.Id)
}
```

## Create a Run-Experiment Task

`CreateRunExperimentTask` creates a new `run_experiment` task and returns it. `Dataset` accepts a name or ID; `Space` is required when `Dataset` is a name. `RunConfiguration` must hold exactly one variant — populate it via `FromLlmGenerationRunConfig` or `FromTemplateEvaluationRunConfig`.

**Signature:**

```go theme={null}
func (c *Client) CreateRunExperimentTask(
    ctx context.Context,
    req CreateRunExperimentTaskRequest,
) (*Task, error)
```

**Usage Example:**

```go theme={null}
package main

import (
    "context"
    "errors"
    "fmt"
    "log"

    "github.com/Arize-ai/client-go-v2/arize"
    "github.com/Arize-ai/client-go-v2/arize/tasks"
)

func main() {
    client, err := arize.NewClient(arize.Config{APIKey: "your-api-key"})
    if err != nil {
        log.Fatal(err)
    }

    var runConfig tasks.RunConfiguration
    if err := runConfig.FromLlmGenerationRunConfig(tasks.LLMGenerationRunConfig{
        // Populate the llm_generation run configuration (provider, model, messages, etc.).
    }); err != nil {
        log.Fatal(err)
    }

    t, err := client.Tasks.CreateRunExperimentTask(
        context.Background(),
        tasks.CreateRunExperimentTaskRequest{
            Name:             "nightly-experiments",
            Dataset:          "your-dataset-name-or-id",
            Space:            "your-space-name-or-id",
            RunConfiguration: runConfig,
        },
    )
    if err != nil {
        var badRequest *arize.BadRequestError
        if errors.As(err, &badRequest) {
            log.Fatalf("invalid run configuration: %v", badRequest)
        }
        log.Fatal(err)
    }

    fmt.Printf("created task %s\n", t.Id)
}
```

## Update a Task

`Update` updates an existing task and returns it. `Task` accepts a name or ID; `Space` is required when `Task` is a name. The SDK fetches the task first to determine its type: `Name` applies to all tasks; `SamplingRate`, `IsContinuous`, `QueryFilter`, and `Evaluators` apply only to evaluation tasks; `RunConfiguration` applies only to `run_experiment` tasks. Leave a patch field `nil` to preserve its current value. A request with no patch fields returns `tasks.ErrNoUpdateFields` without contacting the server.

**Signature:**

```go theme={null}
func (c *Client) Update(ctx context.Context, req UpdateRequest) (*Task, error)
```

**Usage Example:**

```go theme={null}
package main

import (
    "context"
    "errors"
    "fmt"
    "log"

    "github.com/Arize-ai/client-go-v2/arize"
    "github.com/Arize-ai/client-go-v2/arize/tasks"
)

func main() {
    client, err := arize.NewClient(arize.Config{APIKey: "your-api-key"})
    if err != nil {
        log.Fatal(err)
    }

    newName := "renamed-task"
    newRate := float32(0.25)
    t, err := client.Tasks.Update(
        context.Background(),
        tasks.UpdateRequest{
            Task:         "your-task-name-or-id",
            Space:        "your-space-name-or-id",
            Name:         &newName,
            SamplingRate: &newRate,
        },
    )
    if err != nil {
        if errors.Is(err, tasks.ErrNoUpdateFields) {
            log.Fatal("no fields to update")
        }
        var notFound *arize.NotFoundError
        if errors.As(err, &notFound) {
            log.Fatalf("task not found: %v", notFound)
        }
        log.Fatal(err)
    }

    fmt.Printf("updated task %s: %s\n", t.Id, t.Name)
}
```

## Delete a Task

`Delete` irreversibly removes a task and all its associated resources (runs, configurations, etc.). `Task` accepts a name or ID; `Space` is required when `Task` is a name. It returns only an error.

**Signature:**

```go theme={null}
func (c *Client) Delete(ctx context.Context, req DeleteRequest) error
```

**Usage Example:**

```go theme={null}
package main

import (
    "context"
    "errors"
    "log"

    "github.com/Arize-ai/client-go-v2/arize"
    "github.com/Arize-ai/client-go-v2/arize/tasks"
)

func main() {
    client, err := arize.NewClient(arize.Config{APIKey: "your-api-key"})
    if err != nil {
        log.Fatal(err)
    }

    err = client.Tasks.Delete(
        context.Background(),
        tasks.DeleteRequest{
            Task:  "your-task-name-or-id",
            Space: "your-space-name-or-id",
        },
    )
    if err != nil {
        var notFound *arize.NotFoundError
        if errors.As(err, &notFound) {
            log.Printf("no task to remove: %v", notFound)
            return
        }
        log.Fatal(err)
    }
}
```

## Trigger a Run

`TriggerRun` triggers a new run of a task and returns it (initially in `pending` status). `Task` accepts a name or ID; `Space` is required when `Task` is a name. The SDK fetches the task first to determine its type: `DataStartTime`, `DataEndTime`, `MaxSpans`, `OverrideEvaluations`, and `ExperimentIDs` apply only to evaluation tasks; `ExperimentName` (required), `DatasetVersionID`, `ExampleIDs`, `MaxExamples`, `TracingMetadata`, and `EvaluationTaskIDs` apply only to `run_experiment` tasks.

**Signature:**

```go theme={null}
func (c *Client) TriggerRun(
    ctx context.Context,
    req TriggerRunRequest,
) (*TaskRun, error)
```

**Usage Example:**

```go theme={null}
package main

import (
    "context"
    "errors"
    "fmt"
    "log"
    "time"

    "github.com/Arize-ai/client-go-v2/arize"
    "github.com/Arize-ai/client-go-v2/arize/tasks"
)

func main() {
    client, err := arize.NewClient(arize.Config{APIKey: "your-api-key"})
    if err != nil {
        log.Fatal(err)
    }

    run, err := client.Tasks.TriggerRun(
        context.Background(),
        tasks.TriggerRunRequest{
            Task:          "your-task-name-or-id",
            Space:         "your-space-name-or-id",
            DataStartTime: time.Now().Add(-24 * time.Hour),
            DataEndTime:   time.Now(),
            MaxSpans:      1000,
        },
    )
    if err != nil {
        var badRequest *arize.BadRequestError
        if errors.As(err, &badRequest) {
            log.Fatalf("invalid trigger request: %v", badRequest)
        }
        log.Fatal(err)
    }

    fmt.Printf("triggered run %s (status=%s)\n", run.Id, run.Status)
}
```

## List Runs

`ListRuns` returns a paginated list of a task's runs, newest first. `Task` accepts a name or ID; `Space` is required when `Task` is a name.

**Signature:**

```go theme={null}
func (c *Client) ListRuns(
    ctx context.Context,
    req ListRunsRequest,
) (*TaskRunList, error)
```

**Usage Example:**

```go theme={null}
package main

import (
    "context"
    "errors"
    "fmt"
    "log"

    "github.com/Arize-ai/client-go-v2/arize"
    "github.com/Arize-ai/client-go-v2/arize/tasks"
)

func main() {
    client, err := arize.NewClient(arize.Config{APIKey: "your-api-key"})
    if err != nil {
        log.Fatal(err)
    }

    resp, err := client.Tasks.ListRuns(
        context.Background(),
        tasks.ListRunsRequest{
            Task:   "your-task-name-or-id",
            Space:  "your-space-name-or-id",
            Status: tasks.TaskRunStatusCompleted,
            Limit:  50,
        },
    )
    if err != nil {
        var notFound *arize.NotFoundError
        if errors.As(err, &notFound) {
            log.Fatalf("task not found: %v", notFound)
        }
        log.Fatal(err)
    }

    for _, run := range resp.TaskRuns {
        fmt.Printf("%s: status=%s\n", run.Id, run.Status)
    }
}
```

## Get a Run

`GetRun` returns a single task run with its current status and statistics. Use it to poll a run triggered by `TriggerRun` (or use `WaitForRun`). `RunID` is a strict ID — no name resolution is performed.

**Signature:**

```go theme={null}
func (c *Client) GetRun(ctx context.Context, req GetRunRequest) (*TaskRun, error)
```

**Usage Example:**

```go theme={null}
package main

import (
    "context"
    "errors"
    "fmt"
    "log"

    "github.com/Arize-ai/client-go-v2/arize"
    "github.com/Arize-ai/client-go-v2/arize/tasks"
)

func main() {
    client, err := arize.NewClient(arize.Config{APIKey: "your-api-key"})
    if err != nil {
        log.Fatal(err)
    }

    run, err := client.Tasks.GetRun(
        context.Background(),
        tasks.GetRunRequest{RunID: "your-run-id"},
    )
    if err != nil {
        var notFound *arize.NotFoundError
        if errors.As(err, &notFound) {
            log.Fatalf("run not found: %v", notFound)
        }
        log.Fatal(err)
    }

    fmt.Printf("run %s: status=%s\n", run.Id, run.Status)
}
```

## Cancel a Run

`CancelRun` cancels a pending or running task run and returns it. `RunID` is a strict ID.

**Signature:**

```go theme={null}
func (c *Client) CancelRun(ctx context.Context, req CancelRunRequest) (*TaskRun, error)
```

**Usage Example:**

```go theme={null}
package main

import (
    "context"
    "errors"
    "fmt"
    "log"

    "github.com/Arize-ai/client-go-v2/arize"
    "github.com/Arize-ai/client-go-v2/arize/tasks"
)

func main() {
    client, err := arize.NewClient(arize.Config{APIKey: "your-api-key"})
    if err != nil {
        log.Fatal(err)
    }

    run, err := client.Tasks.CancelRun(
        context.Background(),
        tasks.CancelRunRequest{RunID: "your-run-id"},
    )
    if err != nil {
        var badRequest *arize.BadRequestError
        if errors.As(err, &badRequest) {
            log.Fatalf("cannot cancel run: %v", badRequest)
        }
        log.Fatal(err)
    }

    fmt.Printf("cancelled run %s (status=%s)\n", run.Id, run.Status)
}
```

## Wait for a Run

`WaitForRun` polls a task run until it reaches a terminal state (`completed`, `failed`, or `cancelled`) and returns it. It polls every `PollInterval` (default 5 s) for up to `Timeout` (default 10 m); on expiry it returns an error wrapping `tasks.ErrWaitTimeout`. Cancelling `ctx` stops the wait with `ctx`'s error.

**Signature:**

```go theme={null}
func (c *Client) WaitForRun(
    ctx context.Context,
    req WaitForRunRequest,
) (*TaskRun, error)
```

**Usage Example:**

```go theme={null}
package main

import (
    "context"
    "errors"
    "fmt"
    "log"
    "time"

    "github.com/Arize-ai/client-go-v2/arize"
    "github.com/Arize-ai/client-go-v2/arize/tasks"
)

func main() {
    client, err := arize.NewClient(arize.Config{APIKey: "your-api-key"})
    if err != nil {
        log.Fatal(err)
    }

    run, err := client.Tasks.WaitForRun(
        context.Background(),
        tasks.WaitForRunRequest{
            RunID:        "your-run-id",
            PollInterval: 10 * time.Second,
            Timeout:      5 * time.Minute,
        },
    )
    if err != nil {
        if errors.Is(err, tasks.ErrWaitTimeout) {
            log.Fatal("timed out waiting for run to finish")
        }
        log.Fatal(err)
    }

    fmt.Printf("run %s finished with status %s\n", run.Id, run.Status)
}
```