DataFast logoDataFast
"Best analytics tool I've used in 14 years"

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. New/returning visitor fields use tracker session metadata collected after the rollout; old or cookieless events are not reliably classifiable.

Request

Query parameters

fields
string
required
Comma-separated response columns. Omit to return all valid fields for this endpoint. Valid: name, visitors, new_visitors, returning_visitors, visitor_breakdown, pageviews, sessions, revenue, payments, conversion_rate. Example: fields=visitors,pageviews,new_visitors,returning_visitors.
interval
string
required
Time grouping. Values: hour, day, week, month. Example: interval=day.
websiteId
string
Required with a dft_ account token on Website API routes. Omit with a df_ website key. Example: ?websiteId=665f0b3c4d2e1a0012345678.
startAt
string
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
End of the reporting window. Must be provided together with startAt. Example: endAt=2026-05-21.
timezone
string
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
Maximum rows to return. Default 100, maximum 1000 on analytics endpoints and 250 on list visitors. Example: limit=50.
offset
number
Rows to skip before returning results. Use with limit for pagination. Default 0. Example: offset=50.
filter_country
string
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
Limit results by region or state. Example: filter_region=California.
filter_city
string
Limit results by city. Example: filter_city=San Francisco.
filter_device
string
Limit results by device type: desktop, mobile, or tablet. Example: filter_device=mobile.
filter_browser
string
Limit results by browser. Filtering Safari also includes Mobile Safari. Example: filter_browser=Chrome,Safari.
filter_os
string
Limit results by operating system. Example: filter_os=iOS,Android.
filter_referrer
string
Limit results by referrer domain or normalized source such as Google or Direct/None. Example: filter_referrer=Google.
filter_page
string
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
Limit results by first page in the session. Same operators as filter_page. Example: filter_entry_page=/pricing.
filter_hostname
string
Limit results by tracked hostname. Example: filter_hostname=app.example.com.
filter_goal
string
Limit results to visitors who completed a goal. Example: filter_goal=signup.
filter_visit_count
number
Limit results by the all-time visitor session count tracked by the browser cookie. Operators: is, is_not, gte, lte. Example: filter_visit_count=gte:2 for returning visitors.
filter_utm_source
string
Limit results by UTM source. Example: filter_utm_source=google.
filter_utm_medium
string
Limit results by UTM medium. Example: filter_utm_medium=cpc.
filter_utm_campaign
string
Limit results by UTM campaign. Example: filter_utm_campaign=launch.
filter_utm_term
string
Limit results by UTM term. Example: filter_utm_term=brand-keyword.
filter_utm_content
string
Limit results by UTM content. Example: filter_utm_content=hero-cta.
filter_ref
string
Limit results by the ref URL parameter. Example: filter_ref=twitter.
filter_source
string
Limit results by the source URL parameter. Example: filter_source=newsletter.
filter_via
string
Limit results by the via URL parameter. Example: filter_via=partner.

Example query

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

Example filters

Combine filter_* query params with date ranges:
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, contains (pages only), and gte/lte for filter_visit_count. Full reference: filter your data.

Response

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

Response fields

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.
data[].timestamp
string
Event timestamp. Use it when recording historical events; defaults to the request time.
data[].name
string
Human-readable name for the resource or event. The exact meaning depends on the endpoint.
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[].new_visitors
number
New visitors in the bucket.
data[].returning_visitors
number
Returning visitors in the bucket.
data[].visitorBreakdown
object
New/returning counts and percentages for the bucket.
data[].pageviews
number
Pageviews in the bucket.
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 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 for the standard error envelope, auth failures, validation errors, permission errors, and rate limits.

✍️ Something missing? Suggest features.

🤖 AI agent or LLM? Read this page as markdown

Example request
curl -X GET "https://datafa.st/api/v1/analytics/timeseries?fields=visitors,pageviews,new_visitors,returning_visitors,sessions&interval=day&startAt=2026-05-01&endAt=2026-05-19" \
  -H "Authorization: Bearer df_xxx"
Success response
{
  "status": "success",
  "fields": ["visitors", "pageviews", "new_visitors", "returning_visitors", "sessions"],
  "interval": "day",
  "timezone": "America/New_York",
  "totals": {
    "visitors": 14213,
    "visitorBreakdown": {
      "new": 4210,
      "returning": 10003,
      "newPercentage": 29.62,
      "returningPercentage": 70.38
    },
    "new_visitors": 4210,
    "returning_visitors": 10003,
    "pageviews": 20181,
    "sessions": 20181
  },
  "data": [{
    "timestamp": "2026-05-01T00:00:00Z",
    "visitors": 528,
    "visitorBreakdown": {
      "new": 142,
      "returning": 386,
      "newPercentage": 26.89,
      "returningPercentage": 73.11
    },
    "new_visitors": 142,
    "returning_visitors": 386,
    "pageviews": 604,
    "sessions": 604
  }],
  "pagination": {
    "limit": 100,
    "offset": 0,
    "total": 19
  }
}
PreviousAPI reference / AnalyticsNextAPI reference / Overview