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, reports, and custom dashboards. Choose which metrics to include and how to group them by hour, day, week, or month.

# Get time series

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

Return time-bucketed analytics metrics for charts, reports, and custom dashboards. Choose which metrics to include and how to group them by hour, day, week, or month.

If you omit `startAt` and `endAt`, DataFast applies a default window based on `interval`: last 24 hours for `hour`, last 30 days for `day`/`week`, and last 12 months for `month`.

Requesting `revenue` automatically includes `payments` in the response. Same-day date ranges upgrade the interval to `hour` automatically.

> **Related:** [Filter your data](/docs/datafast-filters)

## Request

#### Query parameters

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `fields` | string | Yes | Comma-separated response columns. Omit to return all valid fields for this endpoint. Valid: `name`, `visitors`, `sessions`, `revenue`, `payments`, `conversion_rate`. Example: `fields=visitors,sessions,revenue`. |
| `interval` | string | Yes | Time grouping. Values: `hour`, `day`, `week`, `month`. Example: `interval=day`. |
| `websiteId` | string | Required with dft_ | Required with a `dft_` account token on Website API routes. Omit with a `df_` website key. Example: `?websiteId=665f0b3c4d2e1a0012345678`. |
| `startAt` | string | No* | Start of the reporting window. Use `YYYY-MM-DD` for calendar days or an ISO timestamp. Must be provided together with `endAt`. Example: `startAt=2026-05-01`. |
| `endAt` | string | No* | End of the reporting window. Must be provided together with `startAt`. Example: `endAt=2026-05-21`. |
| `timezone` | string | No | Timezone used to interpret dates and group analytics buckets. Defaults to the website timezone. IANA timezone for dashboard periods and API date grouping. Examples: `"America/New_York"`, `"Europe/Paris"`, `"UTC"`. Defaults to the website timezone when omitted. |
| `limit` | number | No | Maximum rows to return. Default `100`, maximum `1000` on analytics endpoints and `250` on list visitors. Example: `limit=50`. |
| `offset` | number | No | Rows to skip before returning results. Use with `limit` for pagination. Default `0`. Example: `offset=50`. |
| `filter_country` | string | No | Limit results to one or more countries. Prefix with an operator: `is`, `is_not`. Accepts country names or codes. Example: `filter_country=US,Canada` or `filter_country=is_not:France`. |
| `filter_region` | string | No | Limit results by region or state. Example: `filter_region=California`. |
| `filter_city` | string | No | Limit results by city. Example: `filter_city=San Francisco`. |
| `filter_device` | string | No | Limit results by device type: `desktop`, `mobile`, or `tablet`. Example: `filter_device=mobile`. |
| `filter_browser` | string | No | Limit results by browser. Filtering `Safari` also includes Mobile Safari. Example: `filter_browser=Chrome,Safari`. |
| `filter_os` | string | No | Limit results by operating system. Example: `filter_os=iOS,Android`. |
| `filter_referrer` | string | No | Limit results by referrer domain or normalized source such as `Google` or `Direct/None`. Example: `filter_referrer=Google`. |
| `filter_page` | string | No | Limit 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 | Limit results by first page in the session. Same operators as `filter_page`. Example: `filter_entry_page=/pricing`. |
| `filter_hostname` | string | No | Limit results by tracked hostname. Example: `filter_hostname=app.example.com`. |
| `filter_goal` | string | No | Limit results to visitors who completed a goal. Example: `filter_goal=signup`. |
| `filter_utm_source` | string | No | Limit results by UTM source. Example: `filter_utm_source=google`. |
| `filter_utm_medium` | string | No | Limit results by UTM medium. Example: `filter_utm_medium=cpc`. |
| `filter_utm_campaign` | string | No | Limit results by UTM campaign. Example: `filter_utm_campaign=launch`. |
| `filter_utm_term` | string | No | Limit results by UTM term. Example: `filter_utm_term=brand-keyword`. |
| `filter_utm_content` | string | No | Limit results by UTM content. Example: `filter_utm_content=hero-cta`. |
| `filter_ref` | string | No | Limit results by the `ref` URL parameter. Example: `filter_ref=twitter`. |
| `filter_source` | string | No | Limit results by the `source` URL parameter. Example: `filter_source=newsletter`. |
| `filter_via` | string | No | Limit results by the `via` URL parameter. Example: `filter_via=partner`. |

#### Example query

```http
GET /api/v1/analytics/timeseries?fields=visitors,sessions,revenue&interval=day&startAt=2026-05-01&endAt=2026-05-21&filter_device=mobile
```

#### Example filters

Combine `filter_*` query params with date ranges:

```http
GET /api/v1/analytics/timeseries?fields=visitors,revenue&interval=day&startAt=2026-05-01&endAt=2026-05-21&filter_device=mobile&filter_country=US
```

Operators: `is`, `is_not`, and `contains` (pages only). Full reference: [filter your data](/docs/datafast-filters).

## Response

Returns a JSON object with `status: "success"` and endpoint-specific fields in `data` (and `pagination` when the endpoint is paginated).

#### 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. |

## Authentication

- **`df_` website API key:** The website is inferred from the key. You do not need a `websiteId` query parameter.
- **`dft_` account token:** Requires `analytics:read` permission and `?websiteId=` on every request. The token must be allowed to access that website.

Read [authentication and scopes](/docs/api/authentication) for token creation, permission lists, and scoped tokens.

### Errors

**400** — Missing or invalid `fields` or `interval`, partial date range (only one of `startAt`/`endAt`), or invalid `filter_*` value.

**404** — Website not found.

See [API errors](/docs/api#errors) for the standard error envelope, auth failures, validation errors, permission errors, and rate limits.

## 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
  }
}
```