---
title: "List flow performance"
method: GET
path: "/reports/flows"
tags: ["Reports"]
---

# List flow performance

`GET /reports/flows`

## Request

- Base URL: `https://api.privy.com/v1`
- URL: `https://api.privy.com/v1/reports/flows`
- Auth: HTTP bearer

Rank your flows by performance over a period — best performers first,
remaining flows by recency. Each row combines email and SMS stats
across the flow's message steps. Use `/v1/reports/flows/{flow_id}`
for one flow's report including the per-node message breakdown.

Every flow with the requested status is listed, quiet ones included —
unlike the display and campaign leaderboards nothing is dropped for
having no activity, so this doubles as a performance-annotated flow
inventory. A flow's configuration is `/v1/flows/{id}`.

**Required scope:** `reports_read`

## Query parameters

- `period` 'last_7_days' | 'last_30_days' | 'last_90_days' | 'this_month' | 'last_month' | 'custom'
- `start_date` string, date
- `end_date` string, date
- `status` 'draft' | 'active' | 'inactive'
- `page` integer
- `per_page` integer

## Headers

- `Privy-Account-Id` string

## Response `200`

Flows ranked by performance over the resolved period.

- object
  - `data` FlowReportRow[]
    - `flow_id` string: The flow's unique identifier. Use this value in `/v1/reports/flows/{flow_id}` and `/v1/flows/{id}`.
    - `title` string, nullable
    - `status` 'draft' | 'active' | 'inactive'
    - `trigger_type` string, nullable: Normalized name of the event that starts the flow (e.g. `order_placed`, `cart_abandoned`, `customer_subscribed_to_marketing`) — the same vocabulary `GET /v1/flows` returns.
    - `trigger_label` string, nullable: Human-readable form of `trigger_type`.
    - `channels` 'email' | 'sms' | 'multi' | 'null', nullable: Message channels the flow sends on. `null` when the flow has no message nodes.
    - `current_enrollment` ReportMetric: A single report metric with its unit. `count` values are whole numbers, `percent` values are 0–100 with one decimal. Money metrics carry the account's lowercased ISO 4217 currency code as their unit (e.g. `usd`, `eur`, `jpy`) and are expressed in that currency's major units, two decimals. A rate whose denominator was zero reports 0, not null — so 0 does not distinguish "no activity" from "activity that never converted"; read the underlying counts to tell those apart.
      - `value` number
      - `unit` string: `count`, `percent`, or a lowercased ISO 4217 currency code.
    - `stats` FlowReportStats: Combined email + SMS performance for one flow over the report period, summed across the flow's message nodes. `sent` counts send attempts and `delivered` counts provider-confirmed deliveries — separate counters, neither derived from the other. `opened` and `clicked` are unique counts (contacts who opened or clicked at least once within the report period), not totals of every event. `open_rate` is `opened` over email deliveries only, since opens do not exist for SMS; `click_rate` and `order_rate` are over email and SMS deliveries combined. `attributed_orders` and `attributed_revenue` credit the flow when one of its messages was the contact's most recent engagement — email open, email click, or SMS click — in the 7 days before the order was placed: last-touch attribution, where that single most recent engagement takes the whole order.
      - `sent` ReportMetric: A single report metric with its unit. `count` values are whole numbers, `percent` values are 0–100 with one decimal. Money metrics carry the account's lowercased ISO 4217 currency code as their unit (e.g. `usd`, `eur`, `jpy`) and are expressed in that currency's major units, two decimals. A rate whose denominator was zero reports 0, not null — so 0 does not distinguish "no activity" from "activity that never converted"; read the underlying counts to tell those apart.
        - `value` number
        - `unit` string: `count`, `percent`, or a lowercased ISO 4217 currency code.
      - `delivered` ReportMetric: A single report metric with its unit. `count` values are whole numbers, `percent` values are 0–100 with one decimal. Money metrics carry the account's lowercased ISO 4217 currency code as their unit (e.g. `usd`, `eur`, `jpy`) and are expressed in that currency's major units, two decimals. A rate whose denominator was zero reports 0, not null — so 0 does not distinguish "no activity" from "activity that never converted"; read the underlying counts to tell those apart.
        - `value` number
        - `unit` string: `count`, `percent`, or a lowercased ISO 4217 currency code.
      - `opened` ReportMetric: A single report metric with its unit. `count` values are whole numbers, `percent` values are 0–100 with one decimal. Money metrics carry the account's lowercased ISO 4217 currency code as their unit (e.g. `usd`, `eur`, `jpy`) and are expressed in that currency's major units, two decimals. A rate whose denominator was zero reports 0, not null — so 0 does not distinguish "no activity" from "activity that never converted"; read the underlying counts to tell those apart.
        - `value` number
        - `unit` string: `count`, `percent`, or a lowercased ISO 4217 currency code.
      - `clicked` ReportMetric: A single report metric with its unit. `count` values are whole numbers, `percent` values are 0–100 with one decimal. Money metrics carry the account's lowercased ISO 4217 currency code as their unit (e.g. `usd`, `eur`, `jpy`) and are expressed in that currency's major units, two decimals. A rate whose denominator was zero reports 0, not null — so 0 does not distinguish "no activity" from "activity that never converted"; read the underlying counts to tell those apart.
        - `value` number
        - `unit` string: `count`, `percent`, or a lowercased ISO 4217 currency code.
      - `open_rate` ReportMetric: A single report metric with its unit. `count` values are whole numbers, `percent` values are 0–100 with one decimal. Money metrics carry the account's lowercased ISO 4217 currency code as their unit (e.g. `usd`, `eur`, `jpy`) and are expressed in that currency's major units, two decimals. A rate whose denominator was zero reports 0, not null — so 0 does not distinguish "no activity" from "activity that never converted"; read the underlying counts to tell those apart.
        - `value` number
        - `unit` string: `count`, `percent`, or a lowercased ISO 4217 currency code.
      - `click_rate` ReportMetric: A single report metric with its unit. `count` values are whole numbers, `percent` values are 0–100 with one decimal. Money metrics carry the account's lowercased ISO 4217 currency code as their unit (e.g. `usd`, `eur`, `jpy`) and are expressed in that currency's major units, two decimals. A rate whose denominator was zero reports 0, not null — so 0 does not distinguish "no activity" from "activity that never converted"; read the underlying counts to tell those apart.
        - `value` number
        - `unit` string: `count`, `percent`, or a lowercased ISO 4217 currency code.
      - `attributed_orders` ReportMetric: A single report metric with its unit. `count` values are whole numbers, `percent` values are 0–100 with one decimal. Money metrics carry the account's lowercased ISO 4217 currency code as their unit (e.g. `usd`, `eur`, `jpy`) and are expressed in that currency's major units, two decimals. A rate whose denominator was zero reports 0, not null — so 0 does not distinguish "no activity" from "activity that never converted"; read the underlying counts to tell those apart.
        - `value` number
        - `unit` string: `count`, `percent`, or a lowercased ISO 4217 currency code.
      - `attributed_revenue` ReportMetric: A single report metric with its unit. `count` values are whole numbers, `percent` values are 0–100 with one decimal. Money metrics carry the account's lowercased ISO 4217 currency code as their unit (e.g. `usd`, `eur`, `jpy`) and are expressed in that currency's major units, two decimals. A rate whose denominator was zero reports 0, not null — so 0 does not distinguish "no activity" from "activity that never converted"; read the underlying counts to tell those apart.
        - `value` number
        - `unit` string: `count`, `percent`, or a lowercased ISO 4217 currency code.
      - `order_rate` ReportMetric: A single report metric with its unit. `count` values are whole numbers, `percent` values are 0–100 with one decimal. Money metrics carry the account's lowercased ISO 4217 currency code as their unit (e.g. `usd`, `eur`, `jpy`) and are expressed in that currency's major units, two decimals. A rate whose denominator was zero reports 0, not null — so 0 does not distinguish "no activity" from "activity that never converted"; read the underlying counts to tell those apart.
        - `value` number
        - `unit` string: `count`, `percent`, or a lowercased ISO 4217 currency code.
      - `average_order_value` ReportMetric: A single report metric with its unit. `count` values are whole numbers, `percent` values are 0–100 with one decimal. Money metrics carry the account's lowercased ISO 4217 currency code as their unit (e.g. `usd`, `eur`, `jpy`) and are expressed in that currency's major units, two decimals. A rate whose denominator was zero reports 0, not null — so 0 does not distinguish "no activity" from "activity that never converted"; read the underlying counts to tell those apart.
        - `value` number
        - `unit` string: `count`, `percent`, or a lowercased ISO 4217 currency code.
      - `unsubscribed` ReportMetric: A single report metric with its unit. `count` values are whole numbers, `percent` values are 0–100 with one decimal. Money metrics carry the account's lowercased ISO 4217 currency code as their unit (e.g. `usd`, `eur`, `jpy`) and are expressed in that currency's major units, two decimals. A rate whose denominator was zero reports 0, not null — so 0 does not distinguish "no activity" from "activity that never converted"; read the underlying counts to tell those apart.
        - `value` number
        - `unit` string: `count`, `percent`, or a lowercased ISO 4217 currency code.
      - `bounced` ReportMetric: A single report metric with its unit. `count` values are whole numbers, `percent` values are 0–100 with one decimal. Money metrics carry the account's lowercased ISO 4217 currency code as their unit (e.g. `usd`, `eur`, `jpy`) and are expressed in that currency's major units, two decimals. A rate whose denominator was zero reports 0, not null — so 0 does not distinguish "no activity" from "activity that never converted"; read the underlying counts to tell those apart.
        - `value` number
        - `unit` string: `count`, `percent`, or a lowercased ISO 4217 currency code.
      - `sms_opted_out` ReportMetric: A single report metric with its unit. `count` values are whole numbers, `percent` values are 0–100 with one decimal. Money metrics carry the account's lowercased ISO 4217 currency code as their unit (e.g. `usd`, `eur`, `jpy`) and are expressed in that currency's major units, two decimals. A rate whose denominator was zero reports 0, not null — so 0 does not distinguish "no activity" from "activity that never converted"; read the underlying counts to tell those apart.
        - `value` number
        - `unit` string: `count`, `percent`, or a lowercased ISO 4217 currency code.
      - `sms_failed` ReportMetric: A single report metric with its unit. `count` values are whole numbers, `percent` values are 0–100 with one decimal. Money metrics carry the account's lowercased ISO 4217 currency code as their unit (e.g. `usd`, `eur`, `jpy`) and are expressed in that currency's major units, two decimals. A rate whose denominator was zero reports 0, not null — so 0 does not distinguish "no activity" from "activity that never converted"; read the underlying counts to tell those apart.
        - `value` number
        - `unit` string: `count`, `percent`, or a lowercased ISO 4217 currency code.
  - `period` ReportPeriod: The resolved date range the report covers, inclusive, in the account's time zone. Every label except `last_month` ends today, so the last day of the range is still in progress: `last_7_days` is the six days before today plus today, `this_month` runs from the 1st through today, and `last_month` is the whole previous calendar month. Custom ranges cannot exceed 366 days.
    - `label` 'last_7_days' | 'last_30_days' | 'last_90_days' | 'this_month' | 'last_month' | 'custom'
    - `start_date` string, date
    - `end_date` string, date
  - `pagination` PaginationEnvelope
    - `page` integer
    - `per_page` integer
    - `total_count` integer
    - `total_pages` integer

## Other responses

- `401`: Missing or invalid bearer token.
- `403`: `insufficient_scope` when the token lacks the required scope for this endpoint.
- `422`: One or more fields failed validation.
- `429`: Rate limit exceeded. Retry after the specified time.

## Changes

- **2026-11-05** `cf0885e90d5a`: 8 warning
  - added the new `forbidden` enum value to the `error/code` response property for the response status `401`
  - added the new `forbidden` enum value to the `error/code` response property for the response status `403`
  - added the new `forbidden` enum value to the `error/code` response property for the response status `422`
  - added the new `forbidden` enum value to the `error/code` response property for the response status `429`
  - …4 more
- **2026-11-03** `fe500ab59b3b`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/privy/apis/privy-api/changes/reports/flows/get.md)

---

[API](https://skmtc.dev/privy/apis/privy-api.md) - [All operations](https://skmtc.dev/privy/apis/privy-api/llms.txt) - [OpenAPI document](https://skmtc.dev/privy/apis/privy-api/revisions/bc29b48dcdd2?raw)