Tasks - Arize AX Docs

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

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:

func (c *Client) List(ctx context.Context, req ListRequest) (*TaskList, error)

Usage Example:

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:

func (c *Client) Get(ctx context.Context, req GetRequest) (*Task, error)

Usage Example:

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:

func (c *Client) CreateEvaluationTask(
    ctx context.Context,
    req CreateEvaluationTaskRequest,
) (*Task, error)

Usage Example:

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:

func (c *Client) CreateRunExperimentTask(
    ctx context.Context,
    req CreateRunExperimentTaskRequest,
) (*Task, error)

Usage Example:

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:

func (c *Client) Update(ctx context.Context, req UpdateRequest) (*Task, error)

Usage Example:

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:

func (c *Client) Delete(ctx context.Context, req DeleteRequest) error

Usage Example:

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:

func (c *Client) TriggerRun(
    ctx context.Context,
    req TriggerRunRequest,
) (*TaskRun, error)

Usage Example:

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:

func (c *Client) ListRuns(
    ctx context.Context,
    req ListRunsRequest,
) (*TaskRunList, error)

Usage Example:

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:

func (c *Client) GetRun(ctx context.Context, req GetRunRequest) (*TaskRun, error)

Usage Example:

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:

func (c *Client) CancelRun(ctx context.Context, req CancelRunRequest) (*TaskRun, error)

Usage Example:

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:

func (c *Client) WaitForRun(
    ctx context.Context,
    req WaitForRunRequest,
) (*TaskRun, error)

Usage Example:

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

​List Tasks

​Get a Task

​Create an Evaluation Task

​Create a Run-Experiment Task

​Update a Task

​Delete a Task

​Trigger a Run

​List Runs

​Get a Run

​Cancel a Run

​Wait for a Run

List Tasks

Get a Task

Create an Evaluation Task

Create a Run-Experiment Task

Update a Task

Delete a Task

Trigger a Run

List Runs

Get a Run

Cancel a Run

Wait for a Run