> ## 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.

# Get flow performance

> One flow's performance over a period: the combined email + SMS stat
set plus a per-node breakdown of each email and SMS message step.

Configuration — trigger, filters, re-entry behavior, branch graph — is
`/v1/flows/{id}`. The per-node `uuid`s match that response's node `uuid`s,
which is how a message step is placed in the flow graph; a step the flow
no longer contains has no counterpart there.

**Required scope:** `reports_read`




## OpenAPI

````yaml openapi/privy-api.yaml GET /reports/flows/{flow_id}
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/{flow_id}:
    get:
      tags:
        - Reports
      summary: Get flow performance
      description: >
        One flow's performance over a period: the combined email + SMS stat

        set plus a per-node breakdown of each email and SMS message step.


        Configuration — trigger, filters, re-entry behavior, branch graph — is

        `/v1/flows/{id}`. The per-node `uuid`s match that response's node
        `uuid`s,

        which is how a message step is placed in the flow graph; a step the flow

        no longer contains has no counterpart there.


        **Required scope:** `reports_read`
      operationId: getFlowReport
      parameters:
        - $ref: '#/components/parameters/AccountIdParam'
        - name: flow_id
          in: path
          required: true
          description: >-
            The flow's unique identifier (returned as `flow_id` in report
            responses and `id` in flow responses). Ids are opaque public strings
            — a numeric id from a Privy dashboard URL is not a valid API id and
            will 404; list flows and match by title instead.
          schema:
            type: string
          example: Vq7L3mN9xR
        - $ref: '#/components/parameters/ReportPeriodParam'
        - $ref: '#/components/parameters/ReportStartDateParam'
        - $ref: '#/components/parameters/ReportEndDateParam'
      responses:
        '200':
          description: The flow's performance over the resolved period.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    $ref: '#/components/schemas/FlowReportDetail'
              example:
                data:
                  flow_id: Vq7L3mN9xR
                  title: Abandoned Cart Recovery
                  status: active
                  trigger_type: cart_abandoned
                  channels: multi
                  current_enrollment:
                    value: 86
                    unit: count
                  period:
                    label: last_30_days
                    start_date: '2026-06-21'
                    end_date: '2026-07-20'
                  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
                  nodes:
                    - uuid: 7a2f9e1b-5c3d-4d2e-8b4f-3a6c8d9e0f1a
                      type: email
                      name: Cart reminder email
                      subject: You left something behind
                      stats:
                        sent:
                          value: 2600
                          unit: count
                        delivered:
                          value: 2540
                          unit: count
                        opened_unique:
                          value: 1180
                          unit: count
                        clicked_unique:
                          value: 340
                          unit: count
                        bounced:
                          value: 38
                          unit: count
                        unsubscribed:
                          value: 21
                          unit: count
                        attributed_orders:
                          value: 120
                          unit: count
                        attributed_revenue:
                          value: 5610.25
                          unit: usd
                    - uuid: 8b3a0f2c-6d4e-4e3f-9c5a-4b7d9e0f1a2b
                      type: sms
                      name: Cart reminder text
                      stats:
                        sent:
                          value: 780
                          unit: count
                        delivered:
                          value: 762
                          unit: count
                        clicked_unique:
                          value: 96
                          unit: count
                        opted_out:
                          value: 7
                          unit: count
                        failed:
                          value: 18
                          unit: count
                        attributed_orders:
                          value: 41
                          unit: count
                        attributed_revenue:
                          value: 1890
                          unit: usd
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/InsufficientScope'
        '404':
          $ref: '#/components/responses/NotFound'
        '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'
  schemas:
    FlowReportDetail:
      allOf:
        - $ref: '#/components/schemas/FlowReportRow'
        - type: object
          properties:
            period:
              $ref: '#/components/schemas/ReportPeriod'
            nodes:
              type: array
              description: Per-node breakdown of the flow's email and SMS message steps.
              items:
                $ref: '#/components/schemas/FlowReportNode'
    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'
    FlowReportNode:
      type: object
      properties:
        uuid:
          type: string
          example: 7a2f9e1b-5c3d-4d2e-8b4f-3a6c8d9e0f1a
        type:
          type: string
          enum:
            - email
            - sms
          example: email
        name:
          type:
            - string
            - 'null'
          example: Cart reminder email
        subject:
          type:
            - string
            - 'null'
          description: The email's subject line. Present on email nodes only.
          example: You left something behind
        stats:
          $ref: '#/components/schemas/FlowReportNodeStats'
    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
    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'
    FlowReportNodeStats:
      type: object
      description: >
        Per-node deliverability and attribution metrics for one message step
        over

        the report period. Email nodes carry `opened_unique`, `bounced`, and

        `unsubscribed`; `sms` nodes carry `opted_out` and `failed`; both carry
        the

        rest. `opened_unique` and `clicked_unique` count contacts who opened or

        clicked at least once, not total opens or clicks. `attributed_orders`
        and

        `attributed_revenue` credit this node's message under the same
        last-touch,

        7-day rule as the flow total.
      properties:
        sent:
          $ref: '#/components/schemas/ReportMetric'
        delivered:
          $ref: '#/components/schemas/ReportMetric'
        opened_unique:
          $ref: '#/components/schemas/ReportMetric'
        clicked_unique:
          $ref: '#/components/schemas/ReportMetric'
        bounced:
          $ref: '#/components/schemas/ReportMetric'
        unsubscribed:
          $ref: '#/components/schemas/ReportMetric'
        opted_out:
          $ref: '#/components/schemas/ReportMetric'
        failed:
          $ref: '#/components/schemas/ReportMetric'
        attributed_orders:
          $ref: '#/components/schemas/ReportMetric'
        attributed_revenue:
          $ref: '#/components/schemas/ReportMetric'
  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
    NotFound:
      description: >-
        The requested resource does not exist or does not belong to your
        account.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          example:
            error:
              code: not_found
              message: Not found
    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 <token>`. See the Authentication page for
        details.

````