Retrieve a Custom Conversion Event Report

Get a report for your conversion events. This method is recommended for verifying custom conversion events. If you'd like to verify standard events, we recommend using the Events Manager instead.

1. Find the index mapping

Call Get Last Fired At and use custom_events in the response to map custom event labels. If your fields are valid, you’ll receive a response like this:

"data": {
    // Additional fields here
    "custom_events": [
        {
            "last_fired_at": "2024-03-11T19:03:32+00:00",
            "name": "begin_checkout"
        },
        {
            "last_fired_at": "2024-03-12T00:59:05.981000+00:00",
            "name": "login"
        },
        {
            "last_fired_at": "2024-03-11T08:03:41.323000+00:00",
            "name": "select_item"
        },
        {
            "last_fired_at": "2024-03-10T23:36:53.844000+00:00",
            "name": "share"
        }
    ]
}

The custom conversion events will be listed by their index in ascending order, starting with 1. For example, the first conversion event begin_checkout will have an index of 1.

2. Get the report for a custom event

Fetch data for custom conversion events by calling Get A Report and adding the designated value to the fields list. Enum for custom event has pattern of CONVERSION_CUSTOM_EVENT_{{index}}_{{field}}, where:

Parameter	Requirements	Description
{{index}} (integer)	Between 1 and 20 The slot for the custom conversion event. For example, if your event was the first item in the custom_events array, you should set this to 1.
{{field}} (string)	Must include at least one of the following: AVG_VALUE CLICKS ECPA ROAS TOTAL_ITEMS TOTAL_VALUE VIEWS	The field that you want to be returned in your metrics.

Reporting returns conversion data based on the attribution window selected in the Ads Manager.

For example, to return click and view conversions for custom conversion event 1:

"data": {
    "fields": [
        "CONVERSION_CUSTOM_EVENT_1_CLICKS",
        "CONVERSION_CUSTOM_EVENT_1_VIEWS"
    ],
    "starts_at": "2024-03-10T00:00:00Z",
    "ends_at": "2024-03-12T00:00:00Z"
}

Data will be returned in the same format as standard conversion events. If your event is well-formatted and your fields are valid, you’ll receive a response like this:

"data": {
    "metrics": [
        {
            "conversion_purchase_clicks": 7,
            "conversion_purchase_views": 0,
            "conversion_custom_event_1_clicks": 56,
            "conversion_custom_event_1_views": 0,
            "conversion_custom_event_3_clicks": 36,
            "conversion_custom_event_3_views": 0
        }
    ],
    "metrics_updated_at": "2024-03-11T00:00:00Z"
},
"pagination": {
    // Additional fields here
}