Capout Timestamp - Criteo Docs

Introduction

This endpoint provides programmatic access to the budget exhaustion history (“Budget Hit” events) of line items over the past 3 days. This feature mirrors functionality already available in the CMax and CYield UI, enabling partners to retrieve precise timestamps indicating when a line item’s budget was fully consumed on a given day. This insight is particularly valuable for diagnosing pacing issues, identifying over-delivery patterns, or validating campaign strategy effectiveness.

The endpoints and functionalities covered in this page refers to features available exclusively in Preview for now, which doesn’t mean that they are the only ones available for this domain/scope.For more complete information about our API capabilities, check the Stable version in Welcome to Criteo Retail Media API

Endpoints

Method	Endpoint	Description
POST	`/accounts/{accountId}/line-items/cap-out-history`	Retrieves the historical records of when line items reached their budget cap (`Budget Hit`) status within the last 3 days.

Attributes table

Attribute	Data Type	Description
`lineItemIds`	`list`	List of auction line item IDs, generated internally by Criteo. Up to 50 line items can be accepted per request. Acceptable values: list of strings/int64 Writeable? N / Nullable? N
`budgetTypes`	`list`	This allows for the user to describe the way in which they want to receive capout data for the requested line item(s). Accepted values: list of possible budget types below (case-insensitive) or empty list `Total`: for the total capout for the life of the line item `Hourly`: for the capout of display line items. This is not eligible for Sponsored Products. `Daily`: for the capout of Sponsored Products line items. The most recent 3 days when the line item capped out will be presented in the response. `Monthly`: for the capout of Sponsored Products line items. The most recent 3 months when the line item capped out will be presented in the response. Writeable? N / Nullable? N

Attribute

Data Type

Description

lineItemIds

list

List of auction line item IDs, generated internally by Criteo. Up to 50 line items can be accepted per request.

Acceptable values: list of strings/int64

Writeable? N / Nullable? N

budgetTypes

list

This allows for the user to describe the way in which they want to receive capout data for the requested line item(s).

Accepted values: list of possible budget types below (case-insensitive) or empty list

Total: for the total capout for the life of the line item

Hourly: for the capout of display line items. This is not eligible for Sponsored Products.

Daily: for the capout of Sponsored Products line items. The most recent 3 days when the line item capped out will be presented in the response.

Monthly: for the capout of Sponsored Products line items. The most recent 3 months when the line item capped out will be presented in the response.

Writeable? N / Nullable? N

Field Definitions

Writeable (Y/N): Indicates if the field can be modified in requests.
Nullable (Y/N): Indicates if the field can accept null/empty values.
Primary Key: A unique, immutable identifier of the entity, generated internally by Criteo. Primary keys are typically ID fields (e.g., retailerId, campaignId, lineItemId) and are usually required in the URL path.

budgetTypes behavior This endpoint supports multiple budgetTypes in a single request (e.g., “Daily”, “Monthly”). For each requested type, if eligible cap-out data exists, it will be returned in the response. If no data is available for a given budget type or line item within the 3-day window, the response will simply exclude that entry, resulting in a partial or empty result.

Retrieve Capout History Timestamp

This endpoint provides programmatic access to the budget exhaustion history (“Budget Hit” events) of line items over the past 3 days.

Authorization Required To access this endpoint, the requesting API application must be granted the campaign.manage scope.

Sample Request

curl -L -X POST "https://api.criteo.com/experimental/retail-media/accounts/625702934721171442/line-items/cap-out-history" \
    -H "Authorization: Bearer <MY_ACCESS_TOKEN>" \
    -H "Content-Type: application/json" \
    -H "Accept: application/json" \
    -d '{
            "data": {
                "type": "LineItemCapoutHistory",
                "attributes": {
                    "lineItemIds": ["12345"],
                    "budgetTypes": ["Daily"]
                }
            }
        }'

import requests
import json

url = "https://api.criteo.com/experimental/retail-media/accounts/625702934721171442/line-items/cap-out-history"

payload = json.dumps({
    "data": {
        "type": "LineItemCapoutHistory",
        "attributes": {
            "lineItemIds": ["12345"],
            "budgetTypes": ["Daily"]
        }
    }
})
headers = {
  'Content-Type': 'application/json',
  'Accept': 'application/json',
  'Authorization': 'Bearer <MY_ACCESS_TOKEN>'
}

response = requests.post(url, headers=headers, data=payload)

print(response.text)

OkHttpClient client = new OkHttpClient().newBuilder()
  .build();

MediaType mediaType = MediaType.parse("application/json");

RequestBody body = RequestBody.create(mediaType, 
    "{\"data\":{\"type\":\"LineItemCapoutHistory\",\"attributes\":{\"lineItemIds\":[\"12345\"],\"budgetTypes\":[\"Daily\"]}}}");

Request request = new Request.Builder()
  .url("https://api.criteo.com/experimental/retail-media/accounts/625702934721171442/line-items/cap-out-history")
  .method("POST", body)
  .addHeader("Content-Type", "application/json")
  .addHeader("Accept", "application/json")
  .addHeader("Authorization", "Bearer <MY_ACCESS_TOKEN>")
  .build();

Response response = client.newCall(request).execute();

<?php
require_once 'HTTP/Request2.php';
$request = new HTTP_Request2();
$request->setUrl('https://api.criteo.com/experimental/retail-media/accounts/625702934721171442/line-items/cap-out-history');
$request->setMethod(HTTP_Request2::METHOD_POST);
$request->setConfig(array(
  'follow_redirects' => TRUE
));

$request->setHeader(array(
  'Content-Type' => 'application/json',
  'Accept' => 'application/json',
  'Authorization' => 'Bearer <MY_ACCESS_TOKEN>'
));

$request->setBody('{"data":{"type":"LineItemCapoutHistory","attributes":{"lineItemIds":["12345"],"budgetTypes":["Daily"]}}}');

try {
  $response = $request->send();
  if ($response->getStatus() == 200) {
    echo $response->getBody();
  }
  else {
    echo 'Unexpected HTTP status: ' . $response->getStatus() . ' ' .
    $response->getReasonPhrase();
  }
}
catch(HTTP_Request2_Exception $e) {
  echo 'Error: ' . $e->getMessage();
}

Breaking change (2026-10-02): The capoutTimes response keys were reverted from PascalCase (Daily, Hourly, Monthly, Total) back to lowercase (daily, hourly, monthly, total). As per Criteo’s versioning policy, breaking changes can occur in Experimental. Update any code parsing this response accordingly.

Sample Response

{
    "data": {
        "type": "LineItemBudgetCapOutHistoryResponse",
        "attributes": {
            "lineItemBudgetCapOutHistories": [
                {
                    "lineItemId": "12345",
                    "capoutTimes": {
                        "daily": [
                            "2025-06-13T17:28:13+00:00",
                            "2025-06-12T17:52:24+00:00",
                            "2025-06-11T15:49:44+00:00"
                        ]
                    }
                }
            ]
        }
    },
    "warnings": [],
    "errors": []
}

​Introduction

​Endpoints

​Attributes table

​Retrieve Capout History Timestamp

Introduction

Endpoints

Attributes table

Retrieve Capout History Timestamp