Retrieve an event's time seriesMenu

Retrieve an event's time series

GET/v1/events/series

Requires an API key with the events:read scope. About keys and scopes

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

namestringrequired

The event name, exactly as it was tracked.

1–128 characters

intervalstringrequired

The bucket size.

one of hour, day

fromstringoptional

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.

tostringoptional

Exclusive, in the same forms: the series ends with the bucket holding the moment before it. Now by default.

Header parameters

Kirora-Workspacestringoptional

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.

pattern ^[A-Za-z0-9._:-]{1,128}$

Returns

Returns 200 OK with an EventSeries in data. Otherwise returns an error; Errors lists every code and which to retry.

namestringrequired

intervalstringrequired

one of hour, day

timezonestringrequired

The workspace timezone the buckets follow.

pointsobject[]required

One point per bucket, oldest first and without gaps, at most 366.

at most 366 items

2 child attributes

startsAtstringrequired

When this hour or day starts in timezone, as an instant.

date-time

countintegerrequired

Accepted events that happened in it.

min 0

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

const response = await fetch('https://api.kirora.io/v1/events/series?name=Order%20Completed&interval=hour', {
  method: 'GET',
  headers: {
    Authorization: `Bearer ${process.env.KIRORA_API_KEY}`,
  },
});
if (!response.ok) throw new Error(`Kirora API ${response.status}: ${await response.text()}`);
const { data } = await response.json();

import os

import requests

response = requests.get(
    "https://api.kirora.io/v1/events/series?name=Order%20Completed&interval=hour",
    headers={
        "Authorization": f"Bearer {os.environ['KIRORA_API_KEY']}",
    },
)
response.raise_for_status()
data = response.json()["data"]

package main

import (
	"encoding/json"
	"fmt"
	"io"
	"net/http"
	"os"
)

func main() {
	req, err := http.NewRequest("GET", "https://api.kirora.io/v1/events/series?name=Order%20Completed&interval=hour", nil)
	if err != nil {
		panic(err)
	}
	req.Header.Set("Authorization", "Bearer "+os.Getenv("KIRORA_API_KEY"))

	res, err := http.DefaultClient.Do(req)
	if err != nil {
		panic(err)
	}
	defer res.Body.Close()
	if res.StatusCode >= 300 {
		msg, _ := io.ReadAll(res.Body)
		panic(fmt.Sprintf("Kirora API %d: %s", res.StatusCode, msg))
	}

	var out struct {
		Data json.RawMessage `json:"data"`
	}
	if err := json.NewDecoder(res.Body).Decode(&out); err != nil {
		panic(err)
	}
}

using System.Net.Http.Headers;
using System.Text.Json;

using var http = new HttpClient();
using var request = new HttpRequestMessage(HttpMethod.Get, "https://api.kirora.io/v1/events/series?name=Order%20Completed&interval=hour");
request.Headers.Authorization = new AuthenticationHeaderValue("Bearer", Environment.GetEnvironmentVariable("KIRORA_API_KEY"));

using var response = await http.SendAsync(request);
if (!response.IsSuccessStatusCode)
    throw new HttpRequestException($"Kirora API {(int)response.StatusCode}: {await response.Content.ReadAsStringAsync()}");

using var document = JsonDocument.Parse(await response.Content.ReadAsStringAsync());
var data = document.RootElement.GetProperty("data");

Response · 200

{
  "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
      }
    ]
  }
}