HomeGuidesAPI Reference
ChangelogHelp CenterCommunityContact Us
Guides
ChangelogHelp CenterCommunityContact Us

Get performance data for flows triggered by your app metrics

Learn how to get flow-specific performance data related to an app metric.

Before you begin

Note that in order to fetch performance data for flows that use your app metrics, your app must request the following scopes from users:

  • metrics:read
  • flows:read

You will learn

In this guide, you will learn how to get performance data for flows that have been triggered by your app metrics, or metrics created by your app through OAuth. For example, a customer may be using one of your app’s provided flow templates. In this case, you may want to use our Reporting API to monitor how this flow template is performing for the customer. This is an effective way to enable data-driven improvements to your app.

Get flows triggered by your metric

To retrieve flow-specific performance data at the account level, we first need to identify which flows are triggered by your app’s metrics within the account. Follow the steps below:

  1. Using the stored access token for the account, make a request to Get Metrics with a filter to fetch app metrics specific to your integration. In the example below, the filter uses the integration name, but you can also fetch metrics by integration category.
curl --request GET \
     --url https://a.klaviyo.com/api/metrics/?filter=equals(integration.name,"YourIntegration")&fields[metric]=name,integration.id,integration.name \
     --header 'Authorization: Bearer {access_token}' \
     --header 'accept: application/json' \
     --header 'revision: 2024-10-15'

