Get the status of an optimization
GET/api/v2/optimizations/:jobId
Returns the current status of a media plan optimization job, with the timestamps of its life cycle.
The job is created with POST /api/v2/survey/{surveyCode}/optimizations. Poll this endpoint until the job reaches a terminal status, then read the outcome with GET /api/v2/optimizations/{jobId}/result.
The response contains only the status and its timestamps: it has no progress, iterations, partial plans or failure reason. The result call returns those.
Statuses
status | Terminal | Meaning | Next step |
|---|---|---|---|
QUEUED | No | Accepted and waiting for a free execution slot. | Poll again after retryAfterSeconds. |
RUNNING | No | The engine is calculating. | Poll again after retryAfterSeconds. |
SUCCEEDED | Yes | Finished with at least one plan. | GET .../result returns 200. |
FAILED | Yes | Finished without a result: the definition was rejected when the job started, another optimization of the same user was active, or an engine or infrastructure error occurred. | GET .../result returns 409 AE_ERR_413 with the origin code. Fix the cause and submit a new job. |
CANCELLED | Yes | Cancelled outside this API, for example by the user in the TOM web application. | GET .../result returns 409 AE_ERR_413. |
EXPIRED | Yes | Finished successfully, but its result was deleted after the retention period. | GET .../result returns 410 AE_ERR_414. Submit the optimization again if you still need it. |
The usual sequence is QUEUED to RUNNING to SUCCEEDED, FAILED or CANCELLED, and later SUCCEEDED to EXPIRED. A job can also be cancelled while it is still QUEUED. The status can also go back:
- A
RUNNINGjob returns toQUEUEDwhen the platform reschedules it (engine at capacity, infrastructure failure). It then runs again from the beginning. - A
FAILEDjob returns toQUEUEDif the user retries it from the TOM web application. ThejobIdstays the same.
Always act on the latest status you read.
Polling
- Wait at least
retryAfterSecondsbetween two calls. It is a fixed recommendation (currently 30 seconds), not an estimate of the remaining time, and it is present only while the job is not terminal. createdAtis when the job was accepted.finishedAtis present only in terminal statuses: it is when the job finished (forEXPIRED, when it succeeded).- The execution of a run is capped at one hour. Time spent
QUEUED, the preparation of the run and any restart come on top of that hour, so a job can take longer than one hour to reach a terminal status.
Lifetime
Jobs belong to the user of the API key. They also appear in the background-jobs panel of the TOM web application, where that user can cancel, retry or delete them. Results are kept for 30 days after the job finishes. After that, a SUCCEEDED job becomes EXPIRED, and FAILED or CANCELLED jobs are deleted (404). A job deleted from the TOM web application also returns 404.
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 | The id does not exist, belongs to another user, or was deleted. These cases cannot be told apart. |
| 500 | AE_ERR_500, GEN_ERR_500 | Unexpected error. Retry later. |
Request
Responses
- 200
- 401
- 403
- 404
- 500
The current status of the job. retryAfterSeconds is present only while the job is QUEUED or RUNNING, and finishedAt only in terminal statuses.
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).
Unexpected error (AE_ERR_500 or GEN_ERR_500). Retry later.