Change History

This endpoint is available in the Experimental version of the Retail Media API only. Experimental endpoints may change without prior notice. See the versioning policy for details.

Overview

The change history endpoints return a time-ordered log of configuration changes made to Retail Media objects — campaigns, line items, and related entities. Each entry records what changed, on which entity, when it occurred, and the role of the actor who made the change. Two scopes are available: account-level (demand side) and retailer-level (supply side). Changes are returned in descending order by time. Only changes the caller has access to are returned; inaccessible entries are silently omitted.

Prerequisites

Authentication: a valid access token. See Authentication.
App permissions: the RetailMedia_Campaign_Read scope must be enabled on your app. See App Scopes.
Account or retailer access: the authenticated app must have access to the requested account or retailer. A 403 is returned for unknown or inaccessible identifiers.

Endpoints

Method	Endpoint	Description
`GET`	`/accounts/{account-id}/change-history-entries`	List configuration changes within an account.
`GET`	`/retailers/{retailer-id}/change-history-entries`	List configuration changes within a retailer.

Get Change History Entries

Path Parameters

Parameter	Type	Required	Description
`account-id`	string	Yes	Identifier of the advertiser account whose change history is requested.

Query Parameters

Parameter	Type	Required	Description
`campaign-ids`	array[string]	No	Filter to changes on these campaigns. Campaigns the caller cannot access are silently excluded.
`line-item-ids`	array[string]	No	Filter to changes on these line items. Line items the caller cannot access are silently excluded.
`entity-types`	array[string]	No	Filter to these entity types. Unknown values match no entries and do not error.
`event-types`	array[string]	No	Filter to these event types. Unknown values match no entries and do not error.
`start-time`	string (ISO 8601)	No	Inclusive lower bound on change timestamp. Defaults to 7 days before the request time.
`end-time`	string (ISO 8601)	No	Inclusive upper bound on change timestamp. Defaults to the request time.
`limit`	integer	No	Maximum number of entries per page. Between `1` and `100`. Default: `25`.
`offset`	integer	No	Zero-based starting position. Default: `0`. `offset + limit` must not exceed `10,000`. Narrow the time range to retrieve more history.

Array parameters use repeated query keys. For example: event-types=lineItemCreated&event-types=lineItemUpdated. A comma-separated list is treated as a single value and may silently return no results.

Response Attributes

Each data[] item has a type field (ChangeHistoryEntryResponse) and an attributes object:

Attribute	Type	Description
`occurredAt`	string (ISO 8601)	When the change was recorded. Results are sorted descending by this field.
`eventType`	string	Type of event that produced the change (e.g. `lineItemCreated`, `lineItemUpdated`). The set of values is extensible.
`actorRole`	string	Role of the actor who made the change. One of: `unknown`, `internal`, `external`, `api`, `automatedTask`. User identifiers are not returned.
`entity.id`	string	Identifier of the changed entity.
`entity.type`	string	Type of the changed entity (e.g. `lineItem`, `campaign`). The set of values is extensible.
`entity.campaignId`	string or null	Identifier of the parent campaign, when applicable.
`changes[]`	array	List of field-level changes.
`changes[].field`	string	Name of the field that changed.
`changes[].previousValue`	string or null	Value before the change. Null for newly created fields.
`changes[].newValue`	string or null	Value after the change. Null for deleted fields.

Pagination metadata is returned in the meta object:

Field	Type	Description
`offset`	integer	Starting position echoed from the request.
`limit`	integer	Page size echoed from the request.
`count`	integer	Total number of entries across all pages. The number of entries on the current page is `data.length`.

Sample Request

curl -L -X GET 'https://api.criteo.com/experimental/retail-media/accounts/{account-id}/change-history-entries?start-time=2026-10-01T00:00:00Z&end-time=2026-10-15T00:00:00Z&limit=25&offset=0' \
  -H 'Accept: application/json' \
  -H 'Authorization: Bearer <MY_ACCESS_TOKEN>'

Sample Response — 200 OK

