Source: https://datafa.st/docs/api/website/analytics/timeseries
Markdown source: https://datafa.st/docs/api/website/analytics/timeseries.md
Description: Return time-bucketed analytics metrics for charts and reports.

# Get time series

`GET https://datafa.st/api/v1/analytics/timeseries`

Return time-bucketed analytics metrics for charts and reports.

## Request

### Authentication

- `df_` website API key for one website.
- `dft_` account token with `analytics:read`. Pass `websiteId` as a query parameter.


### Query parameters

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `fields` | string | Yes | Controls which metrics are returned for each time bucket and in `totals`. Possible values: `name`, `visitors`, `sessions`, `revenue`, `payments`, `conversion_rate`. Example: `fields=visitors,sessions,revenue`. |
| `interval` | string | Yes | Controls how DataFast groups rows over time. Possible values: `hour`, `day`, `week`, `month`. Use `hour` for same-day charts, `day` for daily trends, `week` for weekly summaries, and `month` for long-range reports. Example: `interval=day`. |
| `startAt` | string | No | Sets the beginning of the reporting window. Use it when you want a specific date range instead of the endpoint default. Must be provided with `endAt`. Example: `startAt=2026-05-01`. |
| `endAt` | string | No | Sets the end of the reporting window. Must be provided with `startAt`. Example: `endAt=2026-05-21`. |
| `timezone` | string | No | Controls how dates are interpreted and how time buckets are grouped. Defaults to the website timezone. Example: `timezone=America/New_York`. |
| `limit` | number | No | Controls how many rows are returned. Use it with `offset` to paginate through long lists. Defaults to `100`. Example: `limit=50`. |
| `offset` | number | No | Skips rows before returning results. Use it to fetch the next page after a previous request. Defaults to `0`. Example: `offset=50`. |
| `filter_country` | string | No | Limits results to visitors from one or more countries. Operators: `is`, `is_not`. Use country names or codes. Example: `filter_country=US,Canada`. |
| `filter_region` | string | No | Limits results to visitors from a region or state. Example: `filter_region=California`. |
| `filter_city` | string | No | Limits results to visitors from a city. Example: `filter_city=San Francisco`. |
| `filter_device` | string | No | Limits results by device type. Useful for mobile vs desktop analysis. Example: `filter_device=mobile`. |
| `filter_browser` | string | No | Limits results by browser. Use this to compare browser-specific traffic or revenue. Example: `filter_browser=Chrome,Safari`. |
| `filter_os` | string | No | Limits results by operating system. Example: `filter_os=iOS,Android`. |
| `filter_referrer` | string | No | Limits results by referrer domain or normalized source. Example: `filter_referrer=Google`. |
| `filter_page` | string | No | Limits results to visitors who viewed a page. Operators: `is`, `is_not`, `contains`, `does_not_contain`. Example: `filter_page=contains:/docs`. |
| `filter_entry_page` | string | No | Limits results by first page in the session. Operators: `is`, `is_not`, `contains`, `does_not_contain`. Example: `filter_entry_page=/pricing`. |
| `filter_hostname` | string | No | Limits results by tracked hostname. Useful when one website tracks multiple hostnames. Example: `filter_hostname=app.example.com`. |
| `filter_goal` | string | No | Limits results to visitors who completed a specific goal. Example: `filter_goal=signup`. |
| `filter_utm_source` | string | No | Limits results by UTM source. Example: `filter_utm_source=google`. |
| `filter_utm_medium` | string | No | Limits results by UTM medium. Example: `filter_utm_medium=cpc`. |
| `filter_utm_campaign` | string | No | Limits results by UTM campaign. Example: `filter_utm_campaign=launch`. |
| `filter_utm_term` | string | No | Limits results by UTM term. Example: `filter_utm_term=brand-keyword`. |
| `filter_utm_content` | string | No | Limits results by UTM content. Example: `filter_utm_content=hero-cta`. |
| `filter_ref` | string | No | Limits results by the `ref` URL parameter. Example: `filter_ref=twitter`. |
| `filter_source` | string | No | Limits results by the `source` URL parameter. Example: `filter_source=newsletter`. |
| `filter_via` | string | No | Limits results by the `via` URL parameter. Example: `filter_via=partner`. |

## Response

Returns a JSON object with `status` and endpoint-specific fields.

### Response fields

| Field | Type | Description |
| --- | --- | --- |
| `fields` | string[] | Controls which properties are included in the response. Use it to request only the metrics or metadata your integration needs. Requested fields. Requesting `revenue` also includes `payments`. |
| `interval` | string | Controls how time-series rows are grouped. For example, `day` returns one row per day and `hour` returns one row per hour. |
| `timezone` | string | Timezone used to interpret dates and group analytics buckets. Defaults to the website timezone. |
| `currency` | string | Currency code for money values, such as `USD` or `EUR`. |
| `totals` | object | Totals for requested fields. |
| `totals.revenueBreakdown` | object | New, renewal, and refund revenue totals when revenue is requested. |
| `data[].timestamp` | string | Event timestamp. Use it when recording historical events; defaults to the request time. |
| `data[].visitors` | number | Number of unique visitors represented by this row or time bucket. Use it to compare traffic volume across dates, pages, sources, countries, devices, or campaigns. |
| `data[].sessions` | number | Number of sessions represented by this row or time bucket. A visitor can create multiple sessions, so this can be higher than `visitors`. |
| `data[].revenue` | number | Revenue attributed to this row or time bucket, in the website currency. Use it to see which time periods or dimensions influenced paid conversions. |
| `data[].payments` | number | Number of payment events attributed to this row or time bucket. Use it when you need transaction count instead of revenue amount. |
| `data[].conversion_rate` | number | Revenue-based conversion rate for this row or bucket. Use it to compare how efficiently traffic converts. |
| `pagination` | object | Pagination metadata. |

### Errors

Common errors include `400` for invalid input, `401` for missing or invalid tokens, `403` for missing permission or suspended tracking, `404` for missing resources, and `500` for server errors.

## Code examples

### Example request

```bash
curl -X GET "https://datafa.st/api/v1/analytics/timeseries?fields=visitors,sessions,revenue,payments&interval=day&startAt=2026-05-01&endAt=2026-05-19" \
  -H "Authorization: Bearer df_xxx"
```

### Success response

```json
{
  "status": "success",
  "fields": ["visitors", "sessions", "revenue", "payments"],
  "interval": "day",
  "timezone": "America/New_York",
  "currency": "USD",
  "totals": {
    "visitors": 14213,
    "sessions": 20181,
    "revenue": 27351,
    "payments": 317
  },
  "data": [{
    "timestamp": "2026-05-01T00:00:00Z",
    "visitors": 528,
    "sessions": 604,
    "revenue": 249,
    "payments": 4
  }],
  "pagination": {
    "limit": 100,
    "offset": 0,
    "total": 19
  }
}
```