Spans

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

Spans are the unit of work captured for an LLM application — each trace is composed of one or more hierarchical spans. The Spans subclient lets you query spans within a project (filtered by time range and an optional filter DSL), remove spans by ID, and write human annotations to a batch of spans. Project accepts a name or ID; when a name is passed, Space (name or ID) is required so the SDK can resolve the name to a unique ID.

List Spans

List returns a paginated list of spans matching the given filter. Unlike other List methods in this SDK, spans.List uses POST because the filter DSL and projection list can be too large for a query string. Both the body fields (project, time range, filter) and the query params (limit, cursor) are flattened into a single ListRequest. Signature:

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

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

    resp, err := client.Spans.List(
        context.Background(),
        spans.ListRequest{
            Project: "your-project-name-or-id",
            Space:   "your-space-name-or-id",
            Start:   time.Now().Add(-24 * time.Hour),
            End:     time.Now(),
            Filter:  "status_code = 'ERROR'",
            Limit:   50,
        },
    )
    if err != nil {
        var unauthorized *arize.UnauthorizedError
        if errors.As(err, &unauthorized) {
            log.Fatalf("unauthorized: %v", unauthorized)
        }
        log.Fatal(err)
    }

    for _, span := range resp.Spans {
        fmt.Printf("%s (trace=%s kind=%s)\n",
            span.Context.SpanId,
            span.Context.TraceId,
            span.Kind,
        )
    }
}

Delete Spans

Delete removes spans by their IDs. The response always includes Completed (whether the server fully processed the request), DeletedSpanIds (IDs confirmed deleted), and NotDeletedSpanIds (IDs not deleted — either not found within the supported lookback window, or not reached when Completed is false). When Completed is false, retry the original full request; the delete operation is idempotent, so re-submitting already-deleted IDs is safe. Signature:

func (c *Client) Delete(
    ctx context.Context,
    req DeleteRequest,
) (*DeleteSpans, 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/spans"
)

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

    result, err := client.Spans.Delete(
        context.Background(),
        spans.DeleteRequest{
            Project: "your-project-name-or-id",
            Space:   "your-space-name-or-id",
            SpanIDs: []string{"span-id-1", "span-id-2"},
        },
    )
    if err != nil {
        var notFound *arize.NotFoundError
        if errors.As(err, &notFound) {
            log.Fatalf("project not found: %v", notFound)
        }
        log.Fatal(err)
    }

    if !result.Completed {
        fmt.Printf("partial delete: confirmed %d span IDs - retry the original request to resolve %d remaining\n",
            len(result.DeletedSpanIds),
            len(result.NotDeletedSpanIds),
        )
        return
    }
    fmt.Printf("deleted %d spans (%d IDs were not found)\n",
        len(result.DeletedSpanIds),
        len(result.NotDeletedSpanIds),
    )
}

Annotate Spans

Annotate writes human annotations to a batch of spans. Annotations are upserted by annotation config name per span: resubmitting the same config name for the same span overwrites the previous value, so retries do not create duplicates. Up to 1000 spans may be annotated per request. Spans are looked up within the configured time window (defaulting to the last 31 days). If any span ID in the batch is not found within the window, the entire request is rejected. The write completes synchronously before the function returns (HTTP 202 Accepted); visibility in read queries may lag by a short interval. Signature:

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

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

    label := "correct"
    err = client.Spans.Annotate(
        context.Background(),
        spans.AnnotateRequest{
            Project: "your-project-name-or-id",
            Space:   "your-space-name-or-id",
            Annotations: []spans.AnnotateRecordInput{
                {
                    RecordId: "span-id-1",
                    Values: []spans.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)
    }
}

API reference

API clients

List Spans

Delete Spans

Annotate Spans

​List Spans

​Delete Spans

​Annotate Spans

List Spans

Delete Spans

Annotate Spans