---
title: "Contacts added over time"
method: GET
path: "/v1/sites/{site_id}/contacts/stats/timeline"
tags: ["Contacts"]
---

# Contacts added over time

`GET /v1/sites/{site_id}/contacts/stats/timeline`

## Request

- Base URL: `https://api.getsitecontrol.com`
- URL: `https://api.getsitecontrol.com/v1/sites/{site_id}/contacts/stats/timeline`
- Auth: HTTP bearer

Contacts added in each bucket of the period and still present, counted by
their current status. Call it for the growth of the list over time. These are
not subscription events: a contact deleted later drops out of past buckets,
and today's unsubscription changes yesterday's bucket.

Buckets are consecutive days, calendar weeks (Monday to Sunday) or calendar
months; the first and the last are cut to the period. Every bucket is
present, an empty one with zeros.

## Path parameters

- `site_id` integer, required

## Query parameters

- `interval` 'day' | 'week' | 'month': day, calendar week (Monday to Sunday) or calendar month.
- `from` string, date, required: First day of the period, UTC, included
- `to` string, date: Last day of the period, UTC, included; today when omitted

## Response `200`

Successful Response

- ContactsStatsTimeline
  - `period` StatsPeriod, required
    - `date_from` string, date, required: First day, UTC, included
    - `date_to` string, date, required: Last day, UTC, included
  - `interval` 'day' | 'week' | 'month', required: day, calendar week (Monday to Sunday) or calendar month.
  - `items` ContactsStatsTimelineItem[], required: Every bucket of the period in order, empty ones with zeros
    - `date_from` string, date, required
    - `date_to` string, date, required
    - `total` ContactCounts, required
      - `all` integer, required: The sum of the three statuses
      - `subscribed` integer, required: Subscribed, with double opt-in confirmed or not needed
      - `unsubscribed` integer, required: Unsubscribed, never subscribed or awaiting double opt-in
      - `bounced` integer, required: The address bounced or failed the e-mail check

## Other responses

- `400`: Unsupported GSC-Version
- `401`: Missing or invalid API key or access token
- `403`: Access denied
- `404`: Not found
- `422`: `stats_period_too_long`: the period is longer than allowed. `validation_failed`: a parameter is invalid
- `429`: `rate_limited`: a request limit is spent; this request also spends the heavy request limit
- `503`: `temporarily_unavailable`: the request took too long, or limits or idempotency keys cannot be enforced; narrow the filters or retry later

---

[API](https://skmtc.dev/getsitecontrol/apis/getsitecontrol-public-api.md) - [All operations](https://skmtc.dev/getsitecontrol/apis/getsitecontrol-public-api/llms.txt) - [OpenAPI document](https://skmtc.dev/getsitecontrol/apis/getsitecontrol-public-api/revisions/084fcad80e75?raw)