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

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

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

Available Filters:

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 & 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 & 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 for more details on using filters in the dashboard.

Response

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

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

{
  "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

{
  "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

Something missing? Suggest features ✍️