Submit a media plan optimization
POST/api/v2/survey/:surveyCode/optimizations
Submits a media plan optimization for one survey and immediately returns a job identifier; the optimization itself runs in the background.
An optimization starts from a set of candidate carriers and adds insertions iteration by iteration. At each step it picks the insertion that best serves the criterion, until one of the objectives is reached or the plan cannot be improved any further. The result contains the plans of the last (up to) three iterations.
Workflow
- Submit the definition with this endpoint and keep the
jobIdfrom the response. - Poll
GET /api/v2/optimizations/{jobId}, waiting at leastretryAfterSecondsbetween calls, untilstatusisSUCCEEDED,FAILED,CANCELLEDorEXPIRED. - If
statusisSUCCEEDED, read the plans withGET /api/v2/optimizations/{jobId}/result. For any other terminal status, the same call returns the reason as an error.
Closing the connection after the 202 does not cancel the job. The jobId is a global key, so the follow-up calls do not include surveyCode.
Where the values come from
| Field | Source |
|---|---|
surveyCode (path) | code of a survey from GET /api/v2/users/surveys. |
workspaceId | id of one of your workspaces from GET /api/v2/workspaces. The engine uses it as calculation context and to price the carriers. |
carriers[].id | id of a carrier (an item with type: CARRIER) from GET /api/v2/survey/{surveyCode}/carriers. |
target.id | id of a saved target from GET /api/v2/workspace/{workspaceId}/survey/{surveyCode}/targets. |
target.filterTgl | An inline TGL expression; see the TGL guide. |
targetBase.id | id of a saved target, from the same list as target.id. |
targetBase.filterTgl | An inline TGL expression; see the TGL guide. |
Request fields
-
workspaceId(required): one of your workspaces (see the table above). Send it always: the engine takes the carrier prices from it. -
carriers(required, at least one): the candidate carriers. Each carrier accepts these optional constraints:minInsertions: minimum insertions in the plan. Default0.maxInsertions: maximum insertions in the plan; must not be lower thanminInsertions. Default: no limit.step: insertions added each time the engine selects the carrier. Default1; must be greater than0.mandatory:truemakes the carrier receive at least one insertion. Defaultfalse.price: net price per insertion. It replaces the price configured in the workspace;0counts as no price.
-
criterion(required): how the engine chooses the next insertion.COVERAGE: the insertion that adds the most coverage.COVERAGE_PER_CPM: the insertion that adds the most coverage per unit of cost. Requires prices (see Prices).
-
objectives(required, at least one): the stop conditions, each with atypeand avalue.typeReached when Compared with BUDGETthe net cost of the plan reaches valuestats.costCOVERAGEthe coverage reaches value, in the same unit asstats.coverstats.coverCOVERAGE_PERCENTthe coverage percentage reaches value(at most100)stats.coverPercentGRPthe GRPs reach valuestats.grpCONTACTSthe contacts reach value, in the same unit asstats.contactsstats.contactsThe run stops after the first iteration that reaches any objective, checked in the order of the table, so the final plan can go slightly past the value (for example, spend a little more than the budget). Use a
valuegreater than0: a value of0or less is accepted but never stops the run. Send eachtypeonce; if a type is repeated, its lastvalueis used. -
minMarginalCoverage: minimum coverage gain, in percentage points ofcoverPercent, that an insertion must add to be chosen. From0to100; default0(no minimum). When no insertion reaches it, the run stops withstopReasonNO_FURTHER_IMPROVEMENT. -
target: the target audience, a filter: the calculation counts only the people it selects. Identify it byid(a saved target) or byfilterTgl(an inline TGL expression), never both. -
targetBase: the population base, the reference universe of the percentages. It has the same shape and rules astargetand is independent of it: neither replaces the other.
If both are omitted, the optimization runs against the full universe of the survey.
Sending both id and filterTgl, or neither, on a present target or targetBase is a 400 (AE_ERR_411) whose message names the field. An unknown field anywhere in the request, a misspelled one included, is a 400 (AE_ERR_400) whose message names the field and the object that contains it.
The target and the base are resolved when the job runs, not when it is submitted: one that cannot be resolved is not a 400 here, the job ends FAILED.
Prices
BUDGET objectives and the COVERAGE_PER_CPM criterion need the cost of each insertion. A carrier's price is its price field or, if that is omitted, the price configured in the workspace. If none of the candidate carriers has a price, the job ends FAILED.
Validation
This endpoint checks only the structure of the request and answers 400 when it is wrong; only the first problem found is reported. The rest is checked when the job runs: a problem found then does not change this response, but the job ends FAILED, and the result call returns 409 (AE_ERR_413) with the origin code. This covers the rules above (maxInsertions not lower than minInsertions, step greater than 0, COVERAGE_PERCENT at most 100, minMarginalCoverage between 0 and 100), missing prices, a target or a base that cannot be resolved, and another active optimization of the same user.
Limits
- One optimization at a time per user. The engine runs one optimization at a time for each user (the owner of the API key), including optimizations open in the TOM web application. A job that starts while another optimization of the same user is active ends
FAILED(origin codePO_ERR_100). Wait until the previous job reaches a terminal status before you submit the next one. - Queue. Accepted jobs stay
QUEUEDuntil an execution slot is free; slots are shared by all users. Each user can have up to 50 queued background jobs of any kind, including exports started in the TOM web application. Beyond that, this endpoint returns429. - Duration. A run stops after 3600 seconds of execution; time spent
QUEUEDdoes not count. It still returns the plans found so far, withstopReasonDURATION_CAP_REACHED. - Not idempotent. Every accepted request creates a new job. Retrying a request that timed out can create a second job, which then competes with the first one (see the first limit).
- Restarts. If the platform has to reschedule a run (engine at capacity, infrastructure failure), the run starts again from the beginning with the same
jobId, and its status goes back toQUEUED. - No cancellation is available through this API, and there are no side effects: the result is data only, and nothing is written to a workspace or ranking.
Deprecated names
The older names are still accepted in requests and are never returned: supports for carriers, and tgl for filterTgl in target and targetBase. Do not send filterTgl and tgl in the same object: the last one in the body is used. Use the current names.
Errors
| Status | errorCode | When |
|---|---|---|
| 400 | AE_ERR_410 | No candidate carrier. |
| 400 | AE_ERR_409 | No objective. |
| 400 | AE_ERR_401 | criterion or an objective type is missing or unknown; the message lists the valid values. |
| 400 | AE_ERR_411 | target or targetBase with both or neither of id and filterTgl. The message names the field. |
| 400 | AE_ERR_400 | An unknown field in the request, in target, in targetBase, in a candidate carrier or in an objective. The message names the field and the object. |
| 400 | E400 | The body is not valid JSON. |
| 401 | E401 | The X-API-Key header is missing or empty. |
| 403 | AE_ERR_408 | The user does not have the Study module. |
| 429 | JOB_USER_LIMIT_REACHED | The user already has the maximum number of queued background jobs. |
| 500 | AE_ERR_500, GEN_ERR_500 | Unexpected failure while queuing the job. The job may or may not have been created, so a retry can create a duplicate. |
A value of the wrong type, such as text in a numeric field, is also rejected with 400; that response may carry no errorCode. Problems detected after the job is accepted are reported by the result call, not here.
Request
Responses
- 202
- 400
- 401
- 403
- 429
- 500
Accepted. The job was created with status QUEUED. Use jobId to poll GET /api/v2/optimizations/{jobId}.
The structure of the request is invalid; only the first problem found is reported. See the Errors table in the operation description for every errorCode. AE_ERR_411: target or targetBase with both or neither of id and filterTgl. AE_ERR_400: an unknown field.
The X-API-Key header is missing or empty.
The application module this operation needs is not enabled for the user, or the user's modules could not be resolved (AE_ERR_408).
The user already has the maximum number of queued background jobs, of any kind. Submit again when some have started or finished. The text of errorMessage is not part of the contract.
Unexpected failure while queuing the job (AE_ERR_500 or GEN_ERR_500). The job may or may not have been created, so a retry can create a duplicate.