{
    "data": [
        {
            "type": "metric",
            "id": "REcTBe",
            "attributes": {
                "name": "YourIntegration: Sent SMS",
                "integration": {
                    "id": "0rG4eQ",
                    "name": "YourIntegration"
                }
            },
            "links": {
                "self": "https://a.klaviyo.com/api/metrics/REcTBe/"
            }
        },
        {
            "type": "metric",
            "id": "RcsmFp",
            "attributes": {
                "name": "YourIntegration: Marked Email as Spam",
                "integration": {
                    "id": "0rG4eQ",
                    "name": "YourIntegration"
                }
            },
            "links": {
                "self": "https://a.klaviyo.com/api/metrics/RcsmFp/"
            }
        },
    ...
}

🚧

Filtering by integration.name and/or integration.category is case-sensitive. The integration.name should match your app’s brand name.

  1. Of the returned metrics, copy the metric ID(s) that you would like to use to fetch related flows.
  2. Call Get IDs for Flows Triggered by Metric with the metric ID to fetch IDs for flows triggered by the app metric. The request and response should look like this:
curl --request GET \
     --url https://a.klaviyo.com/api/metrics/REcTBe/relationships/flow-triggers \
     --header 'Authorization: Bearer {access_token}' \
     --header 'accept: application/json' \
     --header 'revision: 2024-10-15'

{
  "data": [
    {
      "type": "flow",
      "id": "T7K2j8"
    }
  ]
}

Fetch flow-specific performance data

Now that we have an ID for a flow that has been triggered by a specified app metric, we can fetch the performance data on this flow. There are two types of flow reports that you can run:

  • Flow values report (Query Flow Values)

    Returns requested statistics for a given flow over a provided time frame. For example, unique opens for a flow email over the last 12 months.

  • Flow series report (Query Flow Series).

    Returns requested flow statistics broken down by a specified time interval over a provided time frame. For example, weekly click rates for a flow email over the last 30 days.

In your request to Query Flow Values or Query Flow Series for performance data on a specific flow:

  1. Input the app metric ID as the conversion_metric_id. This will be used for calculating conversion-based statistics.
  2. Use an equals filter on the flow ID of the flow you want performance data on. For example, "equals(flow_id,\"T7K2j8\")".

The example request below uses the Query Flow Values endpoint to query statistics (clicks, unique clicks, and unique conversions) over a custom time frame:

curl --request POST \
     --url https://a.klaviyo.com/api/flow-values-reports/ \
     --header 'Authorization: Bearer {access_token}' \
     --header 'accept: application/json' \
     --header 'content-type: application/json' \
     --header 'revision: 2024-10-15 \
     --data '
{
  "data": {
    "type": "flow-values-report",
    "attributes": {
      "timeframe": {
        "start": "2024-05-08T00:00:00+00:00",
        "end": "2024-06-20T00:00:00+00:00"

      },
      "conversion_metric_id": "REcTBe",
      "filter":"equals(flow_id,\"T7K2j8\")",
      "statistics": [
        "clicks",
        "clicks_unique",
        "conversion_uniques"
      ]
    }
  }
}
'

{
  "data": {
    "type": "flow-values-report",
    "attributes": {
      "results": [
        {
          "groupings": {
            "flow_id": "T7K2j8",
            "send_channel": "email",
            "flow_message_id": "01GMRWDSA0ARTAKE1SFX8JGXAY"
          },
          "statistics": {
            "clicks": 123,
            "clicks_unique": 98,
            "conversion_uniques": 3
          }
        },
        {
          "groupings": {
            "flow_id": "T7K2j8",
            "send_channel": "email",
            "flow_message_id": "01GJTHNWVG93F3KNX71SJ4FDBB"
          },
          "statistics": {
            "clicks": 342,
            "clicks_unique": 208,
            "conversion_uniques": 10
          }
        }
      ]
    },
    "relationships": {
      "flows": {
        "data": [
          {
            "type": "flow",
            "id": "string"
          }
        ],
        "links": {
          "self": "string",
          "related": "string"
        }
      },
      "flow-messages": {
        "data": [
          {
            "type": "flow-message",
            "id": "string"
          }
        ],
        "links": {
          "self": "string",
          "related": "string"
        }
      }
    },
    "links": {
      "self": "string"
    }
  }
}

The example request below uses the Query Flow Series endpoint to query statistics for clicks, delivery rate, and open rate on a weekly interval over the last 30 days:

curl --request POST \
     --url https://a.klaviyo.com/api/flow-series-reports/ \
     --header 'Authorization: Bearer {access_token}' \
     --header 'accept: application/json' \
     --header 'content-type: application/json' \
     --header 'revision: 2024-10-15 \
     --data '
{
  "data": {
    "type": "flow-series-report",
    "attributes": {
      "timeframe": {
        "key": "last_30_days"
      },
      "interval": "weekly",
      "conversion_metric_id": "REcTBe",
      "filter": "equals(flow_id,\"T7K2j8\")",
      "statistics": [
        "clicks",
        "delivery_rate",
        "open_rate"
      ]
    }
  }
}
'

{
  "data": {
    "type": "flow-series-report",
    "attributes": {
      "results": [
        {
          "groupings": {
            "flow_id": "T7K2j8",
            "send_channel": "email",
            "flow_message_id": "01GMRWDSA0ARTAKE1SFX8JGXAY"
          },
          "statistics": {
            "clicks": [
              123,
              156,
              144
            ],
      "delivery_rate": [
              1.00,
              0.56,
              0.84
            ],
            "open_rate": [
              0.8253,
              0.8722,
              0.8398
            ]
          }
        },
        {
          "groupings": {
            "flow_id": "T7K2j8",
            "send_channel": "email",
            "flow_message_id": "01GJTHNWVG93F3KNX71SJ4FDBB"
          },
          "statistics": {
             "clicks": [
              123,
              156,
              144
            ],
      "delivery_rate": [
              1.00,
              0.56,
              0.84
            ],
            "open_rate": [
              0.8253,
              0.8722,
              0.8398
            ]
          }
        }
      ],
      "date_times": [
        "2024-01-05T00:00:00+00:00",
        "2024-01-06T00:00:00+00:00",
        "2024-01-07T00:00:00+00:00"
      ]
    },
    "relationships": {
      "flows": {
        "data": [
          {
            "type": "flow",
            "id": "string"
          }
        ],
        "links": {
          "self": "string",
          "related": "string"
        }
      },
      "flow-messages": {
        "data": [
          {
            "type": "flow-message",
            "id": "string"
          }
        ],
        "links": {
          "self": "string",
          "related": "string"
        }
      }
    },
    "links": {
      "self": "string"
    }
  }
}

You will now be able to fetch performance data on flows that are triggered by your app metrics. Learn more about how you can analyze your marketing performance with our Reporting API.

Additional resources

Updated about 24 hours ago

Power smarter
digital relationships
By entering your information and clicking “Sign up,” you consent to receive marketing emails (such as newsletters, blog posts, webinars, event invitations and new product updates) from Klaviyo from time to time. You can unsubscribe at any time by clicking on the “Unsubscribe” link at the bottom of our emails. For more information on how we process your personal information and what rights you have in this respect, please see our Privacy Policy.
Terms and Privacy Trademarks Security