Monitor the performance of your Klaviyo forms programmatically using the Reporting API’s new Query Forms Values and Query Forms Series endpoints.
These endpoints require forms:read permissions enabled on your private API key.
Data model
A form is represented by the following:
form_id
The unique alphanumeric value identifying a single form. Use the equals operator to return a singleform_id, or the any operator to return a list of matchingform_ids.form_version_id
The unique alphanumeric value identifying the version for a single form
Results are grouped by form_id by default. Use group_by with the default or add form_version_id to enable form version reporting.
To group by
form_version_idin your request,form_idis also required.
The supported attributes for filtering include both form_id and form_version_id.
Required body parameters:
type
The type of report you are requesting, forms-values-report or forms-series-report.statistics
List of statistics to query. All rate statistics are returned in fractional form [0.0, 1.0].timeframe
A pre-defined key attribute that represents a set timeframe. For a list of all supported timeframe key values, review the Reporting API Overview.
ORcustomtimeframe
Optional, this cannot be used in addition to timeframe. To use customtimeframe you must pass in a valid start date and end date.
Supported statistics include:
viewed_form
The total number of times the form was viewed.viewed_form_uniques
The number of times a form was viewed by unique users.submits
The total number of form submissions.submit_rate
The rate of form submissions over form views.closed_form
The total number of times a form was closed.closed_form_uniques
The number of times a form was closed by unique users.qualified_form
The total number of times a user qualified to view the form (such as in an A/B testing scenario).qualified_form_uniques
The number of times a unique user was qualified to view the form.viewed_form_step
The total number of times a form step is viewed by a user.viewed_form_step_uniques
The number of times a form step is viewed by unique users.submitted_form_step
The total number of times a form step is completed by a user.submitted_form_step_uniques
The number of times a form step is completed by unique users.
Use cases
Values
The Query Forms Values endpoint returns an array of objects that show performance statistics for a form.
Example request and response
curl --request POST
--url <https://a.klaviyo.com/api/form-values-reports>
--header 'Authorization: Klaviyo-API-Key your-private-api-key'
--header 'accept: application/json'
--header 'revision: 2024-07-15.pre'
{
"data": {
"type": "form-values-report",
"attributes": {
"timeframe": {
"key": "last_12_months",
},
"filter": "any(form_id,[\"abc123\",\"def456\" ])",
"statistics": [
"viewed_form",
"submits",
"submit_rate"
],
"group_by": [
"form_id",
"form_version_id"
]
}
}
}
{
"data": {
"type": "form-values-report",
"attributes": {
"results": [
{
"groupings": {
"form_id": "abc123"
"form_version_id": "012tuy"
},
"statistics": {
"viewed_form": 90,
"submits": 9,
"submit_rate": 0.10
}
},
{
"groupings": {
"form_id": "abc123"
"form_version_id": "765ghi"
},
"statistics": {
"viewed_form": 10,
"submits": 1,
"submit_rate": 0.10
}
},
{
"groupings": {
"form_id": "def456",
"form_version_id": "789jkl"
},
"statistics": {
"viewed_form": 200,
"submits": 10,
"submit_rate": 0.05
}
}
]
}
}
}
Series
The Query Forms Series endpoint returns an array of objects that show performance for individual forms broken down by time series.
For each statistic included in the request, the response outputs a series of dates and the statistic’s corresponding values.
For example:
"viewed_form": {
"2024-03-01": 20,
"2024-03-02": 25,
"2024-03-03": 30
}
For the viewed_form statistic, form views were captured on three dates within the given timeframe. For each date in the array, the total number of form views is returned as an integer.
Example request and response
curl --request POST
--url <https://a.klaviyo.com/api/form-series-reports>
--header 'Authorization: Klaviyo-API-Key your-private-api-key'
--header 'accept: application/json'
--header 'revision: 2024-07-15.pre'
{
"data": {
"type": "form-series-report",
"attributes": {
"timeframe": {
"key": "last_3_months",
},
"interval": "monthly",
"filter": "equals(form_id,\"abc123\")",
"statistics": [
"viewed_form",
"submits",
"submit_rate"
]
}
}
}
{
"data": {
"type": "form-series-report",
"attributes": {
"results": [
{
"groupings": {
"form_id": "01GMRWDSA0ARTAKE1SFX8JGXAY"
},
"statistics": {
"viewed_form": {
"2024-03-01": 20,
"2024-04-01": 20,
"2024-05-01": 20
},
"submits": {
"2024-03-01": 2,
"2024-04-01": 2,
"2024-05-01": 2
},
"submit_rate": {
"2024-03-01": 0.1,
"2024-04-01": 0.1,
"2024-05-01": 0.1
}
}
}]
}
}
Common errors
4XX errors indicate a bad request, which can result from the following issues:
- Missing fields for a timeframe, or including too many timeframe fields.
- Filtering for more than 100 forms in a single request.
- Passing in an invalid or unsupported statistic.
- Requesting a timeframe that is too long. The maximum supported timeframe is 1 year, up to June 1, 2023.
- Using an invalid filter or an unsupported operator.
- Filtering for the same attribute more than once in a single request.
- Grouping with group_by:
["form_version_id"]without including theform_id.
5XX errors are returned in response to a MetricServiceRetryableError. It indicates that the request has failed but is safe to retry after a short period.
Example error response
{
"errors": [
{
"id": "51cd68be-29df-4229-ac1f-0f76c4ecb75e",
"status": 400,
"code": "invalid",
"title": "Invalid input.",
"detail": "Can group by form_version_id only if form_id are also passed in together",
"source": {
"pointer": "/data/attributes/group_bys"
},
"links": {},
"meta": {}
}
]
}