--- title: "Genai Spans Query" method: POST path: "/agents/spans/query" tags: ["Agents"] --- # Genai Spans Query `POST /agents/spans/query` Query agent spans, either as raw rows or grouped aggregates. ## Request body - AgentSpansQueryReq — Request to query agent spans for a project. When `group_by` is empty (or omitted), returns raw span rows in the response's `spans` field. When `group_by` is non-empty, returns aggregate group rows in the response's `groups` field. - `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 - `group_by` AgentGroupByRef[], nullable - `source` 'field' | 'column' | 'custom_attrs_string' | 'custom_attrs_int' | 'custom_attrs_float' | 'custom_attrs_bool' - `key` string, required - `alias` string, nullable - `measures` AgentSpanMeasureSpec[] - `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 - union - … - 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 - `group_distributions` AgentSpanGroupDistributionSpec[] - `alias` string, required - `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 - `bins` integer - `top_n` integer - `custom_attr_columns` AgentSpanValueRef[] - `source` 'field' | 'derived' | 'custom_attrs_string' | 'custom_attrs_int' | 'custom_attrs_float' | 'custom_attrs_bool' - `key` string, required - `include_details` boolean - `include_costs` boolean - `sort_by` AgentSortBy[], nullable - `field` string, required - `direction` 'asc' | 'desc' - `limit` integer - `offset` integer - `started_after` string, date-time, nullable - `started_before` string, date-time, nullable ## Response `200` Successful Response - AgentSpansQueryRes — Response from a spans query. Exactly one of `spans` or `groups` will be populated, based on whether the request specified `group_by`. - `spans` AgentSpanSchema[] - `project_id` string, required - `trace_id` string, required - `span_id` string, required - `parent_span_id` string, nullable - `span_name` string, nullable - `span_kind` 'UNSPECIFIED' | 'INTERNAL' | 'SERVER' | 'CLIENT' | 'PRODUCER' | 'CONSUMER', nullable - `started_at` string, date-time, nullable - `ended_at` string, date-time, nullable - `status_code` 'UNSET' | 'OK' | 'ERROR', nullable - `status_message` string, nullable - `operation_name` string, nullable - `provider_name` string, nullable - `agent_name` string, nullable - `agent_id` string, nullable - `agent_description` string, nullable - `agent_version` string, nullable - `request_model` string, nullable - `response_model` string, nullable - `response_id` string, nullable - `input_tokens` integer, nullable - `output_tokens` integer, nullable - `reasoning_tokens` integer, nullable - `cache_creation_input_tokens` integer, nullable - `cache_read_input_tokens` integer, nullable - `input_cost_usd` number, nullable - `output_cost_usd` number, nullable - `cache_read_cost_usd` number, nullable - `cache_creation_cost_usd` number, nullable - `total_cost_usd` number, nullable - `reasoning_content` string, nullable - `conversation_id` string, nullable - `conversation_name` string, nullable - `tool_name` string, nullable - `tool_type` string, nullable - `tool_call_id` string, nullable - `tool_description` string, nullable - `tool_definitions` string, nullable - `finish_reasons` string[] - `error_type` string, nullable - `request_temperature` number, nullable - `request_max_tokens` integer, nullable - `request_top_p` number, nullable - `request_frequency_penalty` number, nullable - `request_presence_penalty` number, nullable - `request_seed` integer, nullable - `request_stop_sequences` string[] - `request_choice_count` integer, nullable - `output_type` string, nullable - `input_messages` NormalizedMessage[] - unknown - `output_messages` NormalizedMessage[] - unknown - `system_instructions` string[] - `tool_call_arguments` string, nullable - `tool_call_result` string, nullable - `compaction_summary` string, nullable - `compaction_items_before` integer, nullable - `compaction_items_after` integer, nullable - `content_refs` string[] - `artifact_refs` string[] - `object_refs` string[] - `custom_attrs_string` object - `custom_attrs_int` object - `custom_attrs_float` object - `custom_attrs_bool` object - `server_address` string, nullable - `server_port` integer, nullable - `wb_user_id` string, nullable - `wb_run_id` string, nullable - `wb_run_step` integer, nullable - `wb_run_step_end` integer, nullable - `raw_span_dump` string, nullable - `groups` AgentSpanGroupRow[] - `group_keys` object - `span_count` integer - `invocation_count` integer - `conversation_count` integer - `total_input_tokens` integer - `total_cache_creation_input_tokens` integer - `total_cache_read_input_tokens` integer - `total_output_tokens` integer - `total_reasoning_tokens` integer - `total_duration_ms` integer - `error_count` integer - `total_cost_usd` number, nullable - `total_input_cost_usd` number, nullable - `total_output_cost_usd` number, nullable - `agent_names` string[] - `agent_versions` string[] - `provider_names` string[] - `request_models` string[] - `conversation_names` string[] - `first_seen` string, date-time, nullable - `last_seen` string, date-time, nullable - `first_message` unknown - `last_message` unknown - `metrics` object - `distributions` object - `total_count` integer ## 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)