Workspaces, targets and reusable elements
A workspace is where TOM keeps what a user saves: tabulations, Reach tables, targets and user variables, together with the surveys attached to it. This guide shows how to find workspaces, create them, read and reuse their elements and manage targets.
1. Find workspaces
GET /api/v2/workspaces returns every workspace the user can open: the workspaces they own and the workspaces other users have shared with them.
- Use the
idof a workspace asworkspaceIdin the workspace endpoints. surveyCodeandsurveyDescriptiondescribe the active survey of the workspace (the one selected in the TOM web application). They are empty strings when the workspace has no active survey, for example right after you create it.- The list is not paginated.
- By default the list follows the order the user chose in the workspaces view of the TOM web application; without one, the most recently updated first. Send
orderBy(NAMEorLAST_UPDATED) andascendingto get another order. ownershiptells whether the user owns the workspace (OWN), owns it and shares it (SHARED_BY_ME), or another user shares it with them (SHARED_WITH_ME, with the owner inownerName). ASHARED_WITH_MEworkspace is read only: only its owner can create, edit or delete its elements.lastUpdatedis the last update of the workspace itself, not of its elements. It is omitted when the workspace was never updated.
Calling this operation discards your unsaved per-user changes in the workspaces shared with you, including the surveys you added to them 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 loop.
2. Create a workspace and add a survey
POST /api/v2/workspace creates an empty workspace owned by the user of the key. Only name is required (up to 250 characters); title (250) and description (500) are optional.
{ "name": "Q4 2026 media plan" }
- Names do not have to be unique, so every successful call creates a new workspace. After a timeout, check
GET /api/v2/workspacesbefore you retry. - The new workspace has no surveys and no active survey.
POST /api/v2/workspace/{workspaceId}/source attaches a survey to a workspace so that it appears in its surveys list:
{ "code": "APP_DEMO_2025" }
codemust be the code of a survey fromGET /api/v2/users/surveys. It is not checked against the catalog: an unknown code is accepted with200but never appears in the workspace.- Adding a survey does not make it the active survey of the workspace.
- Do not add a code that is already attached: the call is not idempotent and can fail. Check the
surveysof the workspace first. - In a workspace shared with you, the list of surveys is kept per user: the survey is added to your list only, and after the addition your list may no longer include the surveys the owner attached.
3. Read a workspace
GET /api/v2/workspace/{workspaceId} returns the workspace, the saved elements you can reuse and the surveys attached to it.
| Property | Contains | Use the element id with |
|---|---|---|
tabulations | Saved tabulations, including trend tables | The saved tabulation and the element operations |
reachTables | Saved Reach tables | The element operation |
targets | Saved targets (audiences) | target.id in requests, and the update-target operation |
userVars | User variables | The user variables list, which returns the ids to use in CUSTOM_VAR axes |
- Repeat
typeonce per element type to keep only those lists, for example?type=TABULATION&type=TARGET. The values areTABULATION,REACH_TABLE,TARGETandUSER_VAR, in upper case. Lists that are not requested are omitted;surveysis always returned. Comma-separated values are not split. Any other value is400AE_ERR_401, and the message lists the valid ones. - Saved studies (rankings, evaluations, breakdowns and duplications) are not listed.
surveyslists every survey attached to the workspace, including surveys the user can no longer query, and does not includeavailableReach. Check them against the survey list before you use one.- A workspace that is neither owned by nor shared with the user gives
400WS_ERR_403. AworkspaceIdthat does not exist gives500GEN_ERR_500, not404.
4. Reuse a saved table
Saved tabulations and Reach tables come back in two forms:
- As they are:
GET .../survey/{surveyCode}/tabulation/{elementId}calculates the saved tabulation and returns one slice per call. See Building tables. - As a request you can edit:
GET /api/v2/workspace/{workspaceId}/element/{elementId}returns the element converted to the request format of this API:tablefor a tabulation or a Reach table,targetfor a target, and only the metadata for a user variable. Send a tabulation toPOST /api/v2/table/{surveyCode}. Send a Reach table unchanged toPOST /api/v2/table/{surveyCode}, its/htmlvariant orPOST /api/v2/reach/{surveyCode}: it carries its Reach settings.
What to know before you reuse a table as a request:
- The returned
tablecarries the dimensions, the table type,extraParams(trendCategoriesModeincluded), the savedtargetand, when the base was saved applied, thetargetBase. A target or a base comes withidwhen it was saved by id, withfilterTglwhen there is a saved TGL expression or its saved conditions can be written as one, and withlabelwhen there is one. Withresolve=TGL, a target or a base saved byidalso returns itsfilterTgl. A target or a base that cannot be returned in one of these forms is listed innotReproducible(see below). - A
TABULATIONorREACH_TABLEcarries its effectiveweeksandweight: when the element has none saved, or the survey no longer has the saved one, they are the first week and the default weighting of the survey, the ones the TOM web application shows. ATRENDorREACH_TRENDcarries them, withselected, in each survey wave of itsSOURCESaxis. - A Reach table (
REACH_TABLE,REACH_DUPLICATIONorREACH_TREND) carries itstargetMediaanddiaryFilterswhen they were saved. Its time configuration is in itsTIME_DIARY_EDGEaxes, so no Reach setting that changes the figures is left out. - A
REACH_TRENDcomes complete: the elementtypeisREACH_TABLE,table.tableTypeisREACH_TREND, anddimensionscarries itsSOURCESandDIFFERENCESaxes. ASOURCESaxis saved as a group of surveys comes expanded, one survey wave per member with its weeks and weighting. The weeks and the weighting of a wave only decide whether the wave is calculated: two waves of the same survey that differ only in them give identical columns. surveyCodein the element is the survey currently active in the workspace, not necessarily the survey the element was saved with, and the table was read with it. Send the request to thatsurveyCodeto get the figures of the element. In aREACH_TREND, the survey of the path acts as the active survey of the comparison, so another survey can give other figures: a survey without Reach is rejected with400RC_ERR_100, and a saved target that exists but does not resolve in that survey is left out of every wave with anERRORdiagnostic, while the answer is200over the whole population.- To build the request, the platform evaluates the saved table: expect the latency of a calculation, once per survey wave in a
TRENDorREACH_TREND, and an error if the saved definition is no longer valid for the active survey: when the variables of the element do not exist in the survey currently active in the workspace, the answer is400,TB_ERR_104when none of them exists there, orVA_ERR_101. - Saved studies (rankings, evaluations, breakdowns, duplications) are not supported and return
404.
Parts that cannot be returned as they were saved. notReproducible lists, outside table, what the request cannot carry as it was saved. It is omitted when there is nothing to mark. Each entry has a field and a reason:
field | reason | What happened |
|---|---|---|
target, targetBase | NEGATION | The whole definition is negated, or it negates a numeric condition. A group or a category negated with NOT is written in filterTgl and is not marked. |
target, targetBase | WEIGHT | A box or a reference of the definition carries a weight. |
target, targetBase | NESTED | The definition has nested sets or references that cannot be expanded. |
target, targetBase | EMPTY | The definition has no conditions. |
target, targetBase | OTHER | Any other reason, or the platform did not report one. |
diaryEdge | GROUPED_ITEM | An item of a CUSTOM_DIARY_EDGE axis grouped several values (for example Monday to Friday), and it was left out of the axis. |
diaryEdge | TOTAL_ITEM | A CUSTOM_DIARY_EDGE or TIME_DIARY_EDGE axis shows its total item, which a request cannot ask for: sent back, the table has that row or column fewer. |
- A marked
targetortargetBasecomes intablewith itslabelonly. Sent back unchanged, it is rejected with400AE_ERR_405and the message names the field: the table is never calculated over the whole population. Define it again, byidor withfilterTgl, before you send the table. - A base that is not applied is neither returned nor marked.
- A grouped item is marked once, however many axes had one. The other items of the axis are returned as usual; an axis left without items is left out, and so is a dimension left without axes. Sent back, the table is calculated without the grouped item.
5. Targets
A target is a named audience defined by a TGL expression, saved in a workspace. See the TGL guide for the syntax.
| To | Use |
|---|---|
| List the targets, in the folder structure of the user | GET /api/v2/workspace/{workspaceId}/survey/{surveyCode}/targets |
| Read the stored expressions and dates | POST .../targets/details with the ids |
| Create a target | POST .../target |
| Replace a target | PUT .../target/{elementId} |
List. The response has nodes of two types: TARGET_VAR (a saved target, with id, label and subtype LOGIC) and FOLDER (with label and items; folders have no id). Every target of the workspace is returned, whatever surveyCode you send: targets are not tied to a survey, and one that uses variables missing from a survey fails only when you use it with that survey. The response currently also contains the root folder of the workspace's user variables. If the workspace has no targets, the root Targets folder itself is returned.
Details. Send { "ids": ["..."] }. The response has one entry per id that can be returned, with id, label, filterTgl, creationDate and updatedDate. filterTgl is equivalent to the expression you saved but can be written differently: parentheses are normalised and negations are pushed down. An id that cannot be returned (it does not exist, or belongs to a workspace you cannot access) is left out without an error; if none can be returned, the answer is 200 with []. A missing or empty ids is a 400 VAL_ERR_001.
Create. Send the name and the expression:
{ "label": "Men, age groups 3 and 4", "tgl": "SEX.D1 AND (EDA1.D3 OR EDA1.D4)" }
workspaceIdmust be a workspace you own.surveyCodeis the survey used to check the expression, usually the workspace's own survey.- The expression is checked before anything is saved: if the check fails, no target is created. An invalid expression returns a TGL error even when the workspace does not exist.
- The answer is
200with the newid, thelabeland thetglexactly as you sent them. - The target is added at the end of the root of the Targets folder: the API cannot place it in a sub-folder.
- Not idempotent: names do not have to be unique, so every call creates a new target. After a timeout, check the list before you send it again.
Update. PUT .../target/{elementId} is a full replacement: send both label and tgl, even when only one changes. The target keeps its id, so requests that reference it use the new definition.
- To rename a target without changing its definition, send its current expression, available as
filterTglfrom the details operation. Part labels are not included infilterTgl, so a rename sent this way removes them. - Idempotent: repeating the same request leaves the target in the same state.
- No concurrency control: when two clients update the same target at the same time, the last request processed wins.
- Shared workspaces: only the workspace owner changes the target itself. In a workspace that is shared with you, the new expression is saved as your personal version of the target, which the owner and other users do not see, and the name does not change.
elementIdmust identify a target: the id of any other element is rejected withWS_ERR_102.
Targets accept only a subset of TGL: category references, comparisons and ranges on numeric variables, AND, OR and NOT(...). A variable on its own (for example SEX) is rejected, and XOR is saved as OR. See the TGL guide.
6. User variables
GET /api/v2/workspace/{workspaceId}/survey/{surveyCode}/user-vars returns the user variables saved in a workspace, with their folders and, for categorical user variables, their categories (CUSTOM_CAT). To tabulate one, put its id and subtype in a VARIABLES axis with type: CUSTOM_VAR.
- All the user variables of the workspace are returned, whatever the survey:
surveyCodedoes not filter them and their validity is not checked. To know which ones can be used with a survey, query the custom tree withvalidate=trueand readstatus(see Exploring variables and carriers). - Pick the user variables by
type: CUSTOM_VAR: the response currently also contains the root folder of the workspace's targets. - Folders have no
id.
7. Delete workspaces and elements
Two operations delete data you own. A successful delete answers 204 with no body.
| To | Use |
|---|---|
| Delete a workspace and everything in it | DELETE /api/v2/workspace/{workspaceId} |
| Delete one element of a workspace | DELETE /api/v2/workspace/{workspaceId}/element/{elementId} |
curl -X DELETE "https://<host>/api/v2/workspace/<workspaceId>/element/<elementId>" \
-H "X-API-Key: <your-api-key>"
A delete is physical and cannot be undone, exactly as in the TOM web application. There is no trash and no confirmation step.
Delete a workspace. It removes everything the workspace contains: its elements, the folders and the menu, the attached surveys, the settings and the survey groups, together with its shares. The users the workspace was shared with lose access to it without notice.
Delete an element. You can delete tabulations, Reach tables, targets, user variables and saved evaluations. The element also disappears from the menu of the workspace. Folders and the workspace menu, maps and any other type cannot be deleted: the answer is 400 AE_ERR_420, and nothing is deleted.
- The
idof a saved evaluation is the one returned byPOST /api/v2/survey/{surveyCode}/evaluation/save/{workspaceId}when you saved it. Saved evaluations are not listed afterwards, so keep thatidif you want to delete the evaluation later. - Only the owner can delete. In a workspace shared with you (
SHARED_WITH_ME), deleting the workspace or any of its elements answers403AE_ERR_418. A workspace you own and share (SHARED_BY_ME) can be deleted. - Dependencies are not checked. If you delete a target that a saved evaluation or a table uses, the delete succeeds and those elements keep their saved result unchanged.
- No application module is required: being the owner is enough, including for saved evaluations.
- A workspace that does not exist, that you cannot see or that is already deleted gives the same
404AE_ERR_417. An element that does not exist in that workspace, that lives in another workspace or that is already deleted gives404AE_ERR_419. Repeating a delete therefore answers404. - The checks run in a fixed order and stop at the first failure: workspace (
404), owner (403), element (404), element type (400). For example, an element that does not exist in a workspace shared with you gives403, not404. - If another client deletes the same resource at the same moment, you get
404or204, never a400or a500. In both cases the resource no longer exists.
8. Errors
Status and errorCode | Cause |
|---|---|
400 WS_ERR_101 | The workspace does not exist (add a survey, create a target, save an evaluation). |
400 WS_ERR_102 | The workspace has no target with that elementId, or the element is not a target. |
400 WS_ERR_403 | The workspace is neither owned by nor shared with the user, or, for writes, is not owned by the user. |
400 TREE_ERR_404 | The workspace does not exist (user variables and targets lists). |
400 AE_ERR_401 | A type value of the workspace lists that is not an element type. |
400 TGL_ERR_101 | The expression references a variable or category that does not exist in the survey. |
422 TGL_INVALID | The expression cannot be parsed, or uses a variable without a category or a condition. |
400 VAL_ERR_001 | A required field is missing or empty (name of a workspace, code of a survey, label or tgl of a target), or a text is too long. |
400 TB_ERR_104 | None of the variables of a saved tabulation is in the survey (get an element, saved tabulations). |
400 AE_ERR_400 | The body is a JSON array, or a value has the wrong JSON type, for example an array in name or an object in tgl (create a workspace, add a survey, create or update a target, target details). The message names the field. |
404 AE_ERR_404, AE_ERR_406 | The element, or the target of an element, does not exist. |
404 AE_ERR_417 | The workspace does not exist, is not visible to the user or was already deleted (delete operations). |
403 AE_ERR_418 | The workspace is shared with the user, not owned by them (delete operations). |
404 AE_ERR_419 | The element does not exist in the workspace, or was already deleted (delete an element). |
400 AE_ERR_420 | The type of the element cannot be deleted: a folder, the menu, a map or another type (delete an element). |
403 AE_ERR_407 | The target exists but the user cannot see it. |
500 GEN_ERR_500 | Unexpected error, including a workspaceId that does not exist in the get-workspace operation. |