Skip to main content
The spans client methods are currently in ALPHA. 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) (*SpanList, 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 matching the given criteria. A nil *SpanDeletePartial return means all spans were fully deleted (HTTP 204). A non-nil *SpanDeletePartial means the server returned HTTP 200: the request was partially processed and only the IDs listed in SpanDeletePartial.DeletedSpanIds were confirmed deleted — the caller should retry for the remainder. Signature: 
func (c *Client) Delete(
    ctx context.Context,
    req DeleteRequest,
) (*SpanDeletePartial, 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)
    }

    partial, 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 partial == nil {
        fmt.Println("all spans deleted")
        return
    }
    fmt.Printf("partial delete: confirmed %d span IDs - retry remaining\n",
        len(partial.DeletedSpanIds),
    )
}

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