Annotation Queues - Arize AX Docs

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

An annotation queue collects records (dataset examples or spans) that human annotators label using configured annotation configs. The Get, Update, Delete, ListRecords, AddRecords, DeleteRecords, Annotate, and Assign methods accept either a queue 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. Record sources are built with annotationqueues.NewExampleRecordSource or annotationqueues.NewSpanRecordSource, which set the record-type discriminator on your behalf.

List Annotation Queues

List returns a paginated list of annotation queues. Space, when non-empty, accepts a space name or ID and restricts results to that space. Signature:

func (c *Client) List(ctx context.Context, req ListRequest) (*AnnotationQueueList, 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/annotationqueues"
)

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

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

    for _, q := range resp.AnnotationQueues {
        fmt.Printf("%s: %s\n", q.Id, q.Name)
    }
}

Get an Annotation Queue

Get returns a single annotation queue, resolving by name or ID. Signature:

func (c *Client) Get(ctx context.Context, req GetRequest) (*AnnotationQueue, 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/annotationqueues"
)

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

    q, err := client.AnnotationQueues.Get(
        context.Background(),
        annotationqueues.GetRequest{
            AnnotationQueue: "your-queue-name-or-id",
            Space:           "your-space-name-or-id",
        },
    )
    if err != nil {
        var notFound *arize.NotFoundError
        if errors.As(err, &notFound) {
            log.Fatalf("annotation queue not found: %v", notFound)
        }
        log.Fatal(err)
    }

    fmt.Printf("queue %s: %s\n", q.Id, q.Name)
}

Create an Annotation Queue

Create creates a new annotation queue, resolving the parent space by name or ID. AssignmentMethod is optional — when empty, the server applies its default (AssignmentMethodAll). Optional RecordSources (max 2) are added on creation; build entries with annotationqueues.NewExampleRecordSource or annotationqueues.NewSpanRecordSource. Signature:

func (c *Client) Create(ctx context.Context, req CreateRequest) (*AnnotationQueue, 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/annotationqueues"
)

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

    q, err := client.AnnotationQueues.Create(
        context.Background(),
        annotationqueues.CreateRequest{
            Space:               "your-space-name-or-id",
            Name:                "Quality Review Queue",
            AnnotationConfigIDs: []string{"your-annotation-config-id"},
            AnnotatorEmails:     []annotationqueues.Email{"reviewer@example.com"},
            AssignmentMethod:    annotationqueues.AssignmentMethodAll,
            Instructions:        "Review each span for accuracy and relevance.",
        },
    )
    if err != nil {
        var conflict *arize.ConflictError
        if errors.As(err, &conflict) {
            log.Fatalf("annotation queue already exists: %v", conflict)
        }
        log.Fatal(err)
    }

    fmt.Printf("created queue %s\n", q.Id)
}

Update an Annotation Queue

Update updates an existing annotation queue, resolving by name or ID. Name, Instructions, AnnotatorEmails, and AnnotationConfigIDs are pointers — nil preserves the existing value. Signature:

func (c *Client) Update(ctx context.Context, req UpdateRequest) (*AnnotationQueue, 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/annotationqueues"
)

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

    newName := "renamed-queue"
    q, err := client.AnnotationQueues.Update(
        context.Background(),
        annotationqueues.UpdateRequest{
            AnnotationQueue: "your-queue-name-or-id",
            Space:           "your-space-name-or-id",
            Name:            &newName,
        },
    )
    if err != nil {
        var notFound *arize.NotFoundError
        if errors.As(err, &notFound) {
            log.Fatalf("annotation queue not found: %v", notFound)
        }
        log.Fatal(err)
    }

    fmt.Printf("updated queue %s: %s\n", q.Id, q.Name)
}

Delete an Annotation Queue

Delete removes an annotation queue, resolving by name or ID. 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/annotationqueues"
)

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

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

List Records

ListRecords returns a paginated list of records for an annotation queue, resolving the queue by name or ID. Signature:

func (c *Client) ListRecords(
    ctx context.Context,
    req ListRecordsRequest,
) (*AnnotationQueueRecordList, 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/annotationqueues"
)

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

    resp, err := client.AnnotationQueues.ListRecords(
        context.Background(),
        annotationqueues.ListRecordsRequest{
            AnnotationQueue: "your-queue-name-or-id",
            Space:           "your-space-name-or-id",
            Limit:           50,
        },
    )
    if err != nil {
        var notFound *arize.NotFoundError
        if errors.As(err, &notFound) {
            log.Fatalf("annotation queue not found: %v", notFound)
        }
        log.Fatal(err)
    }

    fmt.Printf("loaded %d records\n", len(resp.Records))
}

