Limits and conventions
This page gathers the rules that apply across the TOM External API: how versions evolve, which formats and sizes the API accepts, what each kind of limit looks like, and which operations you can safely repeat.
1. Versioning
- Breaking changes ship as a new major version under a new base path. Version 2 lives under
/api/v2; version 1 (/api/v1) is frozen. See the Migration guide. - Within v2 the API can add endpoints, optional request fields, response fields and enum values. Ignore the response fields you do not know, and handle unknown enum values gracefully.
- Deprecated fields and endpoints are announced in the Release notes before they are removed.
1.1. Deprecated names
The API names a media vehicle a carrier. Earlier it used the word support in several names, and a few other values had different names too. The old names are still accepted in requests, but they are not documented in the reference and the API never returns them. Use the current names:
| Deprecated name (requests only) | Current name | Where |
|---|---|---|
SUPPORTS | CARRIERS | axisType of a table or Reach axis |
supports | carriers | The property of a table or Reach axis, and of an optimization request |
SUPPORT, SUPPORT_JOINT, TOTAL_MEDIA_SUPPORT | CARRIER, CARRIER_JOINT, TOTAL_MEDIA | type of a carrier |
FAMILY | FOLDER | type of a carrier in targetMedia, rankings, evaluations and response curves |
BREAKDOWN_SUPPORTS | BREAKDOWN_CARRIERS | tableType, also in GET /api/v2/statistics |
SOPORTES | CARRIERS | treeType of a tree query |
SUPPORT | CARRIER | types of a tree query |
NODE_UUID, NODE_ID, NODE_DESC | ID, CODE, LABEL | searchField of a tree query |
base | targetBase | The population base of a Reach request. Do not send both: the last one in the body is used |
tgl | filterTgl | The inline expression of the target and the targetBase of an optimization. Do not send both in one object: the last one is used |
Values that the API accepted before without documenting them keep working, but they are not part of the contract. The release notes announce the removal of the deprecated names in advance.
2. Formats
| Topic | Rule |
|---|---|
| Content type | Requests and responses are JSON (UTF-8). Send Content-Type: application/json on POST and PUT. |
| HTML | The only exception is POST /api/v2/table/{surveyCode}/html, which returns text/html. Its errors are still JSON. |
| Errors | Every error is a JSON object (application/problem+json). See Errors and troubleshooting. |
| Compression | JSON and HTML responses are gzip-compressed when the request sends Accept-Encoding: gzip. Error bodies are not compressed. |
| Identifiers | Survey codes, workspace and element ids, tree node ids, sliceId and jobId are opaque strings. Do not build or parse them, and URL-encode them in paths. |
| Dates | ISO 8601 date-time with a UTC offset, for example 2026-05-27T10:00:00.000+00:00 or 2026-05-27T10:00:00Z. Use a full ISO 8601 parser, not a fixed-format one. The date of the last change has a different field name in some resources: updatedDate in surveys and in target details, updateDate in the elements of a workspace and lastUpdated in the response of creating a workspace. They all mean the same thing. |
| Labels | Labels (variable, category, carrier, statistic and axis names) come in the language of the user behind the API key. Codes and enum values never change with the language. |
| Numbers | Calculated values are unrounded numbers unless you ask for formatted cells. decimals and locale affect only the formatted values: locale changes the regional number format, not the language of the labels. |
| Enums | Enumerated values are upper case (TABULATION, REACH_TABLE, CARRIER). Send them exactly as documented. Values in query parameters (for example tableType) are case-sensitive. |
3. Request bodies
-
Size. A request body can be up to 10 MB.
-
Strict and lenient bodies. Two request bodies reject unknown fields, and the message names the field and where it is:
Body Where an unknown field is rejected Answer The table model of POST /api/v2/table/{surveyCode},.../htmlandPOST /api/v2/reach/{surveyCode}The request, its weight, dimensions, axes, split categories, the survey waves of aSOURCESaxis and theirweight400AE_ERR_411POST /api/v2/survey/{surveyCode}/optimizationsAnywhere: the request, target,targetBase, candidate carriers and objectives400AE_ERR_400The other objects of the table model (variables, categories, statistics, carriers,
target,targetBase) and every other request body currently ignore unknown fields. There, a misspelled optional field is dropped silently, so check your field names against the reference. -
Invalid values. A value of the wrong JSON type, such as text in a numeric field or a string where a list goes, is rejected with
400AE_ERR_400, and the message names the field. An invalid value of an enumerated field of a request body (table, Reach, tree query, optimization), or of thetableTypeandtypequery parameters, returns400AE_ERR_401, and the message lists the valid values.
4. Time
- Synchronous calculations. A calculation (table, ranking, evaluation, Reach table, response curve) that takes longer than about two minutes is aborted with
500. Set your client timeout to at least 120 seconds, and reduce the request (fewer carriers, statistics or axes) when you hit the limit. - Optimization. It is asynchronous. A run stops after one hour of execution. Time spent queued does not count, so a job can take longer than one hour to finish. See Asynchronous optimization.
- Caching. The variables and carriers trees change rarely (when a survey is reloaded): cache them. The survey list and the statistics catalog can change between calls: refresh them when a call reports that something is not available.
5. Limits
| Limit | Value | What happens |
|---|---|---|
| Request body | 10 MB | A larger request is rejected. |
| Survey tree query | 3,000 nodes | 206 Partial Content with the first 3,000 nodes, always as a flat list. Narrow the query and repeat it. The custom tree query of a workspace always returns the whole result. |
| Tree depth | 6 levels | NODE_HIERARCHY, NODE_PARENTS and NODE_FULL_HIERARCHY traverse at most 6 levels. |
| Synchronous calculation | About two minutes | 500. |
| Optimizations per user | One at a time | The second job ends FAILED. |
| Queued background jobs per user | 50, of any kind | 429 (JOB_USER_LIMIT_REACHED) when you submit another. |
| Optimization run | 1 hour of execution | The run stops and returns the plans found so far (DURATION_CAP_REACHED). |
| Optimization retention | 30 days | After that, the job is EXPIRED (or deleted if it did not succeed). |
If you need other limits or a higher throughput, ask your TOM platform representative: do not try to work around a limit by retrying.
6. Concurrency
Calculations are independent and nothing in the API stops you from running several at the same time, but they share the capacity of the platform: keep the concurrency of your client moderate. The exception is optimization, which is limited to one active run per user, including runs started in the TOM web application, and to 50 queued jobs of any kind. A job that starts while another optimization of the same user is active ends FAILED: wait until the previous job reaches a terminal status before you submit the next one.
7. Side effects and idempotency
Most operations are reads or calculations on demand: they change nothing and you can repeat them. These operations create or change data:
| Operation | Effect | Repeating it |
|---|---|---|
POST /api/v2/workspace | Creates a workspace. | Creates another one. Names do not have to be unique. After a timeout, check GET /api/v2/workspaces first. |
POST /api/v2/workspace/{workspaceId}/source | Attaches a survey to a workspace. | Not idempotent, and it can fail if the survey is already attached. Check the workspace first. |
POST .../target | Creates a target. | Creates another one. After a timeout, check GET .../targets. |
PUT .../target/{elementId} | Replaces the name and the expression of a target. | Idempotent. When two clients update the same target at the same time, the last request processed wins. |
POST .../evaluation/save/{workspaceId} | Calculates an evaluation and saves it as a study element. | Creates another element. After a failure, check in the TOM web application before you retry. |
POST .../optimizations | Creates a job. | Creates another job, which competes with the first one. Do not retry a request that timed out without checking. |
GET /api/v2/workspaces has a side effect on the workspaces shared with you: it discards your unsaved per-user changes in them, including the surveys you added with the add-survey operation, and it can reset a TOM web application session that is open at the same time. Do not call it in a polling loop.
Success statuses: creating a target answers 200, not 201; submitting an optimization answers 202; the survey tree query can answer 206.
8. What to retry
- Do not retry
4xxresponses without changing the request. The exceptions are409AE_ERR_412(the optimization has not finished: poll again later) and429(wait until some of your jobs finish or start). - A
500on a calculation can mean that it exceeded the time limit: try a smaller request. If it persists, contact support with the UTC time, the endpoint and theerrorCode. - A
500on an operation that creates data may or may not have created it. Check before you retry. - Wait at least
retryAfterSecondsbetween two status polls of an optimization.