--- title: "Genai Spans Stats" method: POST path: "/agents/spans/stats" tags: ["Agents"] --- # Genai Spans Stats `POST /agents/spans/stats` ## Request - Base URL: `https://trace.wandb.ai` (the document declares no server; this is the origin it was published from) - URL: `https://trace.wandb.ai/agents/spans/stats` - Auth: none declared 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": [ {"$eq": [{"$getField": "op_name"}, {"$literal": "predict"}]}, {"$gt": [{"$getField": "summary.usage.tokens"}, {"$literal": 1000}]} ] } ``` - `$and` union[], required - union - LiteralOperation: Represents a constant value in the query language. This can be any standard JSON-serializable value. Example: ``` {"$literal": "predict"} ``` - … - GetFieldOperator: Access a field on the traced call. Supports dot notation for nested access, e.g. `summary.usage.tokens`. Only works on fields present in the `CallSchema`, including: - Top-level fields like `op_name`, `trace_id`, `started_at` - Nested fields like `inputs.input_name`, `summary.usage.tokens`, etc. Example: ``` {"$getField": "op_name"} ``` - … - ConvertOperation: Convert the input value to a specific type (e.g., `int`, `bool`, `string`). Example: ``` { "$convert": { "input": {"$getField": "inputs.value"}, "to": "int" } } ``` - … - SizeOperation: Return the number of elements in a collection or characters in a string. Example: ``` {"$size": {"$getField": "scorer_tags"}} ``` - … - AndOperation (recursive) - OrOperation: Logical OR. At least one condition must be true. Example: ``` { "$or": [ {"$eq": [{"$getField": "op_name"}, {"$literal": "a"}]}, {"$eq": [{"$getField": "op_name"}, {"$literal": "b"}]} ] } ``` - … - NotOperation: Logical NOT. Inverts the condition. Example: ``` { "$not": [ {"$eq": [{"$getField": "op_name"}, {"$literal": "debug"}]} ] } ``` - … - EqOperation: Equality check between two operands. Example: ``` { "$eq": [{"$getField": "op_name"}, {"$literal": "predict"}] } ``` - … - GtOperation: Greater than comparison. Example: ``` { "$gt": [{"$getField": "summary.usage.tokens"}, {"$literal": 100}] } ``` - … - LtOperation: Less than comparison. Example: ``` { "$lt": [{"$getField": "summary.usage.tokens"}, {"$literal": 100}] } ``` - … - GteOperation: Greater than or equal comparison. Example: ``` { "$gte": [{"$getField": "summary.usage.tokens"}, {"$literal": 100}] } ``` - … - LteOperation: Less than or equal comparison. Example: ``` { "$lte": [{"$getField": "summary.usage.tokens"}, {"$literal": 100}] } ``` - … - InOperation: Membership check. Returns true if the left operand is in the list provided as the second operand. Example: ``` { "$in": [ {"$getField": "op_name"}, [{"$literal": "predict"}, {"$literal": "generate"}] ] } ``` - … - ContainsOperation: Case-insensitive substring match. Not part of MongoDB. Weave-specific addition. Example: ``` { "$contains": { "input": {"$getField": "display_name"}, "substr": {"$literal": "llm"}, "case_insensitive": true } } ``` - … - OrOperation: Logical OR. At least one condition must be true. Example: ``` { "$or": [ {"$eq": [{"$getField": "op_name"}, {"$literal": "a"}]}, {"$eq": [{"$getField": "op_name"}, {"$literal": "b"}]} ] } ``` - `$or` union[], required - union - LiteralOperation: Represents a constant value in the query language. This can be any standard JSON-serializable value. Example: ``` {"$literal": "predict"} ``` - … - GetFieldOperator: Access a field on the traced call. Supports dot notation for nested access, e.g. `summary.usage.tokens`. Only works on fields present in the `CallSchema`, including: - Top-level fields like `op_name`, `trace_id`, `started_at` - Nested fields like `inputs.input_name`, `summary.usage.tokens`, etc. Example: ``` {"$getField": "op_name"} ``` - … - ConvertOperation: Convert the input value to a specific type (e.g., `int`, `bool`, `string`). Example: ``` { "$convert": { "input": {"$getField": "inputs.value"}, "to": "int" } } ``` - … - SizeOperation: Return the number of elements in a collection or characters in a string. Example: ``` {"$size": {"$getField": "scorer_tags"}} ``` - … - AndOperation: Logical AND. All conditions must evaluate to true. Example: ``` { "$and": [ {"$eq": [{"$getField": "op_name"}, {"$literal": "predict"}]}, {"$gt": [{"$getField": "summary.usage.tokens"}, {"$literal": 1000}]} ] } ``` - … - OrOperation (recursive) - NotOperation: Logical NOT. Inverts the condition. Example: ``` { "$not": [ {"$eq": [{"$getField": "op_name"}, {"$literal": "debug"}]} ] } ``` - … - EqOperation: Equality check between two operands. Example: ``` { "$eq": [{"$getField": "op_name"}, {"$literal": "predict"}] } ``` - … - GtOperation: Greater than comparison. Example: ``` { "$gt": [{"$getField": "summary.usage.tokens"}, {"$literal": 100}] } ``` - … - LtOperation: Less than comparison. Example: ``` { "$lt": [{"$getField": "summary.usage.tokens"}, {"$literal": 100}] } ``` - … - GteOperation: Greater than or equal comparison. Example: ``` { "$gte": [{"$getField": "summary.usage.tokens"}, {"$literal": 100}] } ``` - … - LteOperation: Less than or equal comparison. Example: ``` { "$lte": [{"$getField": "summary.usage.tokens"}, {"$literal": 100}] } ``` - … - InOperation: Membership check. Returns true if the left operand is in the list provided as the second operand. Example: ``` { "$in": [ {"$getField": "op_name"}, [{"$literal": "predict"}, {"$literal": "generate"}] ] } ``` - … - ContainsOperation: Case-insensitive substring match. Not part of MongoDB. Weave-specific addition. Example: ``` { "$contains": { "input": {"$getField": "display_name"}, "substr": {"$literal": "llm"}, "case_insensitive": true } } ``` - … - NotOperation: Logical NOT. Inverts the condition. Example: ``` { "$not": [ {"$eq": [{"$getField": "op_name"}, {"$literal": "debug"}]} ] } ``` - `$not` unknown[], required - unknown - EqOperation: Equality check between two operands. Example: ``` { "$eq": [{"$getField": "op_name"}, {"$literal": "predict"}] } ``` - `$eq` unknown[], required - unknown - GtOperation: Greater than comparison. Example: ``` { "$gt": [{"$getField": "summary.usage.tokens"}, {"$literal": 100}] } ``` - `$gt` unknown[], required - unknown - LtOperation: Less than comparison. Example: ``` { "$lt": [{"$getField": "summary.usage.tokens"}, {"$literal": 100}] } ``` - `$lt` unknown[], required - unknown - GteOperation: Greater than or equal comparison. Example: ``` { "$gte": [{"$getField": "summary.usage.tokens"}, {"$literal": 100}] } ``` - `$gte` unknown[], required - unknown - LteOperation: Less than or equal comparison. Example: ``` { "$lte": [{"$getField": "summary.usage.tokens"}, {"$literal": 100}] } ``` - `$lte` unknown[], required - unknown - InOperation: Membership check. Returns true if the left operand is in the list provided as the second operand. Example: ``` { "$in": [ {"$getField": "op_name"}, [{"$literal": "predict"}, {"$literal": "generate"}] ] } ``` - `$in` unknown[], required - unknown - ContainsOperation: Case-insensitive substring match. Not part of MongoDB. Weave-specific addition. Example: ``` { "$contains": { "input": {"$getField": "display_name"}, "substr": {"$literal": "llm"}, "case_insensitive": true } } ``` - `$contains` ContainsSpec, required: Specification for the `$contains` operation. - `input`: The string to search. - `substr`: The substring to search for. - `case_insensitive`: If true, match is case-insensitive. - `input` union, required - LiteralOperation: Represents a constant value in the query language. This can be any standard JSON-serializable value. Example: ``` {"$literal": "predict"} ``` - … - GetFieldOperator: Access a field on the traced call. Supports dot notation for nested access, e.g. `summary.usage.tokens`. Only works on fields present in the `CallSchema`, including: - Top-level fields like `op_name`, `trace_id`, `started_at` - Nested fields like `inputs.input_name`, `summary.usage.tokens`, etc. Example: ``` {"$getField": "op_name"} ``` - … - ConvertOperation: Convert the input value to a specific type (e.g., `int`, `bool`, `string`). Example: ``` { "$convert": { "input": {"$getField": "inputs.value"}, "to": "int" } } ``` - … - SizeOperation: Return the number of elements in a collection or characters in a string. Example: ``` {"$size": {"$getField": "scorer_tags"}} ``` - … - AndOperation: Logical AND. All conditions must evaluate to true. Example: ``` { "$and": [ {"$eq": [{"$getField": "op_name"}, {"$literal": "predict"}]}, {"$gt": [{"$getField": "summary.usage.tokens"}, {"$literal": 1000}]} ] } ``` - … - OrOperation: Logical OR. At least one condition must be true. Example: ``` { "$or": [ {"$eq": [{"$getField": "op_name"}, {"$literal": "a"}]}, {"$eq": [{"$getField": "op_name"}, {"$literal": "b"}]} ] } ``` - … - NotOperation: Logical NOT. Inverts the condition. Example: ``` { "$not": [ {"$eq": [{"$getField": "op_name"}, {"$literal": "debug"}]} ] } ``` - … - EqOperation: Equality check between two operands. Example: ``` { "$eq": [{"$getField": "op_name"}, {"$literal": "predict"}] } ``` - … - GtOperation: Greater than comparison. Example: ``` { "$gt": [{"$getField": "summary.usage.tokens"}, {"$literal": 100}] } ``` - … - LtOperation: Less than comparison. Example: ``` { "$lt": [{"$getField": "summary.usage.tokens"}, {"$literal": 100}] } ``` - … - GteOperation: Greater than or equal comparison. Example: ``` { "$gte": [{"$getField": "summary.usage.tokens"}, {"$literal": 100}] } ``` - … - LteOperation: Less than or equal comparison. Example: ``` { "$lte": [{"$getField": "summary.usage.tokens"}, {"$literal": 100}] } ``` - … - InOperation: Membership check. Returns true if the left operand is in the list provided as the second operand. Example: ``` { "$in": [ {"$getField": "op_name"}, [{"$literal": "predict"}, {"$literal": "generate"}] ] } ``` - … - ContainsOperation (recursive) - `substr` union, required - LiteralOperation: Represents a constant value in the query language. This can be any standard JSON-serializable value. Example: ``` {"$literal": "predict"} ``` - … - GetFieldOperator: Access a field on the traced call. Supports dot notation for nested access, e.g. `summary.usage.tokens`. Only works on fields present in the `CallSchema`, including: - Top-level fields like `op_name`, `trace_id`, `started_at` - Nested fields like `inputs.input_name`, `summary.usage.tokens`, etc. Example: ``` {"$getField": "op_name"} ``` - … - ConvertOperation: Convert the input value to a specific type (e.g., `int`, `bool`, `string`). Example: ``` { "$convert": { "input": {"$getField": "inputs.value"}, "to": "int" } } ``` - … - SizeOperation: Return the number of elements in a collection or characters in a string. Example: ``` {"$size": {"$getField": "scorer_tags"}} ``` - … - AndOperation: Logical AND. All conditions must evaluate to true. Example: ``` { "$and": [ {"$eq": [{"$getField": "op_name"}, {"$literal": "predict"}]}, {"$gt": [{"$getField": "summary.usage.tokens"}, {"$literal": 1000}]} ] } ``` - … - OrOperation: Logical OR. At least one condition must be true. Example: ``` { "$or": [ {"$eq": [{"$getField": "op_name"}, {"$literal": "a"}]}, {"$eq": [{"$getField": "op_name"}, {"$literal": "b"}]} ] } ``` - … - NotOperation: Logical NOT. Inverts the condition. Example: ``` { "$not": [ {"$eq": [{"$getField": "op_name"}, {"$literal": "debug"}]} ] } ``` - … - EqOperation: Equality check between two operands. Example: ``` { "$eq": [{"$getField": "op_name"}, {"$literal": "predict"}] } ``` - … - GtOperation: Greater than comparison. Example: ``` { "$gt": [{"$getField": "summary.usage.tokens"}, {"$literal": 100}] } ``` - … - LtOperation: Less than comparison. Example: ``` { "$lt": [{"$getField": "summary.usage.tokens"}, {"$literal": 100}] } ``` - … - GteOperation: Greater than or equal comparison. Example: ``` { "$gte": [{"$getField": "summary.usage.tokens"}, {"$literal": 100}] } ``` - … - LteOperation: Less than or equal comparison. Example: ``` { "$lte": [{"$getField": "summary.usage.tokens"}, {"$literal": 100}] } ``` - … - InOperation: Membership check. Returns true if the left operand is in the list provided as the second operand. Example: ``` { "$in": [ {"$getField": "op_name"}, [{"$literal": "predict"}, {"$literal": "generate"}] ] } ``` - … - ContainsOperation (recursive) - `case_insensitive` boolean, nullable - `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: ``` { "$and": [ {"$eq": [{"$getField": "op_name"}, {"$literal": "predict"}]}, {"$gt": [{"$getField": "summary.usage.tokens"}, {"$literal": 1000}]} ] } ``` - … - OrOperation: Logical OR. At least one condition must be true. Example: ``` { "$or": [ {"$eq": [{"$getField": "op_name"}, {"$literal": "a"}]}, {"$eq": [{"$getField": "op_name"}, {"$literal": "b"}]} ] } ``` - … - NotOperation: Logical NOT. Inverts the condition. Example: ``` { "$not": [ {"$eq": [{"$getField": "op_name"}, {"$literal": "debug"}]} ] } ``` - … - EqOperation: Equality check between two operands. Example: ``` { "$eq": [{"$getField": "op_name"}, {"$literal": "predict"}] } ``` - … - GtOperation: Greater than comparison. Example: ``` { "$gt": [{"$getField": "summary.usage.tokens"}, {"$literal": 100}] } ``` - … - LtOperation: Less than comparison. Example: ``` { "$lt": [{"$getField": "summary.usage.tokens"}, {"$literal": 100}] } ``` - … - GteOperation: Greater than or equal comparison. Example: ``` { "$gte": [{"$getField": "summary.usage.tokens"}, {"$literal": 100}] } ``` - … - LteOperation: Less than or equal comparison. Example: ``` { "$lte": [{"$getField": "summary.usage.tokens"}, {"$literal": 100}] } ``` - … - InOperation: Membership check. Returns true if the left operand is in the list provided as the second operand. Example: ``` { "$in": [ {"$getField": "op_name"}, [{"$literal": "predict"}, {"$literal": "generate"}] ] } ``` - … - ContainsOperation: Case-insensitive substring match. Not part of MongoDB. Weave-specific addition. Example: ``` { "$contains": { "input": {"$getField": "display_name"}, "substr": {"$literal": "llm"}, "case_insensitive": true } } ``` - … - `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": [ {"$eq": [{"$getField": "op_name"}, {"$literal": "predict"}]}, {"$gt": [{"$getField": "summary.usage.tokens"}, {"$literal": 1000}]} ] } ``` - `$and` union[], required - … - OrOperation: Logical OR. At least one condition must be true. Example: ``` { "$or": [ {"$eq": [{"$getField": "op_name"}, {"$literal": "a"}]}, {"$eq": [{"$getField": "op_name"}, {"$literal": "b"}]} ] } ``` - `$or` union[], required - … - NotOperation: Logical NOT. Inverts the condition. Example: ``` { "$not": [ {"$eq": [{"$getField": "op_name"}, {"$literal": "debug"}]} ] } ``` - `$not` unknown[], required - … - EqOperation: Equality check between two operands. Example: ``` { "$eq": [{"$getField": "op_name"}, {"$literal": "predict"}] } ``` - `$eq` unknown[], required - … - GtOperation: Greater than comparison. Example: ``` { "$gt": [{"$getField": "summary.usage.tokens"}, {"$literal": 100}] } ``` - `$gt` unknown[], required - … - LtOperation: Less than comparison. Example: ``` { "$lt": [{"$getField": "summary.usage.tokens"}, {"$literal": 100}] } ``` - `$lt` unknown[], required - … - GteOperation: Greater than or equal comparison. Example: ``` { "$gte": [{"$getField": "summary.usage.tokens"}, {"$literal": 100}] } ``` - `$gte` unknown[], required - … - LteOperation: Less than or equal comparison. Example: ``` { "$lte": [{"$getField": "summary.usage.tokens"}, {"$literal": 100}] } ``` - `$lte` unknown[], required - … - InOperation: Membership check. Returns true if the left operand is in the list provided as the second operand. Example: ``` { "$in": [ {"$getField": "op_name"}, [{"$literal": "predict"}, {"$literal": "generate"}] ] } ``` - `$in` unknown[], required - … - ContainsOperation: Case-insensitive substring match. Not part of MongoDB. Weave-specific addition. Example: ``` { "$contains": { "input": {"$getField": "display_name"}, "substr": {"$literal": "llm"}, "case_insensitive": true } } ``` - `$contains` ContainsSpec, required: Specification for the `$contains` operation. - `input`: The string to search. - `substr`: The substring to search for. - `case_insensitive`: If true, match is case-insensitive. - … - `min` union - number - string, date-time - `max` union - number - string, date-time - `signal_filters` AgentSignalFilter - `tags` string[] - `ratings` RatingCondition[] - `scorer_key` string, required - `op` 'gte' | 'gt' | 'lte' | 'lt' | 'eq', required - `value` number, required - `insight_filters` AgentInsightFilter[] - `field` 'intent_category' | 'intent_sentiment' | 'failure_category' | 'failure_severity' | 'intent_topic_id' | 'failure_topic_id', required - `values` string[], required: Values to match. intent_sentiment accepts only frustrated, dissatisfied, neutral, satisfied, delighted; failure_severity accepts only info, major, or minor. - `exclude` boolean: Exclude conversations matching any value in this filter. ## 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, required - `timezone` string, required - `bucket_type` 'time' | 'number', required - `columns` AgentSpanStatsColumn[], required - `name` string, required - `role` 'time' | 'bucket' | 'group' | 'metric', required - `value_type` 'datetime' | 'number' | 'boolean' | 'string', required - `metric` string, nullable, required - `aggregation` string, nullable, required - `rows` object[], required ## Other responses - `422`: Validation Error ## Changes - **2026-10-16** `dd89fadfe4e4`: 1 info - endpoint added [Operation history](https://skmtc.dev/wandb/apis/fastapi/changes/agents/spans/stats/post.md) --- [API](https://skmtc.dev/wandb/apis/fastapi.md) - [All operations](https://skmtc.dev/wandb/apis/fastapi/llms.txt) - [OpenAPI document](https://skmtc.dev/wandb/apis/fastapi/revisions/f7643c49bf2e?raw)