openapi: 3.2.0 info: title: Latitude Analytics API version: v1 description: Open-source AI agent monitoring platform. Full observability into what's failing in production. Discover underlying issues, get alerts when something breaks and verify your fix worked. servers: - url: https://api.latitude.so description: Production servers: - url: https://api.latitude.so tags: - name: Analytics paths: /v1/projects/{projectSlug}/analytics/query: post: tags: - Analytics x-fern-sdk-group-name: analytics x-fern-sdk-method-name: query summary: Run an analytics query description: Compute a metric over a filtered stream (`traces`, `sessions`, `spans`, `scores`, `behaviors`, `moments`), optionally broken down by a dimension and/or bucketed over time. Returns a tidy series — one point per breakdown value and/or time bucket — suitable for charts and reports. security: - ApiKeyAuth: [] operationId: queryAnalytics parameters: - schema: type: string description: Project slug (human-readable identifier) required: true description: Project slug (human-readable identifier) name: projectSlug in: path requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/AnalyticsQuery' responses: '200': description: The analytics series content: application/json: schema: $ref: '#/components/schemas/AnalyticsSeries' '400': description: Validation error content: application/json: schema: $ref: '#/components/schemas/Error' '401': description: Unauthorized content: application/json: schema: $ref: '#/components/schemas/Error' '404': description: Not found content: application/json: schema: $ref: '#/components/schemas/Error' components: schemas: FilterSet: type: object additionalProperties: type: array items: $ref: '#/components/schemas/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. 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 example: '2026-06-23T00:00:00Z' description: Inclusive lower bound (ISO-8601). toIso: type: string format: date-time example: '2026-06-30T00:00:00Z' 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: '#/components/schemas/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 example: '2026-06-23T00:00:00Z' description: Inclusive lower bound (ISO-8601). toIso: type: string format: date-time example: '2026-06-30T00:00:00Z' 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: '#/components/schemas/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 example: '2026-06-23T00:00:00Z' description: Inclusive lower bound (ISO-8601). toIso: type: string format: date-time example: '2026-06-30T00:00:00Z' 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: '#/components/schemas/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 example: '2026-06-23T00:00:00Z' description: Inclusive lower bound (ISO-8601). toIso: type: string format: date-time example: '2026-06-30T00:00:00Z' 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: '#/components/schemas/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 example: '2026-06-23T00:00:00Z' description: Inclusive lower bound (ISO-8601). toIso: type: string format: date-time example: '2026-06-30T00:00:00Z' 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: '#/components/schemas/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 example: '2026-06-23T00:00:00Z' description: Inclusive lower bound (ISO-8601). toIso: type: string format: date-time example: '2026-06-30T00:00:00Z' 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: '#/components/schemas/FilterSet' - description: Structured filter set applied to the stream (same DSL as `listTraces`). required: - stream - metric - range additionalProperties: false SpanRowFilterSet: type: object additionalProperties: type: array items: $ref: '#/components/schemas/FilterCondition' description: Structured filter set over span row fields. `gtePercentile` is not supported — use absolute thresholds or a percentile metric. Error: type: object properties: error: type: string required: - error 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 AnalyticsSeries: type: object properties: series: type: array items: type: object properties: key: type: string description: The breakdown value, present when `breakdown` was set. label: type: string description: Human-readable name for `key` when the breakdown value is an opaque id — the signal name for `signalId`, the cluster name for `cluster`. Absent for already-readable breakdowns. bucketStart: type: string description: ISO-8601 start of the time bucket, present when `timeBucket` was set. value: type: number description: 'The metric value: seconds for `duration`, dollars for `cost`, a 0–1 ratio for `errorRate`/`cacheHitRate`, otherwise a raw count/token total.' required: - value description: 'Tidy series: one point per breakdown key and/or time bucket.' required: - series securitySchemes: ApiKeyAuth: type: http scheme: bearer bearerFormat: API key description: 'Organization-scoped API key, sent as `Authorization: Bearer `.' x-fern-bearer: name: apiKey env: LATITUDE_API_KEY