Skip to main content

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​

statusTerminalMeaningNext step
QUEUEDNoAccepted and waiting for a free execution slot.Poll again after retryAfterSeconds.
RUNNINGNoThe engine is calculating.Poll again after retryAfterSeconds.
SUCCEEDEDYesFinished with at least one plan.GET .../result returns 200.
FAILEDYesFinished 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.
CANCELLEDYesCancelled outside this API, for example by the user in the TOM web application.GET .../result returns 409 AE_ERR_413.
EXPIREDYesFinished 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 RUNNING job returns to QUEUED when the platform reschedules it (engine at capacity, infrastructure failure). It then runs again from the beginning.
  • A FAILED job returns to QUEUED if the user retries it from the TOM web application. The jobId stays the same.

Always act on the latest status you read.

Polling​

  • Wait at least retryAfterSeconds between 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.
  • createdAt is when the job was accepted. finishedAt is present only in terminal statuses: it is when the job finished (for EXPIRED, 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​

StatuserrorCodeWhen
401E401The X-API-Key header is missing or empty.
403AE_ERR_408The user does not have the Study module.
404JOB_NOT_FOUNDThe id does not exist, belongs to another user, or was deleted. These cases cannot be told apart.
500AE_ERR_500, GEN_ERR_500Unexpected error. Retry later.

Request​

Responses​

The current status of the job. retryAfterSeconds is present only while the job is QUEUED or RUNNING, and finishedAt only in terminal statuses.