Limits
Request sizes, batch sizes, rate limits, quotas and content limits to design your integration around.
This page lists the limits you are most likely to meet when you send data to Optima, read it back, or author content. Where a limit is a default that your administrator can change, it says so. If a figure here differs from what you observe, your Optima instance has a different setting; ask the provider of your Optima instance.
API requests
| Limit | Value |
|---|---|
Request header X-Request-ID | Required on every call to the CDP API. A request without it is refused with status 400 (X-Request-ID header is required). Send a unique value per request; it is what support uses to trace a call. |
| Page size in lists | At most 100 rows per page. The default is 100. Ask for the next page with page (starting at 0) together with size. |
Profiles in one batch write (/profiles/set/batch) | 1 to 500 by default; the provider of your Optima instance can raise this to at most 1,000. A larger batch is refused whole. |
Profile ids in one page of /profiles/ids or /profiles/changes | 1 to 5,000 (default 1,000). Used by systems that walk all profiles, such as continuous agents. |
Profiles in one /profiles/views call | 1 to 100, with at most 100 attributes and at most 20 event types per call. |
Events in one /events/feed page | 1 to 1,000 (default 500). The feed runs about two minutes behind real time and can repeat an event. |
| Profile ids in one batch lookup | 500 (links batch, consents batch, person resolution, and grouped event counts). |
| Queries in one grouped event-count call | 100 |
| Suppression checks in one batch call | 500 |
Events in one /events/add call | No separate count limit, but the size of the whole request is capped. Send several moderate calls rather than one huge one; each call counts against the rate limit. |
| AI assist calls (describe-to-segment, profile summary, explain, script assist, image generation and similar) | 30 per minute per caller by default (your Optima instance's setting; ask the provider of your Optima instance). |
A batch counts as one request for the rate limits. A batch write is all-or-nothing in validation: if any item is invalid, nothing is stored and the message names the item (profiles[3]: …). A temporary failure on the final write can leave a batch partly applied; sending the same batch again is safe, because it is an upsert.
Updates and deletes of stored data are asynchronous: do not expect to read your own write straight away.
Rate limits and quotas
Calls that go over a limit are answered with status 429 and a Retry-After header telling you how many seconds to wait. Wait that long, then retry; do not retry in a tight loop.
| What is limited | How |
|---|---|
| Per source address | A requests-per-minute bucket for each calling address: 6,000 a minute unless the provider of your Optima instance sets another value. |
| Per workspace | A requests-per-minute quota for interactive callers (people using the console) and a separate one for application keys. Set by the provider of your Optima instance. |
| Events per day | A daily cap on events. Over it, /events/add answers 429 with Retry-After. |
| Profiles | A maximum number of profiles. A call that would create a profile over the cap is refused with 403; updates to existing profiles still work. |
| Connectors | A maximum number of connectors, checked when you create one. |
You can see how close you are to the quotas: the Usage screen in the console and the usage call of the API show the quotas next to your consumption, so you can see the headroom before a 429.
The licence of your account can also switch features off. A call to an unlicensed feature is refused with 403 and reason: feature_not_licensed; see Errors.
Safe retries
Send an X-Idempotency-Key header with a write to the CDP API (a UUID, 36 characters; any other length is answered with 400 invalid idempotency key) and a repeat of the same call with the same key within 15 minutes returns the first answer instead of writing twice. A key belongs to one caller, method and path: the same key on another route, or from another key or user, is a new call. Creating an application and rotating a key are never repeated from the stored answer.
Tracking from websites and apps
The public tracking endpoints that the SDKs call are capped more tightly, because anyone on the internet can reach them with the public key. The figures are defaults.
| Limit | Value |
|---|---|
| Requests per minute per source address | 600 |
| Requests per minute per SDK key | 6,000. A single key can be given its own value in the key's Rate limit (req/min) field. |
| Request body | 64 KB. A larger body is refused with 413. |
| Hits in one tracking request | 20 (never fewer). More is refused with 413, and the SDKs then halve the batch and retry. |
| Properties on one hit | 50 |
| Property name | 128 characters |
| Property value | Text up to 4 KB, a number, a true or false, or a list of text values. Anything else is refused with 400. |
| Text fields such as page address, title or referrer | 4,096 characters |
device_id | 8 to 64 characters from A-Z a-z 0-9 _ - |
| Declared consent purposes in one request | 32 |
| Identifiers in one identify call | 16, each value up to 4,096 characters |
| Content impressions or clicks in one report | 50 |
Tracking calls are refused rather than trimmed: a request over a cap is rejected whole, with 400 or 413, and nothing is stored. A successful call answers 202 and means the data was queued for processing. A 503 with Retry-After means it was not accepted; the SDKs keep it and retry.
Message content
| Limit | Value |
|---|---|
| Output of one personalized field | About 256 KB by default. |
| Time to build one field | 2 seconds by default. Waiting for a short link, file, coupon or recommended items does not count. |
| Loop nesting in a template | 3 levels |
| Loop iterations | 1,000,000 per field |
| Email subject | A single line. A line break is refused. |
| Display name | Must not contain an email address (inboxes treat that as spoofing). |
| Reply-To | A single address, when written without tags. |
Recommended items per items call | 1 up to your Optima instance's maximum (50 by default; the provider of your instance sets it). The Personalization dialog offers 1 to 20. |
On-site and in-app content is built when the visitor loads it and has a shorter time allowance (a fraction of a second), so keep its templates simple. See Personalization syntax.
Expressions
| Limit | Value |
|---|---|
| Length | 8,192 bytes |
| Nested list functions | 2 levels |
| Written range | 1,000 numbers |
| Text produced | 32 KB |
The full list, with the running-time cutoffs, is on Expressions.
Analytics
| Limit | Value |
|---|---|
| Filter nesting | 3 levels of groups inside the top group; 3 linked-profile hops |
| Members of a cohort used live in a filter | 1,000,000. Beyond that the query is refused and asks you to materialize the cohort. |
| Query time | A query that takes longer than your Optima instance's time budget is cut off with a time-out message. Narrow the filter or the period. |
Related
- Errors for the exact status codes and messages.
- Attribute types
- Query filters