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 at1.stats: aggregated statistics of the plan (see below).carriers: the insertions assigned to each carrier, identified by the sameidas 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 aBUDGETobjective),costPerGrp,cpmContacts,coverMaxandtotalInsertions. The other fields of the schema are not currently returned. -
totalIterations: the number of iterations the engine executed. Only the last ones are returned inplans. -
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 addingminMarginalCoverage), 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 avaluegreater than0, at the final plan:type,target(the requestedvalue),achieved,completedPercent(achieved/target× 100, which can exceed 100) andreached(achievedat leasttarget). More than one objective can be reached at once.
When there is no result
| Job status | HTTP status | errorCode |
|---|---|---|
QUEUED, RUNNING | 409 | AE_ERR_412 |
FAILED, CANCELLED | 409 | AE_ERR_413 |
EXPIRED | 410 | AE_ERR_414 |
| Unknown, owned by another user, or deleted | 404 | JOB_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 code | Cause | What to do |
|---|---|---|
PO_ERR_100 | The 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_101 | The engine could not be reached or answered with an error. | Submit again later. |
PO_ERR_102 | The engine did not complete any iteration. | Review the definition and submit again. |
PO_ERR_104 | Iterations 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_ERROR | Infrastructure failure. | Submit again. |
The list is not exhaustive: codes from the platform can also appear.
Errors
| Status | errorCode | When |
|---|---|---|
| 401 | E401 | The X-API-Key header is missing or empty. |
| 403 | AE_ERR_408 | The user does not have the Study module. |
| 404 | JOB_NOT_FOUND | See above. |
| 409 | AE_ERR_412, AE_ERR_413 | See above. |
| 410 | AE_ERR_414 | See above. |
| 500 | AE_ERR_500, GEN_ERR_500 | The stored result could not be read. Retry later. |
Request
Responses
- 200
- 401
- 403
- 404
- 409
- 410
- 500
The result of the job: the last (up to) three plans, oldest first, plus totalIterations, stopReason and objectives.
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 job does not exist, belongs to another user, or was deleted. These cases cannot be told apart (JOB_NOT_FOUND).
The job has no result: it has not finished yet (AE_ERR_412), or it failed or was cancelled (AE_ERR_413).
The job succeeded, but its result was deleted 30 days after the job finished (AE_ERR_414).
The stored result could not be read (AE_ERR_500), or another unexpected error (GEN_ERR_500). Retry later.