Skip to main content
GET
Get KPIs (sessions, pageviews, bounce rate, session duration)
Returns the same KPI series that powers the Formo dashboard’s overview chart. Here sessions is the per-day session count (the overview’s Sessions card), while visitors (and visitors_current / visitors_previous) are unique anonymous visitors (the overview’s Visitors card), returned only when include_previous_period=true and no group_by is set. Use group_by to break results down by referrer, location, device, browser, os, or any UTM dimension. Set include_previous_period=true to also receive the equivalent prior window for week-over-week comparisons.

Filtering

Pass filters as a JSON-encoded array of { field, op, value } objects. Multiple filters are combined with implicit AND. For example, return KPIs only for traffic whose referrer contains google:
To filter by page path, use the page field:
page_scope=page is the default. It counts pageviews only on the filtered page and calculates bounce_rate and avg_session_sec for sessions that landed there. Use page_scope=session for the legacy behavior, which includes all activity in any session that viewed the page. The scope only changes requests that include a page filter.
Every public filter leaf uses {"field", "op", "value"}, and every collection is named filters. Query endpoints and saved segments combine their arrays with implicit AND. Profile search adds a sibling logic field, so its body is {"filters": [...], "logic": "and" | "or"}.

Authorizations

Authorization
string
header
required

Workspace API key (e.g. formo_xxx). Create one in the Formo dashboard under Team Settings > API.

Query Parameters

date_from
string<date>

Inclusive start date (YYYY-MM-DD). Defaults to 7 days before date_to.

date_to
string<date>

Inclusive end date (YYYY-MM-DD). Defaults to today.

filters
string

Array of filter conditions, JSON-encoded in the query string. Entries use { field, op, value } and are combined with implicit AND. For example, filter traffic referred by Google with [{"field":"referrer","op":"contains","value":"google"}], or filter a page with [{"field":"page","op":"eq","value":"/pricing"}]. For in / nin, pass a non-empty array value such as ["chrome","firefox"] or a pipe-delimited string such as "chrome|firefox". Array string members cannot contain a literal |, which is reserved as the Tinybird membership separator. Optional one-level nested filters use the same canonical envelope and membership rule. On the user-aggregate endpoints (lifecycle, frequency) the same array also carries profile-family entries: profile metrics (net_worth_usd, volume, revenue, points), social identity fields, a lifecycle entry ({"field":"lifecycle","op":"in","value":"New|Power user"}), and resource entries using the stable fields chains.balance, apps.balance, tokens.balance, and labels.value with named qualifier properties (chain_id, app_id, token_address, scope, tag_id). The retired per-family parameters (socials, chain_filters, app_filters, token_filters, label_filters, profile_filters, lifecycle_filter) are rejected.

page_scope
enum<string>
default:page

Controls how a page filter is interpreted. page (default) scopes metrics to activity on the filtered page. On /v0/kpis, pageviews counts only views of the filtered page, while bounce_rate and avg_session_sec are entry-page metrics for sessions that landed there. session preserves the legacy session scope: metrics include all relevant activity in any session that viewed the page. sessions and visitors are unchanged between scopes. This parameter only affects requests that include a page filter. It is distinct from /v0/top_pages mode, which selects the all, entry, or exit page-flow view.

Available options:
page,
session
group_by
enum<string>

Dimension to break down by

Available options:
referrer,
location,
device,
browser,
os,
utm_source,
utm_medium,
utm_campaign
limit
integer
include_previous_period
boolean

Return current and previous period for WoW comparison

Response

KPI time-series

Analytics endpoint response. The data array contains the rows; the exact row shape depends on the endpoint. meta carries column type information for rendering, rows is the row count, and statistics holds query timing metadata.

data
object[]
meta
object[]
rows
integer
rows_before_limit_at_least
integer
statistics
object