Source: https://datafa.st/docs/api-timeseries
Markdown source: https://datafa.st/docs/api-timeseries.md
Description: Retrieve time series analytics data for visitors, sessions, revenue, or conversion rate.

# Get time series data

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

Retrieve time series analytics data aggregated by hour, day, week, or month. Requires [Bearer Token](/docs/api-introduction) authentication.

## Response

### Single Field Mode (using `fields` parameter with one field)

**Success (200 OK):** Returns time series data with a single value per timestamp

```json
{
  "status": "success",
  "fields": ["visitors"],
  "interval": "day",
  "timezone": "UTC",
  "currency": null,
  "totals": {
    "visitors": 1234
  },
  "data": [
    {
      "visitors": 45,
      "name": "01 Jan",
      "timestamp": "2024-01-01T00:00:00Z"
    },
    {
      "visitors": 52,
      "name": "02 Jan",
      "timestamp": "2024-01-02T00:00:00Z"
    }
  ],
  "pagination": {
    "limit": 100,
    "offset": 0,
    "total": 30
  }
}
```

### Multi-Field Mode (using `fields` parameter)

**Success (200 OK):** Returns time series data with multiple fields per timestamp

```json
{
  "status": "success",
  "fields": [
    "visitors",
    "name",
    "sessions",
    "revenue",
    "conversion_rate"
  ],
  "interval": "day",
  "timezone": "Asia/Calcutta",
  "currency": "$",
  "totals": {
    "visitors": 14213,
    "sessions": 20181,
    "revenue": 27351,
    "revenueBreakdown": {
      "new": 22150.00,
      "renewal": 5201.00,
      "refund": 0.00
    },
    "conversion_rate": 1.92
  },
  "data": [
    {
      "visitors": 528,
      "name": "17 Dec",
      "sessions": 604,
      "revenue": 0,
      "revenueBreakdown": {
        "new": 0.00,
        "renewal": 0.00,
        "refund": 0.00
      },
      "conversion_rate": 0,
      "timestamp": "2025-12-17T00:00:00+05:30"
    },
    {
      "visitors": 472,
      "name": "18 Dec",
      "sessions": 534,
      "revenue": 468,
      "revenueBreakdown": {
        "new": 380.00,
        "renewal": 88.00,
        "refund": 0.00
      },
      "conversion_rate": 0.99,
      "timestamp": "2025-12-18T00:00:00+05:30"
    },
    {
      "visitors": 428,
      "name": "19 Dec",
      "sessions": 490,
      "revenue": 299,
      "revenueBreakdown": {
        "new": 249.00,
        "renewal": 50.00,
        "refund": 0.00
      },
      "conversion_rate": 0.70,
      "timestamp": "2025-12-19T00:00:00+05:30"
    }
  ],
  "pagination": {
    "limit": 5,
    "offset": 0,
    "total": 30
  }
}
```

## Notes

- The API automatically upgrades to hourly granularity for same-day queries when using coarser intervals (day, week, month)
- **Revenue field:** Always includes both new and renewal revenue (total revenue)
  - When `revenue` field is requested, a `revenueBreakdown` object is automatically included with:
    - `new`: New revenue from first-time purchases
    - `renewal`: Revenue from subscription renewals
    - `refund`: Refunded revenue amount
  - All breakdown values are numbers rounded to 2 decimal places
- **Conversion rate:** Revenue-based conversion rate (revenue per visitor)
  - If your website has `includeRenewalRevenue` enabled: `(new revenue + renewal revenue) / unique visitors`
  - If `includeRenewalRevenue` is disabled: `new revenue / unique visitors`
  - This provides a monetary conversion metric rather than a transaction count metric
- Timestamps are returned in ISO 8601 format
- If both `startAt` and `endAt` are provided as full-day UTC timestamps (midnight to 23:59), they are automatically converted to simple dates for timezone-aware interpretation

## Errors

- **400 Bad Request:** Invalid parameters or missing required parameters
- **401 Unauthorized:** Missing or invalid API key
- **404 Not Found:** Website not found
- **500 Internal Server Error:** Server-side issue

## Query parameters

### Required parameters

- **`fields`** (string): Comma-separated list of fields to return. Valid fields: `visitors`, `sessions`, `revenue`, `conversion_rate`, `name`.

### Optional parameters

- **`startAt`** (string): Start date/time in ISO 8601 format (e.g., 2024-01-01T00:00:00Z or 2024-01-01). If omitted, defaults are applied based on interval:
  - hour: last 24 hours
  - day or week: last 30 days
  - month: last 12 months

- **`endAt`** (string): End date/time in ISO 8601 format. Must be provided together with `startAt` if using custom date range

- **`timezone`** (string): Timezone for data aggregation (e.g., UTC, America/New_York, Europe/Amsterdam). Defaults to your website's timezone if not specified

## Filter parameters

You can filter the data using simple, direct query parameters. Pass the parameter name with comma-separated values.

### Location filters

- **`country`** (string): Filter by country name or code (e.g., United States, US)
  - Example: `country=United States,Canada`
- **`region`** (string): Filter by region/state
  - Example: `region=California,New York`
- **`city`** (string): Filter by city name
  - Example: `city=San Francisco,New York`

### Device and browser filters

- **`device`** (string): Filter by device type (desktop, mobile, tablet)
  - Example: `device=mobile,tablet`
- **`browser`** (string): Filter by browser name (e.g., Chrome, Safari, Firefox, Edge)
  - Note: Filtering by Safari automatically includes Mobile Safari
  - Example: `browser=Chrome,Safari`
