Retrieve a breakdown by any dimension

api-referenceGET

GEThttps://analytics.flowsery.com/analytics/api/v1/breakdown

Group visitors by any of 25 dimensions, including ones with no dedicated endpoint such as entry_page, exit_link, browser_version, os_version, via and the individual UTM parameters.

Bearer Token (workspace token or website API key)

Workspace Tokens Need a Website Selector

Workspace API tokens can access every website in the workspace. Pass either websiteId or domain so Flowsery knows which website to query or mutate. Website API keys are already scoped to one website, so the selector can be omitted.

Website Selector

Parameter	Type	Description
`websiteId`	`string`	Website ID to use with a workspace API token. Omit when authenticating with a website API key.
`domain`	`string`	Website domain to use with a workspace API token when websiteId is not provided. Omit when authenticating with a website API key.

Query Parameters

Parameter	Type	Description
`dimension`REQUIRED	`string`	The attribute to group visitors by: one of the 25 values listed under Dimensions. Any other value returns 400.
`startAt`	`string`	ISO 8601 start date/time (e.g. 2024-01-01T00:00:00Z). Defaults to the last 30 days when omitted.
`endAt`	`string`	ISO 8601 end date/time. Defaults to now when omitted.
`timezone`	`string`	Timezone for aggregation (e.g., UTC, America/New_York). Falls back to the site's configured timezone.
`limit`	`number`	Maximum rows to return (1-1000, default: 100).
`offset`	`number`	Rows to skip for pagination (min 0, default: 0).

Dimensions

Parameter	Type	Description
`device`	`string`	Device type: Desktop, Mobile or Tablet.
`page`	`string`	Page path.
`entry_page`	`string`	First page of the session.
`exit_link`	`string`	Outbound link a visitor clicked to leave the site. Revenue is always 0.
`hostname`	`string`	Hostname the page was served from.
`referrer`	`string`	Referrer source name such as Google, or the domain for sites Flowsery does not recognize. Rows include iconUrl.
`channel`	`string`	Acquisition channel, the same rows as GET /channels.
`campaign`	`string`	UTM campaign, the same rows as GET /campaigns.
`goal`	`string`	Goal name. visitors holds the completion count and revenue is always 0.
`country`	`string`	Country name. Rows include countryCode.
`region`	`string`	Region or state as a full name, such as California. Rows include countryCode.
`city`	`string`	City name. Rows include countryCode.
`browser`	`string`	Browser name.
`browser_version`	`string`	Browser version.
`os`	`string`	Operating system.
`os_version`	`string`	Operating system version.
`utm_source`	`string`	The utm_source URL parameter.
`utm_medium`	`string`	The utm_medium URL parameter.
`utm_campaign`	`string`	The utm_campaign URL parameter.
`utm_term`	`string`	The utm_term URL parameter.
`utm_content`	`string`	The utm_content URL parameter.
`ref`	`string`	The ref URL parameter.
`source`	`string`	The source URL parameter.
`via`	`string`	The via URL parameter, often used for affiliate and partner links.
`all_params`	`string`	Every tracking parameter of the session joined into one value, such as utm_source=google&utm_medium=cpc.

Filter Parameters

Parameter	Type	Description
`filter_country`	`string`	Country name as returned by /countries, e.g. United States. Use \| for several values, ! to exclude and ~ to match part of the value.
`filter_region`	`string`	Region or state name as returned by /regions, e.g. California.
`filter_city`	`string`	City name.
`filter_device`	`string`	Device type: Desktop, Mobile or Tablet. Values are case-sensitive.
`filter_browser`	`string`	Browser name. Safari includes Mobile Safari automatically.
`filter_os`	`string`	Operating system (Mac OS, Windows, iOS, Android).
`filter_referrer`	`string`	Referrer as returned by /referrers: a source name such as Google for recognized sites, otherwise the domain.
`filter_ref`	`string`	The ref URL parameter value.
`filter_source`	`string`	The source URL parameter value.
`filter_via`	`string`	The via URL parameter value.
`filter_utm_source`	`string`	UTM source.
`filter_utm_medium`	`string`	UTM medium.
`filter_utm_campaign`	`string`	UTM campaign.
`filter_utm_term`	`string`	UTM term.
`filter_utm_content`	`string`	UTM content.
`filter_page`	`string`	Page path or URL.
`filter_entry_page`	`string`	Entry page path or URL.
`filter_hostname`	`string`	Hostname/domain.
`filter_channel`	`string`	Marketing channel.
`filter_goal`	`string`	Goal name.

Response Fields

Each item in the data array contains the grouped value as value, visitor count, revenue split into newRevenue and renewalRevenue, and its share of visitors as percentage. Geographic dimensions add countryCode and referrer adds iconUrl. A value that was not captured comes back as Unknown.

Values Match the Filters

Values come back in the form the filter_* parameters expect, so any row can be sent back as a filter. Regions are full names (California, not CA), devices are capitalized (Desktop, Mobile, Tablet) and referrers are source names (Google, not google.com).

Combining Filters

Separate several values inside one filter parameter with |. Combine a dimension with filters to answer narrower questions (e.g., dimension=via&filter_country=United States&filter_device=Mobile).

Example Request (Curl)

curl --request GET \
  --url 'https://analytics.flowsery.com/analytics/api/v1/breakdown?dimension=via&limit=3' \
  --header 'Authorization: Bearer <api-key>'

200

{
  "status": "success",
  "data": [
    {
      "value": "partner_anna",
      "visitors": 640,
      "revenue": 2310,
      "newRevenue": 1980,
      "renewalRevenue": 330,
      "percentage": 51.2
    },
    {
      "value": "partner_marc",
      "visitors": 410,
      "revenue": 1270,
      "newRevenue": 1270,
      "renewalRevenue": 0,
      "percentage": 32.8
    },
    {
      "value": "podcast",
      "visitors": 200,
      "revenue": 380,
      "newRevenue": 290,
      "renewalRevenue": 90,
      "percentage": 16
    }
  ],
  "pagination": {
    "limit": 3,
    "offset": 0,
    "total": 14
  }
}