Capout Timestamp

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.

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

📘
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	`/preview/retail-media/account/: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`	string	Auction line item ID, generated internally by Criteo. Up to 50 line items can be accepted per request. Acceptable values: int64 Writeable? N / Nullable? N
`budgetTypes`	enum	This allows for the user to describe the way in which they want to receive capout data for a line item. Accepted values: `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.

Attribute

Data Type

Description

lineItemIds

string

Auction line item ID, generated internally by Criteo. Up to 50 line items can be accepted per request.

Acceptable values: int64 Writeable? N / Nullable? N

budgetTypes

enum

This allows for the user to describe the way in which they want to receive capout data for a line item.

Accepted values: 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.

📘
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", "lifetime"). 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.

https://api.criteo.com//preview/retail-media/account/:accountId/line-items/cap-out-history

Sample Request

curl -X POST "https://api.criteo.com/preview/retail-media/v1/account/{accountId}/line-items/cap-out-history" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{
    "data": {
      "type": "LineItemCapoutHistory",
      "attributes": {
        "lineItemIds": ["12345"],
        "budgetTypes": ["Daily"]
      }
    }
  }'

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": []
}

Responses

Client Error Description	External Error Message
No access to campaign	OK 200
Duplicate campaign ID	OK 200
Campaign doesn’t exist	OK 200
No access to line items	OK 200