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 <code>websiteId</code> or <code>domain</code> 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 <code>data</code> array contains the grouped value as <code>value</code>, visitor count, revenue split into <code>newRevenue</code> and <code>renewalRevenue</code>, and its share of visitors as <code>percentage</code>. Geographic dimensions add <code>countryCode</code> and <code>referrer</code> adds <code>iconUrl</code>. A value that was not captured comes back as <code>Unknown</code>.

Values Match the Filters

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

Combining Filters

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

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
  }
}