# Retrieve an event's time series

Source: https://kirora.io/docs/api/reference/getEventSeries

`GET /v1/events/series`

Requires an API key with the `events:read` scope. [About keys and scopes](https://kirora.io/docs/api/reference/authentication)

Works with integration, agent and partner keys.

How many events of a name happened in each hour or day of the workspace's timezone (`timezone`), to catch tracking that broke: a line that falls to zero after a release. Accepted events only; refused ones are in the event log (`status=rejected`) with the reason. `from` (inclusive) and `to` (exclusive) choose the window, a date meaning the start of that day in `timezone`; it runs from the bucket holding `from` to the one holding the moment before `to`, without gaps, at most 366 points. `from` must be before `to`. Events past retention are gone and not counted.

## Query parameters

- `name` (string, required, 1–128 characters) — The event name, exactly as it was tracked.
- `interval` (string, required, one of `hour`, `day`) — The bucket size.
- `from` (string, optional) — Inclusive: a date-time, or a date meaning the start of that day in the workspace timezone. The series starts with the bucket holding it. By default 30 days (`day`) or 24 hours (`hour`) before `to`.
- `to` (string, optional) — Exclusive, in the same forms: the series ends with the bucket holding the moment before it. Now by default.

## Header parameters

- `Kirora-Workspace` (string, optional, pattern `^[A-Za-z0-9._:-]{1,128}$`) — Partner keys only: the child workspace to act in, by the external id the partner gave it. Without it, a partner key acts in its own workspace. Any other key that sends it is refused with 403, and an unknown workspace is 404.

## Returns

Returns `200 OK` with an `EventSeries` in `data`. Otherwise returns an error; [Errors](https://kirora.io/docs/api/reference/errors) lists every code and which to retry.

- `name` (string, required)
- `interval` (string, required, one of `hour`, `day`)
- `timezone` (string, required) — The workspace timezone the buckets follow.
- `points` (object[], required, at most 366 items) — One point per bucket, oldest first and without gaps, at most 366.
  - `startsAt` (string, required, date-time) — When this hour or day starts in `timezone`, as an instant.
  - `count` (integer, required, min 0) — Accepted events that happened in it.

## Example

```bash
curl 'https://api.kirora.io/v1/events/series?name=Order%20Completed&interval=hour' \
  -H "Authorization: Bearer $KIRORA_API_KEY"
```

Response `200`:

```json
{
  "data": {
    "name": "Order Completed",
    "interval": "day",
    "timezone": "Europe/London",
    "points": [
      {
        "startsAt": "2026-10-19T23:00:00.000Z",
        "count": 44
      },
      {
        "startsAt": "2026-10-20T23:00:00.000Z",
        "count": 41
      },
      {
        "startsAt": "2026-10-21T23:00:00.000Z",
        "count": 0
      }
    ]
  }
}
```