> For the complete documentation index, see [llms.txt](https://docs.groundcover.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.groundcover.com/reference/remote-access-and-apis/api-examples/time-series-queries.md).

# Query gcQL Time Series

Aggregate logs, traces, and other gcQL signals into chart-ready time buckets.

Use a `search-time-series` endpoint to return evenly spaced time buckets from a gcQL aggregation.

### Endpoints

All routes below use **POST**:

| Signal                 | Endpoint                                         |
| ---------------------- | ------------------------------------------------ |
| Logs                   | `/api/logs/v2/search-time-series`                |
| Traces                 | `/api/traces/v2/search-time-series`              |
| Kubernetes events      | `/api/k8s/v2/events/search-time-series`          |
| APM measurements       | `/api/apm-measurements/search-time-series`       |
| AI observability       | `/api/gen-ai/search-time-series`                 |
| Ingestion measurements | `/api/ingestion-measurements/search-time-series` |
| Database measurements  | `/api/dbm-measurements/search-time-series`       |
| AWS cloud costs        | `/api/aws-cur/search-time-series`                |
| RUM events             | `/api/rum/records/search-time-series`            |
| RUM sessions           | `/api/rum/sessions/search-time-series`           |

The logs and traces time-series paths remain under `v2`, even when you use `v3/search` for tabular results. AWS cloud-cost queries use the same series format but allow `bucketDuration` to be omitted (default `24h`); see [Query Cloud Costs](https://docs.groundcover.com/reference/remote-access-and-apis/api-examples/query-cloud-costs.md) for report-granularity constraints.

### Authentication

Send `Authorization: Bearer <YOUR_API_KEY>` and `X-Backend-Id: <YOUR_BACKEND_ID>`. JSON requests also require `Content-Type: application/json`. The examples use `https://api.groundcover.com`; use your deployment's API URL for a self-hosted installation. Replace the example time range with one containing your data.

### Request Body

| Field            | Type    | Required               | Description                                                                                                                                                              |
| ---------------- | ------- | ---------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `start`, `end`   | string  | Yes                    | RFC3339 time range.                                                                                                                                                      |
| `query`          | string  | Yes for these examples | gcQL query containing a `stats` aggregation. Signal-specific restrictions still apply.                                                                                   |
| `bucketDuration` | string  | Yes                    | Bucket interval, such as `30s`, `1m`, `1h`, or `5 minutes`. Use short units or plural word units.                                                                        |
| `valueField`     | string  | No                     | Numeric aggregation column to use as the value. Omit only when the result has exactly one numeric value column. A comma-separated list selects multiple numeric columns. |
| `fillValue`      | number  | No                     | Fill empty buckets with this value. Default is `null`; use `0` only when missing data means zero for your use case.                                                      |
| `enableStream`   | boolean | No                     | Progressive SSE for logs, traces, and AI observability. Kubernetes events supports a single terminal SSE result. Not supported by the remaining endpoints in this table. |

The endpoint adds the time-bucket rollup. Supply an aggregation rather than only `fields` or `limit`. Use `X-Timezone` with an IANA timezone when timezone-aware bucket alignment is needed; the default is UTC.

### Count Error Logs per Workload

```bash
curl --request POST 'https://api.groundcover.com/api/logs/v2/search-time-series' \
  --header 'Authorization: Bearer <YOUR_API_KEY>' \
  --header 'X-Backend-Id: <YOUR_BACKEND_ID>' \
  --header 'Content-Type: application/json' \
  --data '{
  "start": "2026-10-28T10:00:00Z",
  "end": "2026-10-28T11:00:00Z",
  "query": "level:error | stats by (workload) count() as errors",
  "bucketDuration": "5m",
  "valueField": "errors",
  "fillValue": 0
}'
```

A non-streaming response is an array of series, rather than the v3 search envelope:

```json
[
  {
    "metric": {"workload": "checkout-service"},
    "velocity": [
      [1793181600, "12"],
      [1793181900, "0"]
    ]
  }
]
```

`metric` contains the grouping labels. Each `velocity` point is a `[timestamp, value]` pair: a Unix timestamp in seconds and a numeric string, or `null` for an unfilled bucket. The illustrative response above shows only two points.

### Select Multiple Value Columns

For a query that returns several numeric aggregates, set `valueField` to their comma-separated aliases, for example `"requests,errors"`. Each selected column becomes a separate series with a synthetic `metric_name` label. Do not also produce a result column named `metric_name` in that query. Missing or non-numeric selections return HTTP 400.

### Stream a Time Series

On logs, traces, or AI observability, set `enableStream: true` and use `curl -N`. Each SSE event has `data` containing the series array, plus `done` and `estimate`. Replace the previous snapshot, check terminal `error` fields, and wait for `done: true`, as described in [Search Responses and Streaming](https://docs.groundcover.com/reference/remote-access-and-apis/api-examples/search-v3-and-streaming.md#stream-results).

Kubernetes event time-series queries also accept `enableStream: true`, but return one `events_search` event with `done: true` and the final series array, without an `estimate` field.

### Signal-Specific Examples

* [APM measurements](https://docs.groundcover.com/reference/remote-access-and-apis/api-examples/query-apm-measurements.md)
* [AI observability](https://docs.groundcover.com/reference/remote-access-and-apis/api-examples/query-ai-observability.md)
* [Ingestion measurements](https://docs.groundcover.com/reference/remote-access-and-apis/api-examples/query-ingestion-measurements.md)
* [Database measurements](https://docs.groundcover.com/reference/remote-access-and-apis/api-examples/query-database-measurements.md)
* [AWS cloud costs](https://docs.groundcover.com/reference/remote-access-and-apis/api-examples/query-cloud-costs.md)
* [RUM](https://docs.groundcover.com/reference/remote-access-and-apis/api-examples/query-rum.md)


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.groundcover.com/reference/remote-access-and-apis/api-examples/time-series-queries.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
