---
title: "Genai Spans Stats"
method: POST
path: "/agents/spans/stats"
tags: ["Agents"]
---

# Genai Spans Stats

`POST /agents/spans/stats`

Query chart-ready aggregations over agent spans.

## Request body

- AgentSpanStatsReq — Request chart-ready aggregations over GenAI agent spans.
  - `project_id` string, required
  - `query` Query
    - `$expr` union, required
      - AndOperation — Logical AND. All conditions must evaluate to true. Example:
        - `$and` union[], required
          - union
            - unknown
            - unknown
            - unknown
            - AndOperation — recursive
            - unknown
            - unknown
            - unknown
            - unknown
            - unknown
            - unknown
            - unknown
            - unknown
            - unknown
      - unknown
      - unknown
      - unknown
      - unknown
      - unknown
      - unknown
      - unknown
      - unknown
      - unknown
  - `start` string, date-time, required
  - `end` string, date-time, nullable
  - `granularity` integer, nullable
  - `timezone` string
  - `group_by` AgentGroupByRef[]
    - `source` 'field' | 'column' | 'custom_attrs_string' | 'custom_attrs_int' | 'custom_attrs_float' | 'custom_attrs_bool'
    - `key` string, required
    - `alias` string, nullable
  - `metrics` AgentSpanStatsMetricSpec[]
    - `alias` string, required
    - `value_type` 'datetime' | 'number' | 'boolean' | 'string', required
    - `aggregations` string[]
    - `percentiles` number[]
    - `value` AgentSpanValueRef, required — Reference to a span field or typed custom attribute map value.
      - `source` 'field' | 'derived' | 'custom_attrs_string' | 'custom_attrs_int' | 'custom_attrs_float' | 'custom_attrs_bool'
      - `key` string, required
  - `group_limit` integer
  - `bucket_by` union
    - AgentSpanStatsTimeBucketSpec — Bucket stats rows by started_at time intervals.
      - `type` 'time'
    - AgentSpanStatsNumericBucketSpec — Bucket stats rows by ranges of one numeric span or grouped value.
      - `type` 'number'
      - `alias` string
      - `bins` integer
      - `min` number, nullable
      - `max` number, nullable
      - `value` AgentSpanValueRef — Reference to a span field or typed custom attribute map value.
        - `source` 'field' | 'derived' | 'custom_attrs_string' | 'custom_attrs_int' | 'custom_attrs_float' | 'custom_attrs_bool'
        - `key` string, required
      - `group_by` AgentGroupByRef[]
        - `source` 'field' | 'column' | 'custom_attrs_string' | 'custom_attrs_int' | 'custom_attrs_float' | 'custom_attrs_bool'
        - `key` string, required
        - `alias` string, nullable
      - `measure` AgentSpanMeasureSpec — One aggregate measure computed over spans in a group or bucket.
        - `alias` string, required
        - `aggregation` 'sum' | 'avg' | 'min' | 'max' | 'count' | 'count_distinct' | 'count_true' | 'count_false', required
        - `value` AgentSpanValueRef — Reference to a span field or typed custom attribute map value.
          - `source` 'field' | 'derived' | 'custom_attrs_string' | 'custom_attrs_int' | 'custom_attrs_float' | 'custom_attrs_bool'
          - `key` string, required
        - `value_type` 'datetime' | 'number' | 'boolean' | 'string', nullable
        - `filter` Query
          - `$expr` union, required
            - AndOperation — Logical AND. All conditions must evaluate to true. Example:
              - …
            - unknown
            - unknown
            - unknown
            - unknown
            - unknown
            - unknown
            - unknown
            - unknown
            - unknown
  - `group_filters` AgentSpanGroupFilter[]
    - `group_by` AgentGroupByRef[]
      - `source` 'field' | 'column' | 'custom_attrs_string' | 'custom_attrs_int' | 'custom_attrs_float' | 'custom_attrs_bool'
      - `key` string, required
      - `alias` string, nullable
    - `measure` AgentSpanMeasureSpec, required — One aggregate measure computed over spans in a group or bucket.
      - `alias` string, required
      - `aggregation` 'sum' | 'avg' | 'min' | 'max' | 'count' | 'count_distinct' | 'count_true' | 'count_false', required
      - `value` AgentSpanValueRef — Reference to a span field or typed custom attribute map value.
        - `source` 'field' | 'derived' | 'custom_attrs_string' | 'custom_attrs_int' | 'custom_attrs_float' | 'custom_attrs_bool'
        - `key` string, required
      - `value_type` 'datetime' | 'number' | 'boolean' | 'string', nullable
      - `filter` Query
        - `$expr` union, required
          - AndOperation — Logical AND. All conditions must evaluate to true. Example:
            - `$and` union[], required
              - …
          - unknown
          - unknown
          - unknown
          - unknown
          - unknown
          - unknown
          - unknown
          - unknown
          - unknown
    - `min` union
      - number
      - string, date-time
    - `max` union
      - number
      - string, date-time

## Response `200`

Successful Response

- AgentSpanStatsRes — Response containing chart-ready agent span stats rows.
  - `start` string, date-time, required
  - `end` string, date-time, required
  - `granularity` integer, nullable
  - `timezone` string, required
  - `bucket_type` 'time' | 'number'
  - `columns` AgentSpanStatsColumn[]
    - `name` string, required
    - `role` 'time' | 'bucket' | 'group' | 'metric', required
    - `value_type` 'datetime' | 'number' | 'boolean' | 'string', required
    - `metric` string, nullable
    - `aggregation` string, nullable
  - `rows` object[]

## Other responses

- `422` — Validation Error

---

[API](https://skmtc.net/wandb/apis/serverless-training.md) · [All operations](https://skmtc.net/wandb/apis/serverless-training/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/wandb/serverless-training/revisions/8d8d96fc0fd3/schema)