UPuptrace
Querying

Timeseries

Query time-bucketed aggregation data for spans. Use this to analyze trends over time, detect anomalies, or build charts. Returns aligned timestamps with auto-computed interval based on the time range. Use UQL aggregation query (e.g. perMin(count()) | group by service_name) with aggregate functions: count(), avg(), sum(), p50(), p90(), p99(), etc. Use column parameter to select specific aggregate columns for the timeseries. Supports WHERE filters, full-text search, system filtering, and duration filtering. Returns groups with arrays of float values aligned with the time array. Use list_span_groups instead when you need a single aggregated snapshot (not time-bucketed). Use quantiles instead when you only need latency percentiles (p50/p90/p99). Documentation: https://uptrace.dev/features/querying/spans

get/internal/v1/spans/{project_id}/timeseries

Request

Path parameters

project_idinteger required

Uptrace project ID.

Query parameters

time_startstring date-time required

RFC3339 timestamp.

Start time (inclusive) as RFC3339 timestamp.

time_endstring date-time required

RFC3339 timestamp.

End time (exclusive) as RFC3339 timestamp.

querystring

UQL aggregation query (e.g., perMin(count()) | group by service_name).

wherestring

Additional WHERE clause appended to the query.

searchstring

Full-text search for spans containing the given text.

search_attrsstring[]

Attribute names to search within when using search. Can be repeated for multiple attributes.

systemstring[]

Filter by system (e.g., log:error, db:postgresql). Can be repeated for multiple systems.

columnstring[]

Aggregate column names to include in the timeseries. Can be repeated for multiple columns.

duration_gteinteger

Duration greater than or equal to N (milliseconds).

duration_ltinteger

Duration less than N (milliseconds).

limitinteger

Limit number of results.

Response

Timeseries data.

groupsobject[] required

Array of group rows. Aggregated columns contain arrays of float values aligned with the time array.

timenumber[] required

Array of aligned timestamps as unix milliseconds.

intervalinteger required

Time interval between data points in milliseconds.

queryobject[]

Parsed query parts with error state.

whereAttrsobject

Map of WHERE attribute names to their matched values.

Changes

No recorded changes to this operation across all 1 revision of this API.