Our APIs respond with data, errors, and metadata blocks where appropriate
For example, metadata appears only for paginated responses
A response expected to return multiple entities may contain both data and errors blocks
Entity IDs are unique across all Retail Media entities

{
    "data": [
        {
            "type": "{entityType}",
            "id": "{entityId}",
            "attributes": {
                "{fieldName}": {numericValue},
                "{fieldName}": "{stringValue}",
                // ...
            }
        },
   
        // ...
   
        {...}
    ],
    "errors": [
        {
            "traceId": "{traceId}",
            "type": "{errorType}",
            "code": "{errorCode}",
            "instance": "{uri}",
            "title": "{errorTitle}",
            "detail": "{errorDetail}",
            "source": {
                "{fieldName}": "{fieldPath}",
                // ...
            }
        },
 
        // ...
         
        {...}
    ],
    "metadata": {
        "totalItemsAcrossAllPages": {numberOfEntities},
        "currentPageSize": {pageSize},
        "currentPageIndex": {pageIndex},
        "totalPages": {numberOfPages},
        "nextPage": "https://{endpoint}?pageIndex={pageIndex}&pageSize={pageSize}",
        "previousPage": "https://{endpoint}?pageIndex={pageIndex}&pageSize={pageSize}"
    }
}

Data Attributes

Attribute	Descrption
`id` string	Unique ID for the entity; entity IDs are unique across all Retail Media entities
`type` string	Type of entity
`attributes` object	Entity attributes; may be omitted entirely if an entity does not have additional attributes

Error Attributes

Attribute	Description
`traceId` string	Unique ID for the error response
`type` string	Type of error; machine-readable (eg. `validation`)
`code` string	Short machine-readable string for the error (eg. `required-field`)
`instance` string	URI referencing the endpoint that caused the error
`title` string	Short human-readable string that summarizes the issue
`detail` string	Human-readable explanation of the issue
`source` object	Object referencing the field that caused the error

Pagination

Pagination is supported via query parameters for a subset of endpoints that list multiple entities
Results are returned in ascending order by id

List all Accounts associated with your API credentials
List all Brands associated with the Account
List all Retailers associated with the Account
List all Campaigns within the Account
List all Line Items within the Campaign
List all Promoted Products on the Line Item
List all Balances on the Account
List all Campaigns on the Balance

Query Parameters	Description
`pageIndex` integer	Returns the specified page of results given a `pageSize`; pages are 0-indexed
`pageSize` integer	Specifies the maximum number of entities returned in a single page; defaults to `25` entities per page
`limitToId` integer	Limits results to the entity IDs specified; parameter key is repeated, eg. `limitToId=1&limitToId=2`

HTTP Response Codes

200 OK: Request successful
201 Created: New entity was successfully created
207 Multi-Status: May occur when operating on multiple entities, such as the call resulting in some successes but also some failures
400 Bad Request: Improper syntax, check your call structure
401 Unauthorized: Unauthenticated, refresh your access token
403 Forbidden: Insufficient rights to perform this action
404 Not Found: Resource not found, check your entity IDs in the call
408 Timeout: Request timed out
409 Conflict: Request conflicts with something, such as a campaign name that already exists
429 Too Many Requests: Too many requests
5xx: Something's wrong on Criteo's end...