# Retrieve a segment's size history

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

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

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

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

- `id` (string, required, uuid) — The segment's id.

## Query parameters

- `from` (string, optional) — 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.
- `to` (string, optional) — 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-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 a `SegmentSizeHistory` in `data`. Otherwise returns an error; [Errors](https://kirora.io/docs/api/reference/errors) lists every code and which to retry.

- `segmentId` (string, required, uuid)
- `points` (object[], required) — Oldest first.
  - `day` (string, required, date) — The day, `YYYY-MM-DD` in the workspace timezone.
  - `memberCount` (integer, required, min 0) — Contacts that matched.
  - `joinedCount` (integer | null, required, min 0) — 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.
  - `leftCount` (integer | null, required, min 0) — Contacts that left that day; null as `joinedCount` is.
- `definitionChanges` (object[], required) — Days in the window the rules changed, oldest first.
  - `day` (string, required, date) — The day, `YYYY-MM-DD` in the workspace timezone.
  - `changedAt` (string, required, date-time) — That day's last save of the rules.

## Example

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

Response `200`:

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