- **`os`** (string): Filter by operating system (e.g., Mac OS, Windows, iOS, Android)
  - Example: `os=Mac OS,Windows`

### Traffic source filters

- **`referrer`** (string): Filter by referrer domain or popular referrer name (e.g., google.com, Google, Facebook, Direct/None)
  - Supports popular referrer names that get automatically normalized to domains
  - Example: `referrer=google.com,facebook.com`
- **`ref`** (string): Filter by ref URL parameter
  - Example: `ref=twitter,newsletter`
- **`source`** (string): Filter by source URL parameter
  - Example: `source=google,facebook`
- **`via`** (string): Filter by via URL parameter
  - Example: `via=affiliate,partner`

### UTM parameter filters

- **`utm_source`** (string): Filter by UTM source parameter
  - Example: `utm_source=google,facebook`
- **`utm_medium`** (string): Filter by UTM medium parameter (e.g., cpc, email, social)
  - Example: `utm_medium=cpc,email`
- **`utm_campaign`** (string): Filter by UTM campaign parameter
  - Example: `utm_campaign=summer_sale,product_launch`
- **`utm_term`** (string): Filter by UTM term parameter, typically used for keywords
  - Example: `utm_term=keyword1,keyword2`
- **`utm_content`** (string): Filter by UTM content parameter
  - Example: `utm_content=ad_variant_a,ad_variant_b`

### Page and content filters

- **`page`** or **`entry_page`** (string): Filter by page path/URL
  - Example: `page=/pricing,/about`
- **`hostname`** (string): Filter by hostname/domain
  - Example: `hostname=example.com,www.example.com`

### Multiple filter example

```http
GET /api/v1/analytics/timeseries?metric=visitors&interval=day&country=United States,Canada&device=mobile&utm_source=google&page=/pricing
```

See [DataFast filters documentation](/docs/datafast-filters) for more details on using filters in the dashboard.

## Code examples

### Example request (Node.js/Express)

```javascript
// Get daily visitors for the last 30 days
const response = await fetch(
  "https://datafa.st/api/v1/analytics/timeseries?fields=visitors&interval=day&limit=30",
  {
    method: "GET",
    headers: {
      Authorization: `Bearer ${DATAFAST_API_KEY}`,
      "Content-Type": "application/json",
    },
  }
);

const result = await response.json();

// Get multiple fields with custom date range
const response2 = await fetch(
  "https://datafa.st/api/v1/analytics/timeseries?fields=visitors,sessions,revenue&interval=day&startAt=2024-01-01&endAt=2024-01-31&timezone=America/New_York",
  {
    method: "GET",
    headers: {
      Authorization: `Bearer ${DATAFAST_API_KEY}`,
      "Content-Type": "application/json",
    },
  }
);

const result2 = await response2.json();

// Get revenue data filtered by country and device
const response3 = await fetch(
  "https://datafa.st/api/v1/analytics/timeseries?fields=revenue&interval=day&filter_country=is:United States,Canada&filter_device=is_not:mobile&limit=30",
  {
    method: "GET",
    headers: {
      Authorization: `Bearer ${DATAFAST_API_KEY}`,
      "Content-Type": "application/json",
    },
  }
);

const result3 = await response3.json();

// Get visitors filtered by UTM campaign and referrer
const response4 = await fetch(
  "https://datafa.st/api/v1/analytics/timeseries?fields=visitors&interval=day&filter_utm_campaign=is:summer_sale&filter_referrer=is:google.com,facebook.com",
  {
    method: "GET",
    headers: {
      Authorization: `Bearer ${DATAFAST_API_KEY}`,
      "Content-Type": "application/json",
    },
  }
);

const result4 = await response4.json();

// Get sessions filtered by page path (using contains operator)
const response5 = await fetch(
  "https://datafa.st/api/v1/analytics/timeseries?fields=sessions&interval=day&filter_page=contains:/blog&limit=30",
  {
    method: "GET",
    headers: {
      Authorization: `Bearer ${DATAFAST_API_KEY}`,
      "Content-Type": "application/json",
    },
  }
);

const result5 = await response5.json();
```

### Success response (200 OK) - Multi-Field

```json
{
  "status": "success",
  "fields": [
    "visitors",
    "name",
    "sessions",
    "revenue",
    "conversion_rate"
  ],
  "interval": "day",
  "timezone": "Asia/Calcutta",
  "currency": "$",
  "totals": {
    "visitors": 14213,
    "sessions": 20181,
    "revenue": 27351,
    "revenueBreakdown": {
      "new": 22150.00,
      "renewal": 5201.00,
      "refund": 0.00
    },
    "conversion_rate": 1.92
  },
  "data": [
    {
      "visitors": 528,
      "name": "17 Dec",
      "sessions": 604,
      "revenue": 0,
      "revenueBreakdown": {
        "new": 0.00,
        "renewal": 0.00,
        "refund": 0.00
      },
      "conversion_rate": 0,
      "timestamp": "2025-12-17T00:00:00+05:30"
    },
    {
      "visitors": 472,
      "name": "18 Dec",
      "sessions": 534,
      "revenue": 468,
      "revenueBreakdown": {
        "new": 380.00,
        "renewal": 88.00,
        "refund": 0.00
      },
      "conversion_rate": 0.99,
      "timestamp": "2025-12-18T00:00:00+05:30"
    }
  ],
  "pagination": {
    "limit": 5,
    "offset": 0,
    "total": 30
  }
}
```