Skip to main content

Get the result of an optimization

GET 

/api/v2/optimizations/:jobId/result

Returns the outcome of a succeeded optimization: the plans of the last (up to) three iterations, why the run stopped and the state of each objective.

It is available only for a job whose status is SUCCEEDED. Call it once GET /api/v2/optimizations/{jobId} reports SUCCEEDED; you can call it again until the result expires, 30 days after the job finished.

Response​

  • plans: one to three plans, oldest first; the last one is the final plan. Each plan has:

    • iteration: the iteration that produced it, starting at 1.
    • stats: aggregated statistics of the plan (see below).
    • carriers: the insertions assigned to each carrier, identified by the same id as in the request.
  • stats: every field is optional, so read only the ones present. Returned today: cover (coverage, as an absolute figure), coverPercent, grp, contacts, cost (net cost of the plan, the value compared with a BUDGET objective), costPerGrp, cpmContacts, coverMax and totalInsertions. The other fields of the schema are not currently returned.

  • totalIterations: the number of iterations the engine executed. Only the last ones are returned in plans.

  • stopReason: why the run stopped. Switch on this value; do not parse messages.

    stopReasonMeaning
    OBJECTIVE_REACHEDThe last plan reached at least one objective; see objectives.
    DURATION_CAP_REACHEDThe run was stopped after 3600 seconds of execution. The plans are the best found until then.
    NO_FURTHER_IMPROVEMENTThe engine could not improve the plan further: no insertion was left to add (every carrier at its maxInsertions, or no insertion adding minMarginalCoverage), or the engine reached its maximum number of iterations.
    ENGINE_ERRORThe run stopped for another reason after producing at least one plan. The plans are valid but may be far from the objectives; check objectives.
  • objectives: the state of each objective of the request with a value greater than 0, at the final plan: type, target (the requested value), achieved, completedPercent (achieved / target × 100, which can exceed 100) and reached (achieved at least target). More than one objective can be reached at once.

When there is no result​

Job statusHTTP statuserrorCode
QUEUED, RUNNING409AE_ERR_412
FAILED, CANCELLED409AE_ERR_413
EXPIRED410AE_ERR_414
Unknown, owned by another user, or deleted404JOB_NOT_FOUND

For a FAILED job, errorMessage contains the code of the original error in parentheses, for example The optimization job failed (PO_ERR_100). A CANCELLED job has no code. The most common codes are:

Origin codeCauseWhat to do
PO_ERR_100The engine rejected the definition when the job started: another optimization of the same user was active; no candidate carrier had a price (needed for BUDGET or COVERAGE_PER_CPM); a rule was broken (maxInsertions lower than minInsertions, step not greater than 0, COVERAGE_PERCENT above 100, minMarginalCoverage outside 0 to 100); or no objective had a value.Make sure no other optimization of the user is active, fix the definition and submit again.
PO_ERR_101The engine could not be reached or answered with an error.Submit again later.
PO_ERR_102The engine did not complete any iteration.Review the definition and submit again.
PO_ERR_104Iterations ran, but no plan could be read.Submit again.
TGL_ERR_..., TG_ERR_...The target or the base could not be resolved.Fix target or targetBase.
EXECUTOR_LOST, JOB_RETRY_LIMIT_REACHED, EXECUTOR_CHAIN_ERRORInfrastructure failure.Submit again.

The list is not exhaustive: codes from the platform can also appear.

Errors​

StatuserrorCodeWhen
401E401The X-API-Key header is missing or empty.
403AE_ERR_408The user does not have the Study module.
404JOB_NOT_FOUNDSee above.
409AE_ERR_412, AE_ERR_413See above.
410AE_ERR_414See above.
500AE_ERR_500, GEN_ERR_500The stored result could not be read. Retry later.

Request​

Responses​

The result of the job: the last (up to) three plans, oldest first, plus totalIterations, stopReason and objectives.