Skip to main content

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 nameWhere
SUPPORTSCARRIERSaxisType of a table or Reach axis
supportscarriersThe property of a table or Reach axis, and of an optimization request
SUPPORT, SUPPORT_JOINT, TOTAL_MEDIA_SUPPORTCARRIER, CARRIER_JOINT, TOTAL_MEDIAtype of a carrier
FAMILYFOLDERtype of a carrier in targetMedia, rankings, evaluations and response curves
BREAKDOWN_SUPPORTSBREAKDOWN_CARRIERStableType, also in GET /api/v2/statistics
SOPORTESCARRIERStreeType of a tree query
SUPPORTCARRIERtypes of a tree query
NODE_UUID, NODE_ID, NODE_DESCID, CODE, LABELsearchField of a tree query
basetargetBaseThe population base of a Reach request. Do not send both: the last one in the body is used
tglfilterTglThe 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​

TopicRule
Content typeRequests and responses are JSON (UTF-8). Send Content-Type: application/json on POST and PUT.
HTMLThe only exception is POST /api/v2/table/{surveyCode}/html, which returns text/html. Its errors are still JSON.
ErrorsEvery error is a JSON object (application/problem+json). See Errors and troubleshooting.
CompressionJSON and HTML responses are gzip-compressed when the request sends Accept-Encoding: gzip. Error bodies are not compressed.
IdentifiersSurvey 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.
DatesISO 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.
LabelsLabels (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.
NumbersCalculated 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.
EnumsEnumerated 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:

    BodyWhere an unknown field is rejectedAnswer
    The table model of POST /api/v2/table/{surveyCode}, .../html and POST /api/v2/reach/{surveyCode}The request, its weight, dimensions, axes, split categories, the survey waves of a SOURCES axis and their weight400 AE_ERR_411
    POST /api/v2/survey/{surveyCode}/optimizationsAnywhere: the request, target, targetBase, candidate carriers and objectives400 AE_ERR_400

    The 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 400 AE_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 the tableType and type query parameters, returns 400 AE_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​

LimitValueWhat happens
Request body10 MBA larger request is rejected.
Survey tree query3,000 nodes206 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 depth6 levelsNODE_HIERARCHY, NODE_PARENTS and NODE_FULL_HIERARCHY traverse at most 6 levels.
Synchronous calculationAbout two minutes500.
Optimizations per userOne at a timeThe second job ends FAILED.
Queued background jobs per user50, of any kind429 (JOB_USER_LIMIT_REACHED) when you submit another.
Optimization run1 hour of executionThe run stops and returns the plans found so far (DURATION_CAP_REACHED).
Optimization retention30 daysAfter 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:

OperationEffectRepeating it
POST /api/v2/workspaceCreates 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}/sourceAttaches a survey to a workspace.Not idempotent, and it can fail if the survey is already attached. Check the workspace first.
POST .../targetCreates 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 .../optimizationsCreates 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 4xx responses without changing the request. The exceptions are 409 AE_ERR_412 (the optimization has not finished: poll again later) and 429 (wait until some of your jobs finish or start).
  • A 500 on 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 the errorCode.
  • A 500 on an operation that creates data may or may not have created it. Check before you retry.
  • Wait at least retryAfterSeconds between two status polls of an optimization.