Skip to main content
GET /api/public/metrics
The Metrics API enables you to retrieve customized analytics from your ABV data. This endpoint allows you to specify dimensions, metrics, filters, and time granularity to build powerful custom reports and dashboards for your LLM applications.

​
Overview

The Metrics API supports querying across different views (traces, observations, scores) and allows you to:
  • Select specific dimensions to group your data
  • Apply multiple metrics with different aggregation methods
  • Filter data based on metadata, timestamps, and other properties
  • Analyze data across time with customizable granularity
  • Order results according to your needs

​
Query Parameters

The API accepts a JSON query object passed as a URL-encoded parameter:
ParameterTypeDescription
queryJSON stringThe encoded query object defining what metrics to retrieve

​
Query Object Structure

FieldTypeRequiredDescription
viewstringYesThe data view to query: "traces", "observations", "scores-numeric", or "scores-categorical"
dimensionsarrayNoArray of dimension objects to group by, e.g. [{ "field": "name" }]
metricsarrayYesArray of metric objects to calculate, e.g. [{ "measure": "latency", "aggregation": "p95" }]
filtersarrayNoArray of filter objects to narrow results, e.g. [{ "column": "metadata", "operator": "contains", "key": "customKey", "value": "customValue", "type": "stringObject" }]
timeDimensionobjectNoConfiguration for time-based analysis, e.g. { "granularity": "day" }
fromTimestampstringYesISO timestamp for the start of the query period
toTimestampstringYesISO timestamp for the end of the query period
orderByarrayNoSpecification for result ordering, e.g. [{ "field": "name", "direction": "asc" }]

​
Dimension Object Structure

{ "field": "name" }

​
Metric Object Structure

{ "measure": "count", "aggregation": "count" }
Common measure types include:
  • count - Count of records
  • latency - Duration/latency metrics
Aggregation types include:
  • sum - Sum of values
  • avg - Average of values
  • count - Count of records
  • max - Maximum value
  • min - Minimum value
  • p50 - 50th percentile
  • p75 - 75th percentile
  • p90 - 90th percentile
  • p95 - 95th percentile
  • p99 - 99th percentile

​
Filter Object Structure

{
  "column": "metadata",
  "operator": "contains",
  "key": "customKey",
  "value": "customValue",
  "type": "stringObject"
}

​
Time Dimension Object

{
  "granularity": "day"
}
Supported granularities include: hour, day, week, month, and auto.

​
Example

Here’s an example of querying the number of traces grouped by name:

​
API

curl \
  -H "Authorization: Basic <BASIC AUTH HEADER>" \
  -G \
  --data-urlencode 'query={
    "view": "traces",
    "metrics": [{"measure": "count", "aggregation": "count"}],
    "dimensions": [{"field": "name"}],
    "filters": [],
    "fromTimestamp": "2025-05-01T00:00:00Z",
    "toTimestamp": "2025-05-13T00:00:00Z"
  }' \
  https://app.abv.dev/api/public/metrics
Response: 
{"data":[{"name":"trace-test-2","count_count":"10"},{"name":"trace-test-3","count_count":"5"},{"name":"trace-test-1","count_count":"3"}]}

​
Python SDK

Install package 
pip install abvdev

query = """
{
  "view": "traces",
  "metrics": [{"measure": "count", "aggregation": "count"}],
  "dimensions": [{"field": "name"}],
  "filters": [],
  "fromTimestamp": "2025-05-01T00:00:00Z",
  "toTimestamp": "2025-05-13T00:00:00Z"
}
"""
 
abv.api.metrics.metrics(query = query)

​
Data Model

The Metrics API provides access to several data views, each with its own set of dimensions and metrics you can query. This section outlines the available options for each view.

​
Available Views

ViewDescription
tracesQuery data at the trace level
observationsQuery data at the observation level
scores-numericQuery numeric and boolean scores
scores-categoricalQuery categorical (string) scores

​
Trace Dimensions

DimensionTypeDescription
idstringTrace ID
namestringTrace name
tagsstring[]Trace tags
userIdstringUser ID associated with the trace
sessionIdstringSession ID associated with the trace
releasestringRelease tag
versionstringVersion tag
environmentstringEnvironment (e.g., production, staging)
observationNamestringName of related observations
scoreNamestringName of related scores

​
Trace Metrics

MetricDescription
countCount of traces
observationsCountCount of observations within traces
scoresCountCount of scores within traces
latencyTrace duration in milliseconds
totalTokensTotal tokens used in the trace
totalCostTotal cost of the trace

​
Observation Dimensions

DimensionTypeDescription
idstringObservation ID
traceIdstringAssociated trace ID
traceNamestringName of the parent trace
environmentstringEnvironment (e.g., production, staging)
parentObservationIdstringID of parent observation
typestringObservation type
namestringObservation name
levelstringLog level
versionstringVersion
providedModelNamestringModel name
promptNamestringPrompt name
promptVersionstringPrompt version
userIdstringUser ID from parent trace
sessionIdstringSession ID from parent trace
traceReleasestringRelease from parent trace
traceVersionstringVersion from parent trace
scoreNamestringRelated score name

​
Observation Metrics

MetricDescription
countCount of observations
latencyObservation duration in milliseconds
totalTokensTotal tokens used
totalCostTotal cost
timeToFirstTokenTime to first token in milliseconds
countScoresCount of related scores

​
Score Dimensions (Common)

DimensionTypeDescription
idstringScore ID
namestringScore name
environmentstringEnvironment
sourcestringScore source
dataTypestringData type
traceIdstringRelated trace ID
traceNamestringRelated trace name
userIdstringUser ID from trace
sessionIdstringSession ID from trace
observationIdstringRelated observation ID
observationNamestringRelated observation name
observationModelNamestringModel used in related observation
observationPromptNamestringPrompt name used in related observation
observationPromptVersionstringPrompt version used in related observation
configIdstringConfiguration ID

​
Score Metrics

​
Numeric Scores

MetricDescription
countCount of scores
valueNumeric score value

​
Categorical Scores

MetricDescription
countCount of scores
Categorical scores have an additional dimension:
DimensionTypeDescription
stringValuestringString value of the categorical score