canonical: https://jentic.com/apis/criteo.com/criteo

# Criteo API

The Criteo API exposes Criteo's Retail Media platform programmatically, covering the full lifecycle of running ads on retailer storefronts. The 2026-01 surface includes account and brand management, balances and budgets, campaigns with auction and preferred line items, creatives and assets, audience segments and contact lists, catalog ingestion, and partner billing reports. It is OAuth2-authenticated and is the integration target for agencies, retail brands, and marketplaces that programmatically buy or operate sponsored placements through Criteo.

## For AI agents

Programmatically run Criteo Retail Media: create and update campaigns, manage line items and creatives, fund balances, build audience segments, ingest catalogs, and pull billing and reporting outputs. Use it for retail-media buying automation and reporting.

## Scope

Does not handle non-retail-media advertising surfaces, payment settlement, or end-shopper transactions - use for Criteo Retail Media campaign, balance, audience, catalog, and reporting operations only.

## Capabilities

- List Criteo accounts and manage their brand and seller relationships including private market parent and child accounts
- Create and modify balances on an account, add funds, and change the active dates that govern campaign spend
- Create campaigns and update their settings, including campaign budget overrides at the campaign level
- Create auction line items and preferred line items under a campaign and update their bids and configuration
- Build creatives and assets, list them, search them, and update individual creatives by ID
- Manage audience segments and their contact lists in bulk, including create, search, update, and delete operations
- Submit asynchronous catalog and billing report requests and poll their status to retrieve the output once ready

## Use cases

### Automated retail-media campaign creation

Stand up a new sponsored-product campaign end to end by calling POST /2026-01/retail-media/accounts/{account-id}/campaigns to create the campaign, POST /2026-01/retail-media/campaigns/{campaignId}/auction-line-items to add line items, and POST /2026-01/retail-media/accounts/{account-id}/creatives to attach creatives. Useful for agencies onboarding a new brand or rolling out a seasonal push without using the Criteo UI.

Example prompt: Call POST /2026-01/retail-media/accounts/{account-id}/campaigns with campaign payload, then POST /2026-01/retail-media/campaigns/{campaignId}/auction-line-items per line item, then POST /2026-01/retail-media/accounts/{account-id}/creatives for each creative.

### Audience segment build and contact-list sync

Sync first-party email lists into Criteo audience segments by creating segments through POST /2026-01/retail-media/accounts/{account-id}/audience-segments/create and pushing emails with POST /2026-01/retail-media/audience-segments/{audience-segment-id}/contact-list/add-remove. The contact list statistics endpoint exposes match progress so the integration can wait until the segment is usable.

Example prompt: Call POST /2026-01/retail-media/accounts/{account-id}/audience-segments/create, then POST /2026-01/retail-media/audience-segments/{audience-segment-id}/contact-list/add-remove with the email batch, then GET /2026-01/retail-media/accounts/{account-id}/audience-segments/{audience-segment-id}/contact-list to read match stats.

### Asynchronous billing and catalog reporting

Pull Criteo financial and catalog data for warehouse load by submitting asynchronous report requests and polling for status before downloading output. Use POST /2026-01/retail-media/billing/partner-report to submit, then poll GET /2026-01/retail-media/billing/partner-report/{requestId}/status, and download with GET /2026-01/retail-media/billing/partner-report/{requestId}/output once ready.

Example prompt: Submit a billing report via POST /2026-01/retail-media/billing/partner-report, poll GET /2026-01/retail-media/billing/partner-report/{requestId}/status until succeeded, then download via GET /2026-01/retail-media/billing/partner-report/{requestId}/output.

### Agent-driven retail media operations through Jentic

Let an agent answer 'top up balance B with $5,000 and pause the campaign that depends on it' by routing through Jentic. The agent searches for an add-funds operation, loads the Criteo balance schema, and executes the call with the OAuth2 client credentials kept in the vault.

Example prompt: Through Jentic, run search('add funds to a Criteo balance'), load POST /2026-01/retail-media/accounts/{account-id}/balances/{balance-id}/add-funds, and execute it with the target balance and amount.

## Key endpoints

| Method | Path | Description |
| --- | --- | --- |
| POST | /2026-01/retail-media/accounts/{account-id}/campaigns | Create a campaign on an account |
| POST | /2026-01/retail-media/campaigns/{campaignId}/auction-line-items | Create an auction line item on a campaign |
| POST | /2026-01/retail-media/accounts/{account-id}/creatives | Create a creative on an account |
| POST | /2026-01/retail-media/accounts/{account-id}/balances | Create a balance on an account |
| POST | /2026-01/retail-media/accounts/{account-id}/balances/{balance-id}/add-funds | Add funds to a balance |
| POST | /2026-01/retail-media/audience-segments/{audience-segment-id}/contact-list/add-remove | Add or remove contacts in a segment |
| POST | /2026-01/retail-media/billing/partner-report | Submit an asynchronous partner billing report |
| GET | /2026-01/retail-media/billing/partner-report/{requestId}/output | Download a finished partner billing report |