{
  "data": [
    {
      "id": "abc123",
      "attributes": {
        "occurredAt": "2026-10-14T09:32:11Z",
        "eventType": "lineItemUpdated",
        "actorRole": "api",
        "entity": {
          "id": "112233445566778899",
          "type": "lineItem",
          "campaignId": "987654321"
        },
        "changes": [
          {
            "field": "isPaused",
            "previousValue": "false",
            "newValue": "true"
          }
        ]
      }
    }
  ],
  "meta": {
    "offset": 0,
    "limit": 25,
    "count": 1
  },
  "errors": [],
  "warnings": []
}

Get Change History Entries (Retailer)

Path Parameters

Parameter	Type	Required	Description
`retailer-id`	string	Yes	Identifier of the retailer whose change history is requested.

Query Parameters

Same as the account endpoint above.

Response Attributes

Same shape as the account endpoint above.

Campaign-level changes are not returned by this endpoint — only line-item and other retailer-scoped entity changes are included. This applies to both onsite and offsite campaign changes.

Sample Request

curl -L -X GET 'https://api.criteo.com/experimental/retail-media/retailers/{retailer-id}/change-history-entries?start-time=2026-10-01T00:00:00Z&end-time=2026-10-15T00:00:00Z&limit=25&offset=0' \
  -H 'Accept: application/json' \
  -H 'Authorization: Bearer <MY_ACCESS_TOKEN>'

Sample Response — 200 OK

{
  "data": [
    {
      "id": "def456",
      "attributes": {
        "occurredAt": "2026-10-13T14:05:22Z",
        "eventType": "lineItemUpdated",
        "actorRole": "internal",
        "entity": {
          "id": "556677889900112233",
          "type": "lineItem",
          "campaignId": "123456789"
        },
        "changes": [
          {
            "field": "budget",
            "previousValue": "500.00",
            "newValue": "750.00"
          }
        ]
      }
    }
  ],
  "meta": {
    "offset": 0,
    "limit": 25,
    "count": 1
  },
  "errors": [],
  "warnings": []
}

Known Limitations

The default time window is the last 7 days. There is no documented maximum lookback period.
User identifiers are not returned — only the actor’s role (api, internal, etc.).
The order of entries with identical occurredAt timestamps is not defined.
entity-types and event-types enum values are not yet published in the spec. Unknown values are accepted but match no entries.

Error Codes

HTTP Status	`errors[].code`	`errors[].type`	When it occurs
`400`	`model-validation-error`	`validation`	Malformed dates or non-integer/out-of-range pagination parameters. `limit` must be 1–100 and `offset` must be nonnegative.
`400`	`invalid-time-range`	`validation`	The effective `start-time` is later than `end-time`, including when one bound uses its default.
`400`	`invalid-pagination`	`validation`	`offset + limit` exceeds 10,000. Narrow the time range to retrieve more history.
`401`	`authorization-token-invalid` or `authorization-token-expired`	`authorization`	Missing, invalid, or expired bearer token.
`403`	`missing-scope`	`authorization`	The app lacks `RetailMedia_Campaign_Read`.
`403`	`not-authorized`	`access-control`	The requested account or retailer is unknown or inaccessible. These cases are intentionally indistinguishable.
`429`	—	—	Request rate limit exceeded.

Unknown event-types or entity-types values are not validation errors — they match no entries and return 200 with an empty result.

Introduction

Guides for Retail Media API

Overview

Prerequisites

Endpoints

Get Change History Entries

Path Parameters

Query Parameters

Response Attributes

Get Change History Entries (Retailer)

Path Parameters

Query Parameters

Response Attributes

Known Limitations

Error Codes

​Overview

​Prerequisites

​Endpoints

​Get Change History Entries

​Path Parameters

​Query Parameters

​Response Attributes

​Get Change History Entries (Retailer)

​Path Parameters

​Query Parameters

​Response Attributes

​Known Limitations

​Error Codes

Overview

Prerequisites

Endpoints

Get Change History Entries

Path Parameters

Query Parameters

Response Attributes

Get Change History Entries (Retailer)

Path Parameters

Query Parameters

Response Attributes

Known Limitations

Error Codes