Source: https://datafa.st/docs/api/website/analytics/overview
Markdown source: https://datafa.st/docs/api/website/analytics/overview.md
Description: Return aggregate analytics metrics for a date range or all time.

# Get overview

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

Return aggregate analytics metrics for a date range or all time.

## 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 | No | Controls which summary metrics are returned. Possible values: `visitors`, `sessions`, `bounce_rate`, `avg_session_duration`, `currency`, `revenue`, `payments`, `revenue_per_visitor`, `conversion_rate`. Example: `fields=visitors,revenue,conversion_rate`. |
| `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`. |
| `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 |
| --- | --- | --- |
| `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. Total unique visitors in the selected period and filters. |
| `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`. Total sessions in the selected period. One visitor can create multiple sessions. |
| `data[].bounce_rate` | number | Percentage of sessions that ended without another tracked interaction. Use it to spot low-engagement traffic. |
| `data[].avg_session_duration` | number | Average session duration for the selected period. Average session duration for the selected period. |
| `data[].currency` | string | Currency code for money values, such as `USD` or `EUR`. |
| `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. Total attributed revenue for the selected period and filters. |
| `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. Total payment events for the selected period and filters. |
| `data[].revenue_per_visitor` | number | Average revenue per visitor. Use it to compare traffic quality across segments. |
| `data[].conversion_rate` | number | Revenue-based conversion rate for this row or bucket. Use it to compare how efficiently traffic converts. Payment conversion rate for the selected period and filters. |

### 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/overview?startAt=2026-05-01&endAt=2026-05-19" \
  -H "Authorization: Bearer df_xxx"
```

### Success response

```json
{
  "status": "success",
  "data": [{
    "visitors": 12450,
    "sessions": 16890,
    "bounce_rate": 42.1,
    "avg_session_duration": 68,
    "currency": "USD",
    "revenue": 28450,
    "payments": 328,
    "revenue_per_visitor": 2.29,
    "conversion_rate": 2.63
  }]
}
```