---
title: "Timeseries"
method: GET
path: "/internal/v1/spans/{project_id}/timeseries"
tags: ["Querying"]
---

# Timeseries

`GET /internal/v1/spans/{project_id}/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

## Path parameters

- `project_id` integer, required

## Query parameters

- `time_start` string, date-time, required — RFC3339 timestamp.
- `time_end` string, date-time, required — RFC3339 timestamp.
- `query` string
- `where` string
- `search` string
- `search_attrs` string[]
- `system` string[]
- `column` string[]
- `duration_gte` integer
- `duration_lt` integer
- `limit` integer

## Response `200`

Timeseries data.

- object
  - `groups` object[], required — Array of group rows. Aggregated columns contain arrays of float values aligned with the time array.
  - `columns` QueryColumn[] — Column definitions for the result.
    - `name` string, required — Column name.
    - `expr` string — Column expression as written in the query.
    - `unit` string — Column unit (e.g., ms, bytes).
    - `isNum` boolean — Whether the column contains numeric values.
    - `isAgg` boolean — Whether the column is an aggregation.
    - `isGroup` boolean — Whether the column is a GROUP BY key.
    - `aggFunc` string — Aggregation function applied to this column.
  - `time` number[], required — Array of aligned timestamps as unix milliseconds.
  - `interval` integer, required — Time interval between data points in milliseconds.
  - `query` object[] — Parsed query parts with error state.
  - `sorting` OrderItem[] — Applied sorting configuration.
    - `key` string
    - `order` 'asc' | 'desc'
  - `whereAttrs` object — Map of WHERE attribute names to their matched values.

## Other responses

- `400` — Invalid request
- `401` — Authentication required
- `403` — Insufficient permissions
- `500` — Internal server error

---

[API](https://skmtc.net/uptrace/apis/uptrace-json-api.md) · [All operations](https://skmtc.net/uptrace/apis/uptrace-json-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/uptrace/uptrace-json-api/revisions/550c8881ab9a/schema)