Monitor segment growth performance with Reporting API

Monitor the performance of your Klaviyo segment growth performance programmatically using the Reporting API’s new Query Segment Values and Query Segment Series endpoints.

These endpoints require segments:read permissions enabled on your private API key.

Data model

A segment is represented by the following:

segment_id
The unique alphanumeric value identifying a segment. Use the equals operator to return a single segment_id, or the any operator to return a list of matching segment_ids.

The supported attributes for filtering include: segment_id.

Required body parameters:

type
The type of report you are requesting, segment-values-report or segment-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.
OR customtimeframe
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:

total_members
The total number of profiles included in the segment.
members_added
Profiles added to the segment
members_removed
Profiles removed from the segment.
net_members_changed
Net number of profiles changed.

Use cases

Values

The Query Segments Values endpoint returns an array of objects that show performance statistics for a single segment.

Example request and response

 curl --request POST \
 --url https://a.klaviyo.com/api/segment-values-reports/ \
 --header 'Authorization: Klaviyo-API-Key <API-KEY>' \
 --header 'accept: application/json' \
 --header 'content-type: application/json' \
 --header 'revision: 2024-07-15.pre' \
 --data '
 {  
  "data": {  
    "type": "segment-values-report",  
    "attributes": {  
      "statistics": [  
        "total_members",  
        "members_added",  
        "members_removed",  
        "net_members_changed"  
      ],  
      "timeframe": {  
        "key": "last_7_days"  
      },  
      "filter": "equals(segment_id,"RpKvCF")"  
    }  
  }  
}

{  
  "data": {  
    "type": "segment-values-report",  
    "id": "b85c66bb-495d-479b-8425-3ffb7f298f60",  
    "attributes": {  
      "results": [  
        {  
          "groupings": {  
            "segment_id": "RpKvCF"  
          },  
          "statistics": {  
            "total_members": 79,  
            "members_added": 79,  
            "members_removed": 0,  
            "net_members_changed": 79  
          }  
        }  
      ]  
    }  
  },  
  "links": {  
    "self": "<https://a.klaviyo.com/api/segment-values-reports/">  
  }  
}

Series

The Query Segments Series endpoint returns an array of objects that each show performance for a single segment over a given time series.

Example request and response

curl --request POST  
     --url <https://a.klaviyo.com/api/segment-series-reports/>  
     --header 'Authorization: Klaviyo-API-Key <API-KEY>'  
    --header 'accept: application/json'  
     --header 'content-type: application/json'  
     --header 'revision: 2024-07-15.pre'  
     --data '  
{  
  "data": {  
    "type": "segment-series-report",  
    "attributes": {  
      "statistics": [  
        "total_members",  
        "members_added"  
      ],  
      "timeframe": {  
        "key": "last_7_days"  
      },  
      "filter": "equals(segment_id,\"RpKvCF\")",  
      "interval": "daily"  
    }  
  }  
}

{  
  "data": {  
    "type": "segment-series-report",  
    "id": "7bbe2230-3f89-42e7-af21-a31da4eb8b15",  
    "attributes": {  
      "results": \[  
        {  
          "groupings": {  
            "segment_id": "RpKvCF"  
          },  
          "statistics": {  
            "total_members": [  
              0,  
              0,  
              79,  
              79,  
              79,  
              79,  
              79,  
              79  
            ],  
            "members_added": [  
              0,  
              0,  
              79,  
              0,  
              0,  
              0,  
              0,  
              0  
            ]  
          }  
        }  
      ],  
      "date_times": [  
        "2024-07-30T00:00:00+00:00",  
        "2024-07-31T00:00:00+00:00",  
        "2024-08-01T00:00:00+00:00",  
        "2024-08-02T00:00:00+00:00",  
        "2024-08-03T00:00:00+00:00",  
        "2024-08-04T00:00:00+00:00",  
        "2024-08-05T00:00:00+00:00",  
        "2024-08-06T00:00:00+00:00"  
      ]  
    }  
  },  
  "links": {  
    "self": "<https://a.klaviyo.com/api/segment-series-reports/">  
  }  
}

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.

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": "0e2d53c9-bd42-49d1-b815-b46a1c9760b1",  
           "status": 400,  
           "code": "invalid",  
           "title": "Invalid input.",  
           "detail": "Cannot query for segment data before June 1st, 2023",  
           "source": {  
               "pointer": "/data/attributes/timeframe/start"  
           },  
           "links": {},  
           "meta": {}  
       }  
   ]  
}