## Key resources

- **Accounts and brands** — Account-management endpoints under /retail-media/account-management and /retail-media/accounts that manage account, brand, and seller relationships.
- **Balances** — Per-account balances with create, modify, add-funds, and change-dates endpoints, plus history and campaign linkage.
- **Campaigns and line items** — Campaigns under /retail-media/campaigns and /retail-media/accounts/{account-id}/campaigns, with auction and preferred line items and budget overrides.
- **Creatives and assets** — Account-level creatives and assets endpoints, including search and individual update by ID.
- **Audience segments** — Bulk create, search, update, delete on audience segments and per-segment contact list management.
- **Catalogs** — Catalog and seller catalog exports, plus catalog output retrieval per catalog ID.
- **Reports** — Asynchronous billing and partner reports submitted by request ID with status and output endpoints.

## Why Jentic

- **Setup:** Wiring Criteo Retail Media by hand means running its OAuth2 client-credentials exchange at api.criteo.com/oauth2/token, refreshing the bearer, and mapping calls across a 108-path surface. Through Jentic you install once, import Criteo from the API Directory, store the client credentials once, and your agent calls it.
- **Permission scoping:** Criteo puts the account id in the URL path (/retail-media/accounts/{account-id}/...), so a rule can pin the agent to one retail-media account. You choose the operations it may call, so adding funds to a balance is not included unless you add that operation.
- **Credential handling:** Your Criteo client credentials are stored once, encrypted, by your own Jentic One instance and exchanged for a bearer at execution time. They never enter the agent's prompt, logs, or context.
- **Discovery method:** Agents search Jentic by intent such as 'create a Criteo campaign' or 'add funds to a Criteo balance', and Jentic returns the matching Criteo operation with its input schema so the agent calls the right endpoint without browsing the reference docs.

## Related APIs

- **The Trade Desk** — DSP API for programmatic display, video, and CTV that overlaps with retail media buying workflows.
- **Outbrain** — Native and content recommendation advertising API.
- **Facebook Graph** — Marketing API often run alongside retail-media spend for branded social campaigns.

## FAQ

### What authentication does the Criteo API use?

The API uses OAuth 2.0 with client-credentials and authorization-code flows. Exchange your client ID and secret at https://api.criteo.com/oauth2/token for an access token, then call the API with that bearer. Through Jentic, the credentials are stored encrypted and the token is fetched and refreshed automatically so they never enter the agent's prompt.

### Can I create a campaign with the Criteo API?

Yes. POST /2026-01/retail-media/accounts/{account-id}/campaigns creates a campaign on an account. Add auction line items with POST /2026-01/retail-media/campaigns/{campaignId}/auction-line-items and creatives with POST /2026-01/retail-media/accounts/{account-id}/creatives.

### How do I top up a Criteo balance through the API?

Call POST /2026-01/retail-media/accounts/{account-id}/balances/{balance-id}/add-funds with the amount payload. To shift the active window without changing the amount, use POST /2026-01/retail-media/accounts/{account-id}/balances/{balance-id}/change-dates instead.

### How do I retrieve a partner billing report from the Criteo API?

Submit the request with POST /2026-01/retail-media/billing/partner-report, then poll GET /2026-01/retail-media/billing/partner-report/{requestId}/status until the job is succeeded, and finally download the file with GET /2026-01/retail-media/billing/partner-report/{requestId}/output.

### What are the rate limits for the Criteo API?

Criteo enforces per-application rate limits and surfaces them in response headers rather than declaring fixed numeric ceilings in the spec. Build retries with exponential backoff around HTTP 429 responses, particularly on bulk audience segment and creative endpoints.

### How do I add funds to a Criteo balance through Jentic?

Install Jentic with pip install jentic, then async-search for 'add funds to a Criteo balance'. Jentic returns POST /2026-01/retail-media/accounts/{account-id}/balances/{balance-id}/add-funds; load it and execute with the account, balance, and amount fields. Jentic handles the OAuth2 token exchange against api.criteo.com automatically.

### Can I limit what my agent is allowed to do with the Criteo API?

Yes. Because you run Jentic One yourself, your own rules decide which Criteo operations and credentials the agent may use. Criteo carries the account id in the URL path (/retail-media/accounts/{account-id}/...), so a rule can pin the agent to a single retail-media account. You also choose which operations it may call, so a sensitive action like adding funds to a balance with POST /retail-media/accounts/{account-id}/balances/{balance-id}/add-funds stays unavailable unless you explicitly allow it, while you still permit reads such as pulling a partner billing report.