Skip to main content
/v1/resolve, /v1/circle, /v1/edge and /v1/paths each start a job. When its answer is ready within 30 seconds of the call, the call answers with it; otherwise it answers 202 with the job:
The answer is then read with /v1/job, passing job.id as given. A 202 can also come sooner.
Every 202 of a job carries the same id: polling returns it until the answer is ready, never a new one.
Set a client timeout of at least 60 seconds. A client that gives up first never sees the job id, and sending the call again starts a new job, reserved and charged again. Poll every 3 seconds for the first 10 polls, then every 10 seconds. A job’s answer is the body and status the call would have answered: a 200, or an error such as 400 same_person or 422 ambiguous_person with candidates.
A job that failed is answered 200 { "job": { "id": …, "status": "FAILED" } }. It is final, not a signal to retry the poll: polling again returns the same. Send the original call again to start a new job.
A 503 unavailable on a poll means the job’s state could not be read this time, not that the job failed. Poll again, backing off. A job older than 24 hours that keeps answering 503 may never answer.
A circle, edge or paths answer that carries a body (a 200, or 422 ambiguous_person with candidates) is kept for 14 days; after that a poll is answered 410 result_unavailable. Other job answers are kept longer. A job that did not start, or made no progress, for 24 hours is answered 410 result_unavailable too.