Skip to main content

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​

  1. Submit the definition with this endpoint and keep the jobId from the response.
  2. Poll GET /api/v2/optimizations/{jobId}, waiting at least retryAfterSeconds between calls, until status is SUCCEEDED, FAILED, CANCELLED or EXPIRED.
  3. If status is SUCCEEDED, read the plans with GET /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​

FieldSource
surveyCode (path)code of a survey from GET /api/v2/users/surveys.
workspaceIdid of one of your workspaces from GET /api/v2/workspaces. The engine uses it as calculation context and to price the carriers.
carriers[].idid of a carrier (an item with type: CARRIER) from GET /api/v2/survey/{surveyCode}/carriers.
target.idid of a saved target from GET /api/v2/workspace/{workspaceId}/survey/{surveyCode}/targets.
target.filterTglAn inline TGL expression; see the TGL guide.
targetBase.idid of a saved target, from the same list as target.id.
targetBase.filterTglAn 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. Default 0.
    • maxInsertions: maximum insertions in the plan; must not be lower than minInsertions. Default: no limit.
    • step: insertions added each time the engine selects the carrier. Default 1; must be greater than 0.
    • mandatory: true makes the carrier receive at least one insertion. Default false.
    • price: net price per insertion. It replaces the price configured in the workspace; 0 counts 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 a type and a value.

    typeReached whenCompared with
    BUDGETthe net cost of the plan reaches valuestats.cost
    COVERAGEthe coverage reaches value, in the same unit as stats.coverstats.cover
    COVERAGE_PERCENTthe coverage percentage reaches value (at most 100)stats.coverPercent
    GRPthe GRPs reach valuestats.grp
    CONTACTSthe contacts reach value, in the same unit as stats.contactsstats.contacts

    The 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 value greater than 0: a value of 0 or less is accepted but never stops the run. Send each type once; if a type is repeated, its last value is used.

  • minMarginalCoverage: minimum coverage gain, in percentage points of coverPercent, that an insertion must add to be chosen. From 0 to 100; default 0 (no minimum). When no insertion reaches it, the run stops with stopReason NO_FURTHER_IMPROVEMENT.

  • target: the target audience, a filter: the calculation counts only the people it selects. Identify it by id (a saved target) or by filterTgl (an inline TGL expression), never both.

  • targetBase: the population base, the reference universe of the percentages. It has the same shape and rules as target and 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 code PO_ERR_100). Wait until the previous job reaches a terminal status before you submit the next one.
  • Queue. Accepted jobs stay QUEUED until 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 returns 429.
  • Duration. A run stops after 3600 seconds of execution; time spent QUEUED does not count. It still returns the plans found so far, with stopReason DURATION_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 to QUEUED.
  • 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​

StatuserrorCodeWhen
400AE_ERR_410No candidate carrier.
400AE_ERR_409No objective.
400AE_ERR_401criterion or an objective type is missing or unknown; the message lists the valid values.
400AE_ERR_411target or targetBase with both or neither of id and filterTgl. The message names the field.
400AE_ERR_400An 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.
400E400The body is not valid JSON.
401E401The X-API-Key header is missing or empty.
403AE_ERR_408The user does not have the Study module.
429JOB_USER_LIMIT_REACHEDThe user already has the maximum number of queued background jobs.
500AE_ERR_500, GEN_ERR_500Unexpected 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​

Accepted. The job was created with status QUEUED. Use jobId to poll GET /api/v2/optimizations/{jobId}.