Jobs, waiting and retries
How long-running work runs as jobs, how to wait without polling, and how to retry safely with idempotency keys and ETags.
A POST returns the job and
its Location at once; a waiting GET reads it.
The four jobs
Section titled “The four jobs”- Start, then read
POST /,plans GET /plans/ {id} - Statuses
running(queued too),done,error- Running at once
- Your unfinished forecasts, up to
limits.plan_ unfinished_ forecasts - Kept
- Unsaved 90 days; saved until deleted
- Start, then read
POST /,exports GET /exports/ {id} - Statuses
queued,running,done,error,cancelled,expired- Running at once
- 20 per model set and 3 per plan by default
- Kept
- Its file for
limits.ttl_ hours
- Start, then read
POST /withforecasts async: true,GET /forecasts/ {id} - Statuses
running,done,error- Running at once
- 50 per company
- Kept
- An hour after it finishes
- Start, then read
POST /,plans/ {id}/ economics GET /plans/ {id}/ economics/ {job_ id} - Statuses
running,done,error- Running at once
- 4 per company
- Kept
- An hour after it finishes
Past a cap, retry after one finishes, or after Retry-After when given (codes).
Every job carries seconds, its run time. Plans report progress as a share done; exports the step, share, rows and
bytes.
Wait instead of polling
Section titled “Wait instead of polling”Add wait (1 to 25 seconds) to the job’s GET. It answers when the status changes or the time passes; a finished
job answers at once.
curl -sS --fail-with-body \ -H "Authorization: Bearer $NOVI_API_TOKEN" \ "$NOVI_API_BASE/plans/$PLAN_ID?wait=25"Set your client’s timeout above the wait, for example 60 seconds.
Links and Location
Section titled “Links and Location”Location, links.self and an export’s file.url are paths, such as /forecasts/api/v1/exports/<id>/file. Resolve
them against https://<your-company>.novilabs.io.
Retry safely with Idempotency-Key
Section titled “Retry safely with Idempotency-Key”These calls take an Idempotency-Key header: POST /plans, POST /exports, POST /plans/{id}/economics,
POST /forecast-sources, POST /area-sets, POST /saved/{collection}, and POST /forecasts with async: true
(otherwise the key is ignored).
- Send your own key, 1 to 128 letters, digits and
.,_,:or-, such as a UUID, on every retry of that request. - The same key with the same body within 24 hours (for an async forecast or plan economics job, while the job is
kept) returns what the first request made, with
Idempotent-Replayed: true, and starts nothing. - The same key with a different body is a conflict error with
details.fieldIdempotency-Key. - Only a request that succeeds records its key, so retry a server error or a lost response with the same key.
- Keys are per operation.
ETags and compression
Section titled “ETags and compression”Send a read’s ETag back as If-None-Match: when nothing changed, the answer is Not Modified, with no body.
| Read | Behavior |
|---|---|
Dataset reads, economics decks, GET / |
ETag |
A done or failed plan, GET / |
ETag |
A curve page, GET / |
ETag on each page |
| An export file | Strong ETag, Accept-Ranges: bytes; Range resumes and If-Range guards the resume |
Responses over 1 KB are gzipped when you send Accept-Encoding: gzip.
Paging
Section titled “Paging”Lists page with limit and an opaque cursor. Pass next_cursor back until it is null, with the same filters
and sort each time. On GET /plans, plans created or deleted between pages are neither skipped nor repeated.
Request ids
Section titled “Request ids”Every response carries X-Request-Id. Send your own to match your logs, and quote it when you ask Novi about a call.