AppsData Clients

Working with Analyze

The Analyze API lets you read a site’s analytics through the Data API — traffic, top pages, top dimensions, top events, and time on page. Use it to build dashboards, sync metrics into other tools, or answer questions about how visitors use a site.

Every report is a read-only GET request. All reports share one filter model and report over a time window you choose.

Analyze add-on required
Analyze endpoints require an access token with the sites:read scope and a workspace that has the Analyze add-on.

Choose a report

Each report answers a different question. Pick the one that matches what you want to measure.

Traffic

A daily time series of sessions, users, or pageviews over a window.

Top pages

The most-visited pages, ranked by sessions, users, or pageviews.

Top dimensions

The top values for a dimension you choose — country, device, traffic source, and more.

Top events

The top events, ranked by how often they occurred.

Time on page

The average time spent on a page, as one value or bucketed by day or week.

Core concepts

Metric scopes

Most reports measure activity in one of three units, set with metricScope:

  • session — a single visit that groups a visitor’s activity.
  • user — a unique visitor.
  • pageview — a single page load.

Support varies by report. Traffic and Time on page take any of the three. Top dimensions takes session or user. Top pages returns all three counts per row and uses sortBy to rank them. Top events counts how many times each event occurred and does not use a metricScope.

Time windows

Pass startTime and endTime as UTC timestamps ending in Z, for example 2026-04-01T00:00:00Z. Numeric offsets such as -04:00 or +00:00 aren’t accepted.

A few rules apply to every report:

  • The window can span at most 100 days.
  • The earliest supported startTime is 2025-04-09T00:00:00Z.
  • Time series reports bucket counts by day, aligned to UTC midnight.

Filtering

Narrow any report to a subset of traffic in one of two ways:

  • Top-level query parameters — shortcuts for common dimensions, such as country, deviceType, trafficSource, and browser. For example, ?country=US&deviceType=desktop.
  • The filter parameter — the full supported set, with operators. Use bracket notation: scalars take one value (filter[country][eq]=US), and arrays use indexed brackets (filter[country][in][0]=US&filter[country][in][1]=CA). Comma-separated values aren’t supported.

Each dimension accepts eq, in, ne, or nin. Filter a given dimension in one place only — either a top-level parameter or a filter entry, not both. Using both returns 400 analyze_filter_conflict. Each report supports its own set of dimensions; see the filter parameter on the report’s reference page for the list.

Finding values to filter by
To filter by an enumerable dimension, call Top dimensions with that dimension and reuse each row’s attributeKey as the filter value. For example, dimension=browser returns Chrome, which you pass as filter[browser][eq]=Chrome or the browser=Chrome shortcut.

Rate and concurrency limits

Analyze applies two limits in addition to standard authentication:

  • Rate limit — the standard per-minute Data API rate limit, based on the site plan.
  • Concurrency limit — each access token can have one Analyze request in flight at a time, across all Analyze endpoints.

If either limit is exceeded, the request fails with 429 Too Many Requests and a Retry-After header. Serialize your Analyze calls — wait for one to finish before starting the next — and retry after the Retry-After interval.

Errors

Analyze validates each request and returns 400 Bad Request with a code that identifies the rule that failed:

CodeMeaning
time_range_too_wideThe window spans more than 100 days.
before_historical_floorstartTime is earlier than 2025-04-09T00:00:00Z.
invalid_time_rangeendTime is not greater than startTime.
analyze_input_validationA parameter value is invalid. See the message field for details.
analyze_filter_conflictA dimension was set both as a top-level parameter and inside filter.
analyze_unsupported_filterThe request used a dimension or operator the report doesn’t support.

A 403 Forbidden means the token is missing the sites:read scope, or the workspace doesn’t have the Analyze add-on.

Walkthrough: build a traffic view

Imagine you’re building a weekly traffic digest for a client — they want to know how desktop visitors from the UK engaged with their site last week. This walkthrough pulls that report step by step, starting broad and narrowing down with filters.

1

Request the traffic report

Call the Traffic report with a window, a metricScope, and a deviceType shortcut.

$curl --request GET \
>  --url 'https://api.webflow.com/beta/sites/{site_id}/analyze/reports/traffic?startTime=2026-04-01T00:00:00Z&endTime=2026-04-08T00:00:00Z&metricScope=session&deviceType=desktop' \
>  --header 'authorization: Bearer YOUR_API_TOKEN' \
>  --header 'accept: application/json'
2

Read the response

Each data point is one UTC day. The filter field in the response confirms how the report was scoped.

1{
2  "report": "traffic",
3  "metricScope": "session",
4  "window": {
5    "startTime": "2026-04-01T00:00:00Z",
6    "endTime": "2026-04-08T00:00:00Z"
7  },
8  "data": [
9    { "timestamp": "2026-04-01T00:00:00Z", "count": 1234 },
10    { "timestamp": "2026-04-02T00:00:00Z", "count": 1180 },
11    { "timestamp": "2026-04-03T00:00:00Z", "count": 1310 },
12    { "timestamp": "2026-04-04T00:00:00Z", "count": 1095 },
13    { "timestamp": "2026-04-05T00:00:00Z", "count": 742 },
14    { "timestamp": "2026-04-06T00:00:00Z", "count": 688 },
15    { "timestamp": "2026-04-07T00:00:00Z", "count": 1021 }
16  ],
17  "filter": { "deviceType": { "eq": "desktop" } }
18}
3

Narrow it further

Add another dimension to focus the view. Here, country=GB limits the report to visitors from the United Kingdom — the filter value is the ISO code (GB), not the country name.

$curl --request GET \
>  --url 'https://api.webflow.com/beta/sites/{site_id}/analyze/reports/traffic?startTime=2026-04-01T00:00:00Z&endTime=2026-04-08T00:00:00Z&metricScope=session&deviceType=desktop&country=GB' \
>  --header 'authorization: Bearer YOUR_API_TOKEN' \
>  --header 'accept: application/json'

From here, swap in another report to answer a different question — Top pages for your most-visited content, or Top dimensions to rank visitors by country, device, or traffic source.