{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://raw.githubusercontent.com/api-evangelist/latitude-so/main/json-schema/latitude-so-analytics-query-schema.json",
  "title": "AnalyticsQuery",
  "x-generated": "2026-10-18",
  "x-method": "derived",
  "x-generator": "derive-json-schema.py",
  "x-source": "openapi/latitude-so-openapi.json#/components/schemas/AnalyticsQuery",
  "oneOf": [
    {
      "type": "object",
      "properties": {
        "stream": {
          "type": "string",
          "enum": [
            "traces"
          ]
        },
        "query": {
          "type": "string",
          "minLength": 1,
          "maxLength": 500,
          "description": "Semantic search query, combined with `filters` via AND. Ranks/filters by relevance."
        },
        "breakdown": {
          "type": "string",
          "enum": [
            "model",
            "provider",
            "service",
            "tool",
            "tag",
            "name",
            "userId",
            "status"
          ],
          "description": "Dimension to group by, one row per value."
        },
        "metric": {
          "oneOf": [
            {
              "type": "object",
              "properties": {
                "kind": {
                  "type": "string",
                  "enum": [
                    "count"
                  ]
                }
              },
              "required": [
                "kind"
              ]
            },
            {
              "type": "object",
              "properties": {
                "kind": {
                  "type": "string",
                  "enum": [
                    "errorRate"
                  ]
                }
              },
              "required": [
                "kind"
              ]
            },
            {
              "type": "object",
              "properties": {
                "kind": {
                  "type": "string",
                  "enum": [
                    "cacheHitRate"
                  ]
                }
              },
              "required": [
                "kind"
              ]
            },
            {
              "type": "object",
              "properties": {
                "kind": {
                  "type": "string",
                  "enum": [
                    "sum"
                  ]
                },
                "field": {
                  "type": "string",
                  "enum": [
                    "duration",
                    "cost",
                    "tokens"
                  ]
                }
              },
              "required": [
                "kind",
                "field"
              ]
            },
            {
              "type": "object",
              "properties": {
                "kind": {
                  "type": "string",
                  "enum": [
                    "min"
                  ]
                },
                "field": {
                  "type": "string",
                  "enum": [
                    "duration",
                    "cost",
                    "tokens"
                  ]
                }
              },
              "required": [
                "kind",
                "field"
              ]
            },
            {
              "type": "object",
              "properties": {
                "kind": {
                  "type": "string",
                  "enum": [
                    "max"
                  ]
                },
                "field": {
                  "type": "string",
                  "enum": [
                    "duration",
                    "cost",
                    "tokens"
                  ]
                }
              },
              "required": [
                "kind",
                "field"
              ]
            },
            {
              "type": "object",
              "properties": {
                "kind": {
                  "type": "string",
                  "enum": [
                    "avg"
                  ]
                },
                "field": {
                  "type": "string",
                  "enum": [
                    "duration",
                    "cost",
                    "tokens"
                  ]
                }
              },
              "required": [
                "kind",
                "field"
              ]
            },
            {
              "type": "object",
              "properties": {
                "kind": {
                  "type": "string",
                  "enum": [
                    "median"
                  ]
                },
                "field": {
                  "type": "string",
                  "enum": [
                    "duration",
                    "cost",
                    "tokens"
                  ]
                }
              },
              "required": [
                "kind",
                "field"
              ]
            },
            {
              "type": "object",
              "properties": {
                "kind": {
                  "type": "string",
                  "enum": [
                    "percentile"
                  ]
                },
                "field": {
                  "type": "string",
                  "enum": [
                    "duration",
                    "cost",
                    "tokens"
                  ]
                },
                "p": {
                  "type": "number",
                  "minimum": 1,
                  "maximum": 99
                }
              },
              "required": [
                "kind",
                "field",
                "p"
              ]
            }
          ],
          "description": "The metric: `count`, `errorRate`, `cacheHitRate`, `{sum|min|max|avg|median}` over `duration`/`cost`/`tokens`, or `{kind:'percentile',field,p}` for an arbitrary percentile (`p` in [1,99]; e.g. `p:95`)."
        },
        "timeBucket": {
          "type": "object",
          "properties": {
            "unit": {
              "type": "string",
              "enum": [
                "hour",
                "day",
                "week"
              ],
              "description": "Bucket granularity."
            },
            "size": {
              "type": "integer",
              "minimum": 0,
              "exclusiveMinimum": true,
              "maximum": 365,
              "default": 1,
              "description": "Number of units per bucket (e.g. `2` weeks)."
            }
          },
          "required": [
            "unit"
          ],
          "description": "Bucket the metric over time. Omit for a single aggregate."
        },
        "range": {
          "type": "object",
          "properties": {
            "fromIso": {
              "type": "string",
              "format": "date-time",
              "description": "Inclusive lower bound (ISO-8601)."
            },
            "toIso": {
              "type": "string",
              "format": "date-time",
              "description": "Exclusive upper bound (ISO-8601). Must be after `fromIso`."
            }
          },
          "required": [
            "fromIso",
            "toIso"
          ],
          "description": "The time window."
        },
        "orderBy": {
          "type": "object",
          "properties": {
            "by": {
              "type": "string",
              "enum": [
                "value",
                "key"
              ],
              "default": "value"
            },
            "direction": {
              "type": "string",
              "enum": [
                "asc",
                "desc"
              ],
              "default": "desc"
            }
          },
          "default": {
            "by": "value",
            "direction": "desc"
          },
          "description": "Sort for breakdown results. Defaults to value-desc."
        },
        "limit": {
          "type": "integer",
          "minimum": 0,
          "exclusiveMinimum": true,
          "maximum": 500,
          "default": 50,
          "description": "Maximum rows returned. Defaults to 50; max 500."
        },
        "filters": {
          "allOf": [
            {
              "$ref": "#/$defs/FilterSet"
            },
            {
              "description": "Structured filter set applied to the stream (same DSL as `listTraces`)."
            }
          ]
        }
      },
      "required": [
        "stream",
        "metric",
        "range"
      ],
      "additionalProperties": false
    },
    {
      "type": "object",
      "properties": {
        "stream": {
          "type": "string",
          "enum": [
            "sessions"
          ]
        },
        "query": {
          "type": "string",
          "minLength": 1,
          "maxLength": 500,
          "description": "Semantic search query, combined with `filters` via AND. Ranks/filters by relevance."
        },
        "breakdown": {
          "type": "string",
          "enum": [
            "model",
            "provider",
            "service",
            "tool",
            "tag",
            "userId",
            "status"
          ],
          "description": "Dimension to group by, one row per value."
        },
        "metric": {
          "oneOf": [
            {
              "type": "object",
              "properties": {
                "kind": {
                  "type": "string",
                  "enum": [
                    "count"
                  ]
                }
              },
              "required": [
                "kind"
              ]
            },
            {
              "type": "object",
              "properties": {
                "kind": {
                  "type": "string",
                  "enum": [
                    "errorRate"
                  ]
                }
              },
              "required": [
                "kind"
              ]
            },
            {
              "type": "object",
              "properties": {
                "kind": {
                  "type": "string",
                  "enum": [
                    "cacheHitRate"
                  ]
                }
              },
              "required": [
                "kind"
              ]
            },
            {
              "type": "object",
              "properties": {
                "kind": {
                  "type": "string",
                  "enum": [
                    "sum"
                  ]
                },
                "field": {
                  "type": "string",
                  "enum": [
                    "duration",
                    "cost",
                    "tokens"
                  ]
                }
              },
              "required": [
                "kind",
                "field"
              ]
            },
            {
              "type": "object",
              "properties": {
                "kind": {
                  "type": "string",
                  "enum": [
                    "min"
                  ]
                },
                "field": {
                  "type": "string",
                  "enum": [
                    "duration",
                    "cost",
                    "tokens"
                  ]
                }
              },
              "required": [
                "kind",
                "field"
              ]
            },
            {
              "type": "object",
              "properties": {
                "kind": {
                  "type": "string",
                  "enum": [
                    "max"
                  ]
                },
                "field": {
                  "type": "string",
                  "enum": [
                    "duration",
                    "cost",
                    "tokens"
                  ]
                }
              },
              "required": [
                "kind",
                "field"
              ]
            },
            {
              "type": "object",
              "properties": {
                "kind": {
                  "type": "string",
                  "enum": [
                    "avg"
                  ]
                },
                "field": {
                  "type": "string",
                  "enum": [
                    "duration",
                    "cost",
                    "tokens"
                  ]
                }
              },
              "required": [
                "kind",
                "field"
              ]
            },
            {
              "type": "object",
              "properties": {
                "kind": {
                  "type": "string",
                  "enum": [
                    "median"
                  ]
                },
                "field": {
                  "type": "string",
                  "enum": [
                    "duration",
                    "cost",
                    "tokens"
                  ]
                }
              },
              "required": [
                "kind",
                "field"
              ]
            },
            {
              "type": "object",
              "properties": {
                "kind": {
                  "type": "string",
                  "enum": [
                    "percentile"
                  ]
                },
                "field": {
                  "type": "string",
                  "enum": [
                    "duration",
                    "cost",
                    "tokens"
                  ]
                },
                "p": {
                  "type": "number",
                  "minimum": 1,
                  "maximum": 99
                }
              },
              "required": [
                "kind",
                "field",
                "p"
              ]
            }
          ],
          "description": "The metric: `count`, `errorRate`, `cacheHitRate`, `{sum|min|max|avg|median}` over `duration`/`cost`/`tokens`, or `{kind:'percentile',field,p}` for an arbitrary percentile (`p` in [1,99]; e.g. `p:95`)."
        },
        "timeBucket": {
          "type": "object",
          "properties": {
            "unit": {
              "type": "string",
              "enum": [
                "hour",
                "day",
                "week"
              ],
              "description": "Bucket granularity."
            },
            "size": {
              "type": "integer",
              "minimum": 0,
              "exclusiveMinimum": true,
              "maximum": 365,
              "default": 1,
              "description": "Number of units per bucket (e.g. `2` weeks)."
            }
          },
          "required": [
            "unit"
          ],
          "description": "Bucket the metric over time. Omit for a single aggregate."
        },
        "range": {
          "type": "object",
          "properties": {
            "fromIso": {
              "type": "string",
              "format": "date-time",
              "description": "Inclusive lower bound (ISO-8601)."
            },
            "toIso": {
              "type": "string",
              "format": "date-time",
              "description": "Exclusive upper bound (ISO-8601). Must be after `fromIso`."
            }
          },
          "required": [
            "fromIso",
            "toIso"
          ],
          "description": "The time window."
        },
        "orderBy": {
          "type": "object",
          "properties": {
            "by": {
              "type": "string",
              "enum": [
                "value",
                "key"
              ],
              "default": "value"
            },
            "direction": {
              "type": "string",
              "enum": [
                "asc",
                "desc"
              ],
              "default": "desc"
            }
          },
          "default": {
            "by": "value",
            "direction": "desc"
          },
          "description": "Sort for breakdown results. Defaults to value-desc."
        },
        "limit": {
          "type": "integer",
          "minimum": 0,
          "exclusiveMinimum": true,
          "maximum": 500,
          "default": 50,
          "description": "Maximum rows returned. Defaults to 50; max 500."
        },
        "filters": {
          "allOf": [
            {
              "$ref": "#/$defs/FilterSet"
            },
            {
              "description": "Structured filter set applied to the stream (same DSL as `listTraces`)."
            }
          ]
        }
      },
      "required": [
        "stream",
        "metric",
        "range"
      ],
      "additionalProperties": false
    },
    {
      "type": "object",
      "properties": {
        "stream": {
          "type": "string",
          "enum": [
            "spans"
          ]
        },
        "breakdown": {
          "type": "string",
          "enum": [
            "model",
            "provider",
            "service",
            "tool",
            "tag",
            "operation",
            "status"
          ],
          "description": "Dimension to group by, one row per value."
        },
        "metric": {
          "oneOf": [
            {
              "type": "object",
              "properties": {
                "kind": {
                  "type": "string",
                  "enum": [
                    "count"
                  ]
                }
              },
              "required": [
                "kind"
              ]
            },
            {
              "type": "object",
              "properties": {
                "kind": {
                  "type": "string",
                  "enum": [
                    "errorRate"
                  ]
                }
              },
              "required": [
                "kind"
              ]
            },
            {
              "type": "object",
              "properties": {
                "kind": {
                  "type": "string",
                  "enum": [
                    "cacheHitRate"
                  ]
                }
              },
              "required": [
                "kind"
              ]
            },
            {
              "type": "object",
              "properties": {
                "kind": {
                  "type": "string",
                  "enum": [
                    "sum"
                  ]
                },
                "field": {
                  "type": "string",
                  "enum": [
                    "duration",
                    "cost",
                    "tokens"
                  ]
                }
              },
              "required": [
                "kind",
                "field"
              ]
            },
            {
              "type": "object",
              "properties": {
                "kind": {
                  "type": "string",
                  "enum": [
                    "min"
                  ]
                },
                "field": {
                  "type": "string",
                  "enum": [
                    "duration",
                    "cost",
                    "tokens"
                  ]
                }
              },
              "required": [
                "kind",
                "field"
              ]
            },
            {
              "type": "object",
              "properties": {
                "kind": {
                  "type": "string",
                  "enum": [
                    "max"
                  ]
                },
                "field": {
                  "type": "string",
                  "enum": [
                    "duration",
                    "cost",
                    "tokens"
                  ]
                }
              },
              "required": [
                "kind",
                "field"
              ]
            },
            {
              "type": "object",
              "properties": {
                "kind": {
                  "type": "string",
                  "enum": [
                    "avg"
                  ]
                },
                "field": {
                  "type": "string",
                  "enum": [
                    "duration",
                    "cost",
                    "tokens"
                  ]
                }
              },
              "required": [
                "kind",
                "field"
              ]
            },
            {
              "type": "object",
              "properties": {
                "kind": {
                  "type": "string",
                  "enum": [
                    "median"
                  ]
                },
                "field": {
                  "type": "string",
                  "enum": [
                    "duration",
                    "cost",
                    "tokens"
                  ]
                }
              },
              "required": [
                "kind",
                "field"
              ]
            },
            {
              "type": "object",
              "properties": {
                "kind": {
                  "type": "string",
                  "enum": [
                    "percentile"
                  ]
                },
                "field": {
                  "type": "string",
                  "enum": [
                    "duration",
                    "cost",
                    "tokens"
                  ]
                },
                "p": {
                  "type": "number",
                  "minimum": 1,
                  "maximum": 99
                }
              },
              "required": [
                "kind",
                "field",
                "p"
              ]
            }
          ],
          "description": "The metric: `count`, `errorRate`, `cacheHitRate`, `{sum|min|max|avg|median}` over `duration`/`cost`/`tokens`, or `{kind:'percentile',field,p}` for an arbitrary percentile (`p` in [1,99]; e.g. `p:95`)."
        },
        "timeBucket": {
          "type": "object",
          "properties": {
            "unit": {
              "type": "string",
              "enum": [
                "hour",
                "day",
                "week"
              ],
              "description": "Bucket granularity."
            },
            "size": {
              "type": "integer",
              "minimum": 0,
              "exclusiveMinimum": true,
              "maximum": 365,
              "default": 1,
              "description": "Number of units per bucket (e.g. `2` weeks)."
            }
          },
          "required": [
            "unit"
          ],
          "description": "Bucket the metric over time. Omit for a single aggregate."
        },
        "range": {
          "type": "object",
          "properties": {
            "fromIso": {
              "type": "string",
              "format": "date-time",
              "description": "Inclusive lower bound (ISO-8601)."
            },
            "toIso": {
              "type": "string",
              "format": "date-time",
              "description": "Exclusive upper bound (ISO-8601). Must be after `fromIso`."
            }
          },
          "required": [
            "fromIso",
            "toIso"
          ],
          "description": "The time window."
        },
        "orderBy": {
          "type": "object",
          "properties": {
            "by": {
              "type": "string",
              "enum": [
                "value",
                "key"
              ],
              "default": "value"
            },
            "direction": {
              "type": "string",
              "enum": [
                "asc",
                "desc"
              ],
              "default": "desc"
            }
          },
          "default": {
            "by": "value",
            "direction": "desc"
          },
          "description": "Sort for breakdown results. Defaults to value-desc."
        },
        "limit": {
          "type": "integer",
          "minimum": 0,
          "exclusiveMinimum": true,
          "maximum": 500,
          "default": 50,
          "description": "Maximum rows returned. Defaults to 50; max 500."
        },
        "filters": {
          "$ref": "#/$defs/SpanRowFilterSet"
        }
      },
      "required": [
        "stream",
        "metric",
        "range"
      ],
      "additionalProperties": false
    },
    {
      "type": "object",
      "properties": {
        "stream": {
          "type": "string",
          "enum": [
            "scores"
          ],
          "description": "Scored occurrences. A signal is scores carrying a `signalId` — analyze one signal via `stream: \"scores\"` filtered by `score.signalId` (or broken down by `signalId`)."
        },
        "breakdown": {
          "type": "string",
          "enum": [
            "signalId",
            "source",
            "model",
            "provider",
            "service",
            "tool",
            "tag"
          ],
          "description": "Dimension to group by: `signalId`/`source` (direct) or a trace dim (`model`…`tag`)."
        },
        "metric": {
          "oneOf": [
            {
              "type": "object",
              "properties": {
                "kind": {
                  "type": "string",
                  "enum": [
                    "count"
                  ]
                }
              },
              "required": [
                "kind"
              ]
            },
            {
              "type": "object",
              "properties": {
                "kind": {
                  "type": "string",
                  "enum": [
                    "passRate"
                  ]
                }
              },
              "required": [
                "kind"
              ]
            },
            {
              "type": "object",
              "properties": {
                "kind": {
                  "type": "string",
                  "enum": [
                    "errorRate"
                  ]
                }
              },
              "required": [
                "kind"
              ]
            },
            {
              "type": "object",
              "properties": {
                "kind": {
                  "type": "string",
                  "enum": [
                    "avg"
                  ]
                },
                "field": {
                  "type": "string",
                  "enum": [
                    "value"
                  ]
                }
              },
              "required": [
                "kind",
                "field"
              ]
            },
            {
              "type": "object",
              "properties": {
                "kind": {
                  "type": "string",
                  "enum": [
                    "min"
                  ]
                },
                "field": {
                  "type": "string",
                  "enum": [
                    "value"
                  ]
                }
              },
              "required": [
                "kind",
                "field"
              ]
            },
            {
              "type": "object",
              "properties": {
                "kind": {
                  "type": "string",
                  "enum": [
                    "max"
                  ]
                },
                "field": {
                  "type": "string",
                  "enum": [
                    "value"
                  ]
                }
              },
              "required": [
                "kind",
                "field"
              ]
            },
            {
              "type": "object",
              "properties": {
                "kind": {
                  "type": "string",
                  "enum": [
                    "median"
                  ]
                },
                "field": {
                  "type": "string",
                  "enum": [
                    "value"
                  ]
                }
              },
              "required": [
                "kind",
                "field"
              ]
            }
          ],
          "description": "The metric: `count`, `passRate`, `errorRate`, or `{avg|min|max|median}` of the 0–1 score `value`."
        },
        "timeBucket": {
          "type": "object",
          "properties": {
            "unit": {
              "type": "string",
              "enum": [
                "hour",
                "day",
                "week"
              ],
              "description": "Bucket granularity."
            },
            "size": {
              "type": "integer",
              "minimum": 0,
              "exclusiveMinimum": true,
              "maximum": 365,
              "default": 1,
              "description": "Number of units per bucket (e.g. `2` weeks)."
            }
          },
          "required": [
            "unit"
          ],
          "description": "Bucket the metric over time. Omit for a single aggregate."
        },
        "range": {
          "type": "object",
          "properties": {
            "fromIso": {
              "type": "string",
              "format": "date-time",
              "description": "Inclusive lower bound (ISO-8601)."
            },
            "toIso": {
              "type": "string",
              "format": "date-time",
              "description": "Exclusive upper bound (ISO-8601). Must be after `fromIso`."
            }
          },
          "required": [
            "fromIso",
            "toIso"
          ],
          "description": "The time window."
        },
        "orderBy": {
          "type": "object",
          "properties": {
            "by": {
              "type": "string",
              "enum": [
                "value",
                "key"
              ],
              "default": "value"
            },
            "direction": {
              "type": "string",
              "enum": [
                "asc",
                "desc"
              ],
              "default": "desc"
            }
          },
          "default": {
            "by": "value",
            "direction": "desc"
          },
          "description": "Sort for breakdown results. Defaults to value-desc."
        },
        "limit": {
          "type": "integer",
          "minimum": 0,
          "exclusiveMinimum": true,
          "maximum": 500,
          "default": 50,
          "description": "Maximum rows returned. Defaults to 50; max 500."
        },
        "filters": {
          "allOf": [
            {
              "$ref": "#/$defs/FilterSet"
            },
            {
              "description": "Structured filter set applied to the stream (same DSL as `listTraces`)."
            }
          ]
        }
      },
      "required": [
        "stream",
        "metric",
        "range"
      ],
      "additionalProperties": false
    },
    {
      "type": "object",
      "properties": {
        "stream": {
          "type": "string",
          "enum": [
            "behaviors"
          ],
          "description": "Taxonomy observations — behavior instances clustered from session moments."
        },
        "breakdown": {
          "type": "string",
          "enum": [
            "cluster",
            "session",
            "method"
          ],
          "description": "Dimension to group by: `cluster`, `session`, or `method`."
        },
        "metric": {
          "oneOf": [
            {
              "type": "object",
              "properties": {
                "kind": {
                  "type": "string",
                  "enum": [
                    "count"
                  ]
                }
              },
              "required": [
                "kind"
              ]
            },
            {
              "type": "object",
              "properties": {
                "kind": {
                  "type": "string",
                  "enum": [
                    "avg"
                  ]
                },
                "field": {
                  "type": "string",
                  "enum": [
                    "confidence"
                  ]
                }
              },
              "required": [
                "kind",
                "field"
              ]
            },
            {
              "type": "object",
              "properties": {
                "kind": {
                  "type": "string",
                  "enum": [
                    "min"
                  ]
                },
                "field": {
                  "type": "string",
                  "enum": [
                    "confidence"
                  ]
                }
              },
              "required": [
                "kind",
                "field"
              ]
            },
            {
              "type": "object",
              "properties": {
                "kind": {
                  "type": "string",
                  "enum": [
                    "max"
                  ]
                },
                "field": {
                  "type": "string",
                  "enum": [
                    "confidence"
                  ]
                }
              },
              "required": [
                "kind",
                "field"
              ]
            },
            {
              "type": "object",
              "properties": {
                "kind": {
                  "type": "string",
                  "enum": [
                    "median"
                  ]
                },
                "field": {
                  "type": "string",
                  "enum": [
                    "confidence"
                  ]
                }
              },
              "required": [
                "kind",
                "field"
              ]
            }
          ],
          "description": "The metric: `count`, or `{avg|min|max|median}` of the 0–1 assignment `confidence`."
        },
        "timeBucket": {
          "type": "object",
          "properties": {
            "unit": {
              "type": "string",
              "enum": [
                "hour",
                "day",
                "week"
              ],
              "description": "Bucket granularity."
            },
            "size": {
              "type": "integer",
              "minimum": 0,
              "exclusiveMinimum": true,
              "maximum": 365,
              "default": 1,
              "description": "Number of units per bucket (e.g. `2` weeks)."
            }
          },
          "required": [
            "unit"
          ],
          "description": "Bucket the metric over time. Omit for a single aggregate."
        },
        "range": {
          "type": "object",
          "properties": {
            "fromIso": {
              "type": "string",
              "format": "date-time",
              "description": "Inclusive lower bound (ISO-8601)."
            },
            "toIso": {
              "type": "string",
              "format": "date-time",
              "description": "Exclusive upper bound (ISO-8601). Must be after `fromIso`."
            }
          },
          "required": [
            "fromIso",
            "toIso"
          ],
          "description": "The time window."
        },
        "orderBy": {
          "type": "object",
          "properties": {
            "by": {
              "type": "string",
              "enum": [
                "value",
                "key"
              ],
              "default": "value"
            },
            "direction": {
              "type": "string",
              "enum": [
                "asc",
                "desc"
              ],
              "default": "desc"
            }
          },
          "default": {
            "by": "value",
            "direction": "desc"
          },
          "description": "Sort for breakdown results. Defaults to value-desc."
        },
        "limit": {
          "type": "integer",
          "minimum": 0,
          "exclusiveMinimum": true,
          "maximum": 500,
          "default": 50,
          "description": "Maximum rows returned. Defaults to 50; max 500."
        },
        "filters": {
          "allOf": [
            {
              "$ref": "#/$defs/FilterSet"
            },
            {
              "description": "Structured filter set applied to the stream (same DSL as `listTraces`)."
            }
          ]
        }
      },
      "required": [
        "stream",
        "metric",
        "range"
      ],
      "additionalProperties": false
    },
    {
      "type": "object",
      "properties": {
        "stream": {
          "type": "string",
          "enum": [
            "moments"
          ],
          "description": "Semantic-moment labels — kind/actor-tagged moments detected within a session."
        },
        "breakdown": {
          "type": "string",
          "enum": [
            "kind",
            "actor",
            "session"
          ],
          "description": "Dimension to group by: `kind`, `actor`, or `session`."
        },
        "metric": {
          "oneOf": [
            {
              "type": "object",
              "properties": {
                "kind": {
                  "type": "string",
                  "enum": [
                    "count"
                  ]
                }
              },
              "required": [
                "kind"
              ]
            },
            {
              "type": "object",
              "properties": {
                "kind": {
                  "type": "string",
                  "enum": [
                    "avg"
                  ]
                },
                "field": {
                  "type": "string",
                  "enum": [
                    "confidence",
                    "coherence"
                  ]
                }
              },
              "required": [
                "kind",
                "field"
              ]
            },
            {
              "type": "object",
              "properties": {
                "kind": {
                  "type": "string",
                  "enum": [
                    "min"
                  ]
                },
                "field": {
                  "type": "string",
                  "enum": [
                    "confidence",
                    "coherence"
                  ]
                }
              },
              "required": [
                "kind",
                "field"
              ]
            },
            {
              "type": "object",
              "properties": {
                "kind": {
                  "type": "string",
                  "enum": [
                    "max"
                  ]
                },
                "field": {
                  "type": "string",
                  "enum": [
                    "confidence",
                    "coherence"
                  ]
                }
              },
              "required": [
                "kind",
                "field"
              ]
            },
            {
              "type": "object",
              "properties": {
                "kind": {
                  "type": "string",
                  "enum": [
                    "median"
                  ]
                },
                "field": {
                  "type": "string",
                  "enum": [
                    "confidence",
                    "coherence"
                  ]
                }
              },
              "required": [
                "kind",
                "field"
              ]
            }
          ],
          "description": "The metric: `count`, or `{avg|min|max|median}` of the 0–1 label `confidence` or moment `coherence`."
        },
        "timeBucket": {
          "type": "object",
          "properties": {
            "unit": {
              "type": "string",
              "enum": [
                "hour",
                "day",
                "week"
              ],
              "description": "Bucket granularity."
            },
            "size": {
              "type": "integer",
              "minimum": 0,
              "exclusiveMinimum": true,
              "maximum": 365,
              "default": 1,
              "description": "Number of units per bucket (e.g. `2` weeks)."
            }
          },
          "required": [
            "unit"
          ],
          "description": "Bucket the metric over time. Omit for a single aggregate."
        },
        "range": {
          "type": "object",
          "properties": {
            "fromIso": {
              "type": "string",
              "format": "date-time",
              "description": "Inclusive lower bound (ISO-8601)."
            },
            "toIso": {
              "type": "string",
              "format": "date-time",
              "description": "Exclusive upper bound (ISO-8601). Must be after `fromIso`."
            }
          },
          "required": [
            "fromIso",
            "toIso"
          ],
          "description": "The time window."
        },
        "orderBy": {
          "type": "object",
          "properties": {
            "by": {
              "type": "string",
              "enum": [
                "value",
                "key"
              ],
              "default": "value"
            },
            "direction": {
              "type": "string",
              "enum": [
                "asc",
                "desc"
              ],
              "default": "desc"
            }
          },
          "default": {
            "by": "value",
            "direction": "desc"
          },
          "description": "Sort for breakdown results. Defaults to value-desc."
        },
        "limit": {
          "type": "integer",
          "minimum": 0,
          "exclusiveMinimum": true,
          "maximum": 500,
          "default": 50,
          "description": "Maximum rows returned. Defaults to 50; max 500."
        },
        "filters": {
          "allOf": [
            {
              "$ref": "#/$defs/FilterSet"
            },
            {
              "description": "Structured filter set applied to the stream (same DSL as `listTraces`)."
            }
          ]
        }
      },
      "required": [
        "stream",
        "metric",
        "range"
      ],
      "additionalProperties": false
    }
  ],
  "$defs": {
    "FilterCondition": {
      "type": "object",
      "properties": {
        "op": {
          "type": "string",
          "enum": [
            "eq",
            "neq",
            "gt",
            "gte",
            "lt",
            "lte",
            "in",
            "notIn",
            "contains",
            "notContains",
            "gtePercentile"
          ],
          "description": "Comparison operator applied to the field's value (e.g. `eq`, `neq`, `in`). The full operator list lives in the API reference."
        },
        "value": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "number"
            },
            {
              "type": "boolean"
            },
            {
              "type": "array",
              "items": {
                "anyOf": [
                  {
                    "type": "string"
                  },
                  {
                    "type": "number"
                  }
                ]
              }
            }
          ],
          "description": "Right-hand value compared against the field. Arrays are required for `in` / `notIn`-style operators."
        }
      },
      "required": [
        "op",
        "value"
      ]
    },
    "FilterSet": {
      "type": "object",
      "additionalProperties": {
        "type": "array",
        "items": {
          "$ref": "#/$defs/FilterCondition"
        }
      },
      "description": "Filter set keyed by field name. Each entry holds an array of conditions ANDed together for that field; field-level groups are also ANDed across the set."
    },
    "SpanRowFilterSet": {
      "type": "object",
      "additionalProperties": {
        "type": "array",
        "items": {
          "$ref": "#/$defs/FilterCondition"
        }
      },
      "description": "Structured filter set over span row fields. `gtePercentile` is not supported — use absolute thresholds or a percentile metric."
    }
  }
}