# Get clicks over time `POST https://app.clik.so/api/analytics/timeseries` > **In short:** Returns click counts in time buckets of an hour, a day, a week or a month, for drawing a chart. It takes the same filters as the click summary. ## You need * **API key permission:** `read` * **Workspace role:** viewer or higher * **Plan:** any plan, including Free ## Example ```bash curl -X POST "https://app.clik.so/api/analytics/timeseries" \ -H "Authorization: Bearer $CLIKSO_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "from": "2026-10-01T00:00:00Z", "to": "2026-10-08T00:00:00Z", "interval": "day" }' ``` Response 200: ```json { "status": 200, "success": true, "message": "Success", "data": [ { "timestamp": "2026-10-01T00:00:00Z", "clicks": 52 }, { "timestamp": "2026-10-02T00:00:00Z", "clicks": 61 }, { "timestamp": "2026-10-04T00:00:00Z", "clicks": 47 } ] } ``` ## Request body | Field | Type | Required | Description | | ------------------ | ---------------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `from` | string · date-time | no | Start of the window, inclusive. An ISO 8601 date-time with a time zone, like `2026-10-01T00:00:00Z`. With `to`; if either is missing, the last 7 days are used. Anything that is not a valid date-time, or a `from` after `to`, is a `422`. | | `to` | string · date-time | no | End of the window, exclusive. An ISO 8601 date-time with a time zone, like `2026-10-08T00:00:00Z`. | | `interval` | string | no | Bucket size. Only used by the time-series endpoint. One of: `hour`, `day`, `week`, `month` Default `"hour"` | | `url_ids` | array of string · uuid | no | Only these links, by id. Up to 100 items | | `slugs` | array of string | no | Only these links, as `domain/short_code`, like `clik.is/summer-sale` or, for a nested code, `clik.is/acme/launch` (split at the first `/`). Up to 100 items | | `domains` | array of string | no | Only links on these domains. Covers at most 250 links. Up to 100 items | | `country` | array of string | no | 2-letter country codes, like `US`. Up to 100 items | | `city` | array of string | no | City names, as they appear in the summary. Up to 100 items | | `region` | array of string | no | Region names. Up to 100 items | | `continent` | array of string | no | Continent codes: `AF`, `AN`, `AS`, `EU`, `NA`, `OC`, `SA`. Up to 100 items | | `device` | array of string | no | `mobile`, `tablet`, `desktop` or `tv`. Up to 100 items | | `os` | array of string | no | Operating systems, like `iOS`, `Android`, `Windows`, `Mac OS`, `Linux`. Up to 100 items | | `browser` | array of string | no | Browsers, like `Chrome`, `Safari`, `Firefox`. Up to 100 items | | `referrer` | array of string | no | Exact referrer URLs, as they appear in the summary. Up to 100 items | | `short_links` | array of string | no | Full short URLs, like `https://clik.is/summer-sale`. Up to 100 items | | `destination_urls` | array of string | no | Exact destination URLs. Up to 100 items | | `utm_source` | array of string | no | `utm_source` values on the clicked short URL. Up to 100 items | | `utm_medium` | array of string | no | `utm_medium` values on the clicked short URL. Up to 100 items | | `utm_campaign` | array of string | no | `utm_campaign` values on the clicked short URL. Up to 100 items | | `utm_term` | array of string | no | `utm_term` values on the clicked short URL. Up to 100 items | | `utm_content` | array of string | no | `utm_content` values on the clicked short URL. Up to 100 items | ## Common errors | Status | Code | When | | ------ | --------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | 401 | `UNAUTHORIZED` | The API key is missing, malformed or unknown. | | 422 | `VALIDATION_ERROR` | `interval` is not hour, day, week or month, the body is not JSON, a filter list has more than 100 entries, `from` or `to` is not an ISO 8601 date-time, or `from` is after `to`. | | 429 | `RATE_LIMITED` | The workspace went over its per-minute analytics quota, or the key over its per-minute limit. Wait for `Retry-After` seconds. | | 429 | `USAGE_LIMIT_REACHED` | The workspace used its daily analytics quota. `details.resets_at` says when it resets (midnight UTC). | | 500 | `INTERNAL_ERROR` | The analytics store did not answer. Try again in a moment. | ## Good to know * Rate limit: Analytics quota per workspace, shared by all its keys: per minute Free 5, Starter 10, Pro 30, Business 60; per UTC day Free 100, Starter 1,000, Pro 5,000, Business 20,000. * `interval` is `hour`, `day`, `week` or `month`, and defaults to `hour`. Any other value is a `422`. * Buckets with no clicks are left out, so fill the gaps with zero when you draw a chart. * Timestamps are the start of each bucket, in UTC. Weeks start on Sunday. * Leave out `from` or `to` and you get the last 7 days. A `from` older than your plan keeps is moved forward; the `X-Analytics-Retention-Clamped` header says when. * The same request within 60 seconds is answered from a cache. It still counts toward your quota. --- Source: https://clik.so/docs/api/analytics/get-analytics-timeseries