Flow reports

Flows are the branching journeys you build in the dashboard. The Product API does not build them — it exposes them read-only, so an integration can find a flow, enumerate its versions, and report on how it is performing. This page covers both halves: the discovery endpoints that hand you the ids, and the flow report that turns them into numbers.

Everything on this page is governed by a single scope, PROJECT_AUTOMATION_READ.

Finding a flow

The list endpoint is the entry point: it returns the flows of a project, newest first, and the id it gives you is exactly the value the report endpoint takes.

The listing accepts the standard Query Filter syntax for filtering, sorting and pagination, so you can narrow it to the flows you care about:

GET /project/{project}/flow
  ?status_eq=enabled

Versions

A flow evolves through versions, and the versions endpoint is where you find the ids the report scopes to. It returns every version of the flow, newest first, archived ones included.

Two fields carry the meaning:

• status is the version's role, and it is permanent for the version's life. A version never changes role: promoting a test version to production produces a new version with its own id rather than rewriting the old one. So a version id is also a stable label for the cohort its traffic belongs to.
• sequence is the permanent version number — v1, v2, v3 — assigned when a version first goes live. A 0 means unnumbered: a draft or a manual preview that has never gone live.

Manual previews never send to your audience, so draft and test versions produce no analytics traffic. The reports only ever carry data for live and live-test versions.

The flow report

One report covers flows: a series — the statistics you ask for, bucketed over time.

It follows the same grammar as every other family (Building queries) and returns the same series shape (Reading results). The specifics:

GET /project/{project}/analytics/flow/{flow}/series
  ?statistics=delivered,clicks_first,conversions,conversion_value
  &timeframe=last_30_days
  &interval=day

group_by=channel gives you the per-leg series of a fallback chain, and pairing one group_by with a filter on another dimension cross-cuts the report the same way it does elsewhere — filter[country]=ES with group_by=channel, for example.

Timeframe and freshness

A flow report is always computed on demand — its freshness.source is live, with no cached value to age.

The window is clamped to the flow's own lifetime: from the day the flow was created to the day it was archived. An active flow (no archivedAt) is served exactly as you asked for it. When the clamp trims your window, the response carries a timeframe_clamped_to_entity_lifetime warning and echoes the window it actually used.

Totals versus one version

filter[version] is the parameter flows have and no other family does, and it changes what the whole report means.

Without filter[version], the report is the flow total across every version — the live version and the live-test cohort added together. That is the honest business number: the A/B cohort is real traffic to real contacts, with real deliveries, real clicks and real revenue, so leaving it out would under-report what the flow actually did.

With filter[version]=<versionId>, every statistic is scoped to that single version. Not just the delivery figures: clicks, conversions and revenue are scoped too, because attribution keeps the version alongside the flow on the events it credits. That is what makes the parameter useful — it is how you judge a test version on its own merits before deciding whether to promote it.

GET /project/{project}/analytics/flow/{flow}/series
  ?statistics=delivered,click_rate,conversions,conversion_value,roas
  &timeframe=last_30_days
  &filter[version]=66b1f2a4e5a6b7c8d9e0f1b3

Comparing two versions

There is no group_by=version and no compare endpoint for flows. You compare by issuing the same request twice, changing only the version id:

1. 1

   List the flow's versions

   Call GET /project/{project}/flow/{id}/versions and pick the live version and the live-test version.

2. 2

   Report on each one

   Issue two identical series requests — same statistics, same timeframe, same interval — differing only in filter[version].

3. 3

   Compare like for like

   Read the rates rather than the raw counts. The A/B cohort runs on a small share of the audience, so its volumes are smaller by design; click_rate, conversion_rate and roas are what put the two versions on the same footing.

4. 4

   Optionally, take the total

   The same request with no filter[version] gives you the flow as a whole, both cohorts included — the number to report to the business.

Next