Retrieve a segment's size historyMenu

Retrieve a segment's size history

GET/v1/segments/{id}/size-history

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

Works with integration, agent and partner keys.

Returns the segment's size each day in the report window, as the background count last found it that day; it is counted every 15 minutes or so. Days are the workspace timezone's, as in every report. A day with no count (before the segment existed, or while the sweep was behind) is absent. Each day also says how many contacts joined and left (list them with GET /v1/segments/{id}/membership-changes), and definitionChanges the days the rules were saved, so a step in the line reads as an edit. Kept for 400 days; a window covers at most 366.

Path parameters

idstringrequired

The segment's id.

uuid

Query parameters

fromstringoptional: Start of the window, inclusive: a date-time, or a date meaning the start of that day in the workspace timezone. Give with to; omit both for the last 30 days.
tostringoptional: End of the window, exclusive, in the same forms. To include a whole last day, pass the day after it: from=2026-10-01&to=2026-10-08 covers 1 to 7 October. No later than the end of today; a window touches at most 366 days. Give with from.

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 a SegmentSizeHistory in data. Otherwise returns an error; Errors lists every code and which to retry.

segmentIdstringrequired

uuid

pointsobject[]required

Oldest first.

4 child attributes

daystringrequired

The day, YYYY-MM-DD in the workspace timezone.

date

memberCountintegerrequired

Contacts that matched.

min 0

joinedCountinteger | nullrequired

Contacts that joined that day; null before joins were counted. On the segment's first day it counts only those who joined after its first count.

min 0

leftCountinteger | nullrequired

Contacts that left that day; null as joinedCount is.

min 0

definitionChangesobject[]required

Days in the window the rules changed, oldest first.

2 child attributes

daystringrequired

The day, YYYY-MM-DD in the workspace timezone.

date

changedAtstringrequired

That day's last save of the rules.

date-time

curl https://api.kirora.io/v1/segments/018f2a4e-6b1c-7d3e-9f40-37386ae05a6b/size-history \
  -H "Authorization: Bearer $KIRORA_API_KEY"

const response = await fetch('https://api.kirora.io/v1/segments/018f2a4e-6b1c-7d3e-9f40-37386ae05a6b/size-history', {
  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/segments/018f2a4e-6b1c-7d3e-9f40-37386ae05a6b/size-history",
    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/segments/018f2a4e-6b1c-7d3e-9f40-37386ae05a6b/size-history", 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/segments/018f2a4e-6b1c-7d3e-9f40-37386ae05a6b/size-history");
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": {
    "segmentId": "0192f3a3-2c4d-7f6e-9b32-5a7b8c9d0e1f",
    "points": [
      {
        "day": "2026-10-14",
        "memberCount": 412,
        "joinedCount": 9,
        "leftCount": 3
      },
      {
        "day": "2026-10-15",
        "memberCount": 431,
        "joinedCount": 27,
        "leftCount": 8
      },
      {
        "day": "2026-10-16",
        "memberCount": 438,
        "joinedCount": 12,
        "leftCount": 5
      }
    ],
    "definitionChanges": [
      {
        "day": "2026-10-15",
        "changedAt": "2026-10-15T09:12:40.000Z"
      }
    ]
  }
}