Add Records

AddRecords adds record sources to an annotation queue (resolved by name or ID) and returns the created records. Build entries with annotationqueues.NewExampleRecordSource or annotationqueues.NewSpanRecordSource; at most 2 record sources are allowed per request. Signature:

func (c *Client) AddRecords(
    ctx context.Context,
    req AddRecordsRequest,
) (*AnnotationQueueRecordCreate, 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/annotationqueues"
)

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

    src, err := annotationqueues.NewSpanRecordSource(annotationqueues.AnnotationQueueSpanRecordInput{
        ProjectId: "your-project-id",
        StartTime: time.Now().Add(-24 * time.Hour),
        EndTime:   time.Now(),
    })
    if err != nil {
        log.Fatal(err)
    }

    created, err := client.AnnotationQueues.AddRecords(
        context.Background(),
        annotationqueues.AddRecordsRequest{
            AnnotationQueue: "your-queue-name-or-id",
            Space:           "your-space-name-or-id",
            RecordSources:   []annotationqueues.AnnotationQueueRecordInput{src},
        },
    )
    if err != nil {
        var badRequest *arize.BadRequestError
        if errors.As(err, &badRequest) {
            log.Fatalf("invalid record sources: %v", badRequest)
        }
        log.Fatal(err)
    }

    fmt.Printf("added %d record sources\n", len(created.RecordSources))
}

Delete Records

DeleteRecords removes records from an annotation queue, resolving the queue by name or ID. RecordIDs are strict IDs. Signature:

func (c *Client) DeleteRecords(ctx context.Context, req DeleteRecordsRequest) 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/annotationqueues"
)

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

    err = client.AnnotationQueues.DeleteRecords(
        context.Background(),
        annotationqueues.DeleteRecordsRequest{
            AnnotationQueue: "your-queue-name-or-id",
            Space:           "your-space-name-or-id",
            RecordIDs:       []string{"record-id-1", "record-id-2"},
        },
    )
    if err != nil {
        var notFound *arize.NotFoundError
        if errors.As(err, &notFound) {
            log.Printf("records not found: %v", notFound)
            return
        }
        log.Fatal(err)
    }
}

Annotate a Record

Annotate submits annotations for a record in an annotation queue, resolving the queue by name or ID. RecordID is a strict ID — no name resolution is performed. Signature:

func (c *Client) Annotate(
    ctx context.Context,
    req AnnotateRequest,
) (*AnnotationQueueRecordAnnotateResult, 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/annotationqueues"
)

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

    label := "correct"
    result, err := client.AnnotationQueues.Annotate(
        context.Background(),
        annotationqueues.AnnotateRequest{
            AnnotationQueue: "your-queue-name-or-id",
            Space:           "your-space-name-or-id",
            RecordID:        "your-record-id",
            Annotations: []annotationqueues.AnnotationInput{
                {Name: "quality", Label: &label},
            },
        },
    )
    if err != nil {
        var badRequest *arize.BadRequestError
        if errors.As(err, &badRequest) {
            log.Fatalf("annotation rejected: %v", badRequest)
        }
        log.Fatal(err)
    }

    fmt.Printf("annotation submitted for record %s (%d annotations)\n", result.Id, len(result.Annotations))
}

Assign Users to a Record

Assign assigns users to a record in an annotation queue, resolving the queue by name or ID. RecordID is a strict ID — no name resolution is performed. Signature:

func (c *Client) Assign(
    ctx context.Context,
    req AssignRequest,
) (*AnnotationQueueRecordAssignResult, 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/annotationqueues"
)

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

    result, err := client.AnnotationQueues.Assign(
        context.Background(),
        annotationqueues.AssignRequest{
            AnnotationQueue:    "your-queue-name-or-id",
            Space:              "your-space-name-or-id",
            RecordID:           "your-record-id",
            AssignedUserEmails: []annotationqueues.Email{"reviewer@example.com"},
        },
    )
    if err != nil {
        var notFound *arize.NotFoundError
        if errors.As(err, &notFound) {
            log.Fatalf("record not found: %v", notFound)
        }
        log.Fatal(err)
    }

    fmt.Printf("assigned %d users to record %s\n", len(result.AssignedUsers), result.Id)
}

​List Annotation Queues

​Get an Annotation Queue

​Create an Annotation Queue

​Update an Annotation Queue

​Delete an Annotation Queue

​List Records

​Add Records

​Delete Records

​Annotate a Record

​Assign Users to a Record

List Annotation Queues

Get an Annotation Queue

Create an Annotation Queue

Update an Annotation Queue

Delete an Annotation Queue

List Records

Add Records

Delete Records

Annotate a Record

Assign Users to a Record