Skip to content
Optima docs
Reference

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

LimitValue
Request header X-Request-IDRequired 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 listsAt 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/changes1 to 5,000 (default 1,000). Used by systems that walk all profiles, such as continuous agents.
Profiles in one /profiles/views call1 to 100, with at most 100 attributes and at most 20 event types per call.
Events in one /events/feed page1 to 1,000 (default 500). The feed runs about two minutes behind real time and can repeat an event.
Profile ids in one batch lookup500 (links batch, consents batch, person resolution, and grouped event counts).
Queries in one grouped event-count call100
Suppression checks in one batch call500
Events in one /events/add callNo 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 limitedHow
Per source addressA requests-per-minute bucket for each calling address: 6,000 a minute unless the provider of your Optima instance sets another value.
Per workspaceA 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 dayA daily cap on events. Over it, /events/add answers 429 with Retry-After.
ProfilesA maximum number of profiles. A call that would create a profile over the cap is refused with 403; updates to existing profiles still work.
ConnectorsA 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.

LimitValue
Requests per minute per source address600
Requests per minute per SDK key6,000. A single key can be given its own value in the key's Rate limit (req/min) field.
Request body64 KB. A larger body is refused with 413.
Hits in one tracking request20 (never fewer). More is refused with 413, and the SDKs then halve the batch and retry.
Properties on one hit50
Property name128 characters
Property valueText 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 referrer4,096 characters
device_id8 to 64 characters from A-Z a-z 0-9 _ -
Declared consent purposes in one request32
Identifiers in one identify call16, each value up to 4,096 characters
Content impressions or clicks in one report50

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

LimitValue
Output of one personalized fieldAbout 256 KB by default.
Time to build one field2 seconds by default. Waiting for a short link, file, coupon or recommended items does not count.
Loop nesting in a template3 levels
Loop iterations1,000,000 per field
Email subjectA single line. A line break is refused.
Display nameMust not contain an email address (inboxes treat that as spoofing).
Reply-ToA single address, when written without tags.
Recommended items per items call1 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

LimitValue
Length8,192 bytes
Nested list functions2 levels
Written range1,000 numbers
Text produced32 KB

The full list, with the running-time cutoffs, is on Expressions.

Analytics

LimitValue
Filter nesting3 levels of groups inside the top group; 3 linked-profile hops
Members of a cohort used live in a filter1,000,000. Beyond that the query is refused and asks you to materialize the cohort.
Query timeA 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.

On this page