Skip to main content

List the targets of a workspace

GET 

/api/v2/workspace/:workspaceId/survey/:surveyCode/targets

Returns the targets saved in a workspace, in the folder structure that the user sees in TOM.

A target is a saved audience definition: a name plus a TGL expression (see the TGL guide). Targets are stored in a workspace and can be reused by id in other requests. Use this operation to find those ids.

Before you call it​

  • workspaceId: the id of a workspace you own or that is shared with you, from GET /api/v2/workspaces.
  • surveyCode: a survey code from GET /api/v2/users/surveys, usually the workspace's own surveyCode. It does not filter the list (see Behaviour).

Response​

A JSON array of nodes, in the order shown in the workspace. Each node is one of:

typeWhat it isFields returned
TARGET_VARA saved target.id, label, type, subtype (always LOGIC)
FOLDERA folder that organises targets.label, type, items (its child nodes; omitted when the folder is empty). Folders have no id.

The workspace's root Targets folder is not returned: its children are the top-level elements of the array, except when the workspace has no targets, in which case the root Targets folder itself is returned. The array currently also contains the root folder of the workspace's user variables (a FOLDER without id, possibly with sub-folders).

Behaviour​

  • Every target in the workspace is returned, whatever surveyCode you send. Targets are not tied to a survey and are not checked against it here: a target that uses variables missing from a survey is still listed, and fails only when you use it with that survey.
  • The response carries ids and names only. To read a target's TGL expression and its creation and update dates, send its id to POST /api/v2/workspace/{workspaceId}/survey/{surveyCode}/targets/details.
  • GET /api/v2/workspace/{workspaceId} also lists the workspace's targets, as a flat list with dates and without folders.
  • Read-only and safe to retry.

Where to use a target id​

  • target.id and targetBase.id in POST /api/v2/survey/{surveyCode}/ranking, .../evaluation, .../evaluation/save/{workspaceId} and .../response-curve: the target is the audience and the base is the reference universe of the percentages.
  • target.id and targetBase.id in POST /api/v2/survey/{surveyCode}/optimizations: the target is the audience and the base is the reference universe of the percentages.
  • target.id in POST /api/v2/table/{surveyCode}, its /html variant and POST /api/v2/reach/{surveyCode}, to filter the whole table.
  • targetBase.id in POST /api/v2/table/{surveyCode}, its /html variant and POST /api/v2/reach/{surveyCode}, as the population base.
  • A TARGET_VAR item with id in a VARIABLES axis of POST /api/v2/table/{surveyCode} and POST /api/v2/reach/{surveyCode}.

Errors​

StatuserrorCodeWhen
400TREE_ERR_404No workspace exists with this workspaceId.
401E401The X-API-Key header is missing or empty.
500GEN_ERR_500Unexpected error.

Request​

Responses​

The workspace's targets and folders, as an array of nodes in workspace order.