> ## Documentation Index > Fetch the complete documentation index at: https://help.privy.com/llms.txt > Use this file to discover all available pages before exploring further. # List flow performance > 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` ## OpenAPI ````yaml openapi/privy-api.yaml GET /reports/flows openapi: 3.1.0 info: title: Privy API version: '1.0' description: > The Privy API lets you programmatically manage your contact list and read what you have set up in Privy. Create, update, unsubscribe, and remove contacts; report orders; and read your campaigns, flows, segments, orders, store products, coupon pools, performance reports, and account setup. servers: - url: https://api.privy.com/v1 description: Production security: - bearerAuth: [] tags: - name: Account description: Retrieve information about the authenticated Privy account. - name: Contacts description: Manage your contact list. - name: Imports description: >- Read your contact import history — CSV uploads, connected-provider syncs, and SMS consent imports. - name: Campaigns description: >- Read your message campaigns — email and SMS newsletters, plus the messages your flows send. - name: Displays description: >- Read your on-site displays (popups, flyouts, banners, embedded forms, landing pages). - name: Coupons description: Read your coupon pools, their code inventory, and individual codes. - name: Reports description: >- Read performance reporting — signups, views, conversion rates, and attributed revenue — for your business, displays, and flows. - name: Flows description: Read your automation flows and their configuration. - name: Segments description: Read your customer segments and their membership. - name: Orders description: Report orders placed in your store and read your order history. - name: Products description: Read the product catalog and collections of your connected store. - name: Events description: Ingest custom events to trigger Flows and other automations. paths: /reports/flows: get: tags: - Reports summary: List flow performance description: | 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` operationId: listFlowReports parameters: - $ref: '#/components/parameters/AccountIdParam' - $ref: '#/components/parameters/ReportPeriodParam' - $ref: '#/components/parameters/ReportStartDateParam' - $ref: '#/components/parameters/ReportEndDateParam' - name: status in: query description: Only include flows with this status. Any other value is rejected. schema: type: string enum: - draft - active - inactive example: active - $ref: '#/components/parameters/PageParam' - name: per_page in: query description: >- Flows per page. Values above 25 are clamped to 25; omitted or invalid values default to 10. schema: type: integer default: 10 minimum: 1 maximum: 25 example: 10 responses: '200': description: Flows ranked by performance over the resolved period. content: application/json: schema: type: object properties: data: type: array items: $ref: '#/components/schemas/FlowReportRow' period: $ref: '#/components/schemas/ReportPeriod' pagination: $ref: '#/components/schemas/PaginationEnvelope' example: data: - flow_id: Vq7L3mN9xR title: Abandoned Cart Recovery status: active trigger_type: cart_abandoned channels: multi current_enrollment: value: 86 unit: count stats: sent: value: 5200 unit: count delivered: value: 5050 unit: count opened: value: 2210 unit: count clicked: value: 640 unit: count open_rate: value: 51.4 unit: percent click_rate: value: 12.7 unit: percent attributed_orders: value: 210 unit: count attributed_revenue: value: 9640.5 unit: usd order_rate: value: 4.2 unit: percent average_order_value: value: 45.91 unit: usd unsubscribed: value: 34 unit: count bounced: value: 61 unit: count sms_opted_out: value: 12 unit: count sms_failed: value: 9 unit: count period: label: last_30_days start_date: '2026-06-21' end_date: '2026-07-20' pagination: page: 1 per_page: 10 total_count: 4 total_pages: 1 '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/InsufficientScope' '422': $ref: '#/components/responses/ValidationFailed' '429': $ref: '#/components/responses/RateLimited' security: - bearerAuth: [] components: parameters: AccountIdParam: name: Privy-Account-Id in: header required: false description: > Target a subaccount instead of the main connected account. Pass a subaccount `id` from get_account's `subaccounts` list. Only direct subaccounts of the connected account are reachable — omit this for the main account itself. schema: type: string example: S1U2B3A4C5C6T7 ReportPeriodParam: name: period in: query description: >- The date range to report over, resolved in the account's time zone. Pass `custom` together with `start_date` and `end_date`. schema: type: string enum: - last_7_days - last_30_days - last_90_days - this_month - last_month - custom default: last_30_days example: last_30_days ReportStartDateParam: name: start_date in: query description: >- Inclusive start of a `custom` period (ISO 8601 date). Required when `period=custom`, ignored otherwise. schema: type: string format: date example: '2026-06-01' ReportEndDateParam: name: end_date in: query description: >- Inclusive end of a `custom` period (ISO 8601 date). Required when `period=custom`, ignored otherwise. Custom periods are capped at 366 days. schema: type: string format: date example: '2026-06-30' PageParam: name: page in: query description: Page number (starts at 1). schema: type: integer default: 1 minimum: 1 example: 1 schemas: FlowReportRow: type: object properties: flow_id: type: string description: >- The flow's unique identifier. Use this value in `/v1/reports/flows/{flow_id}` and `/v1/flows/{id}`. example: Vq7L3mN9xR title: type: - string - 'null' example: Abandoned Cart Recovery status: type: string enum: - draft - active - inactive example: active trigger_type: type: - string - 'null' description: >- 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. example: cart_abandoned trigger_label: type: - string - 'null' description: Human-readable form of `trigger_type`. example: Cart abandoned channels: type: - string - 'null' enum: - email - sms - multi - null description: >- Message channels the flow sends on. `null` when the flow has no message nodes. example: multi current_enrollment: allOf: - $ref: '#/components/schemas/ReportMetric' description: > Contacts with a journey in progress right now — a point-in-time count, not scoped to the report period, and at most one journey per contact. stats: $ref: '#/components/schemas/FlowReportStats' ReportPeriod: type: object description: | 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. properties: label: type: string enum: - last_7_days - last_30_days - last_90_days - this_month - last_month - custom example: last_30_days start_date: type: string format: date example: '2026-06-21' end_date: type: string format: date example: '2026-07-20' PaginationEnvelope: type: object properties: page: type: integer example: 1 per_page: type: integer example: 25 total_count: type: integer example: 142 total_pages: type: integer example: 6 ReportMetric: type: object description: | 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. properties: value: type: number example: 42 unit: type: string description: '`count`, `percent`, or a lowercased ISO 4217 currency code.' example: count FlowReportStats: type: object description: > 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. properties: sent: $ref: '#/components/schemas/ReportMetric' delivered: $ref: '#/components/schemas/ReportMetric' opened: $ref: '#/components/schemas/ReportMetric' clicked: $ref: '#/components/schemas/ReportMetric' open_rate: $ref: '#/components/schemas/ReportMetric' click_rate: $ref: '#/components/schemas/ReportMetric' attributed_orders: $ref: '#/components/schemas/ReportMetric' attributed_revenue: $ref: '#/components/schemas/ReportMetric' order_rate: $ref: '#/components/schemas/ReportMetric' average_order_value: $ref: '#/components/schemas/ReportMetric' unsubscribed: $ref: '#/components/schemas/ReportMetric' bounced: $ref: '#/components/schemas/ReportMetric' sms_opted_out: $ref: '#/components/schemas/ReportMetric' sms_failed: $ref: '#/components/schemas/ReportMetric' ErrorResponse: type: object properties: error: type: object required: - code - message properties: code: type: string enum: - invalid_client - invalid_scope - unauthorized - insufficient_scope - paid_plan_required - api_access_required - not_found - no_connected_store - conflict - contacts_not_ready - validation_failed - rate_limited - store_unavailable example: validation_failed message: type: string example: One or more fields are invalid details: type: array items: type: object properties: field: type: string example: email message: type: string example: is required responses: Unauthorized: description: Missing or invalid bearer token. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: error: code: unauthorized message: Bearer token is missing or invalid InsufficientScope: description: Token lacks the required scope for this endpoint. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: error: code: insufficient_scope message: Token does not have the required scope ValidationFailed: description: One or more fields failed validation. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: error: code: validation_failed message: One or more fields are invalid details: - field: email message: is required RateLimited: description: Rate limit exceeded. Retry after the specified time. headers: Retry-After: description: Seconds to wait before retrying. schema: type: integer example: 42 X-RateLimit-Limit-Minute: description: Maximum requests allowed per minute. schema: type: integer example: 60 X-RateLimit-Remaining-Minute: description: Requests remaining in the current minute window. schema: type: integer example: 0 X-RateLimit-Reset-Minute: description: Unix timestamp when the minute window resets. schema: type: integer example: 1711929600 X-RateLimit-Limit-Day: description: Maximum requests allowed per day. schema: type: integer example: 10000 X-RateLimit-Remaining-Day: description: Requests remaining in the current day window. schema: type: integer example: 9500 X-RateLimit-Reset-Day: description: Unix timestamp when the day window resets. schema: type: integer example: 1712016000 content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: error: code: rate_limited message: Rate limit exceeded securitySchemes: bearerAuth: type: http scheme: bearer bearerFormat: API token or OAuth access token description: > Send either an API token or an OAuth access token as `Authorization: Bearer `. See the Authentication page for details. ````