Waiting and polling

A check takes time: a quick check usually finishes within a minute, standard in 1 to 3 minutes, deep in 20 to 40 minutes. You choose whether the create request waits.

Without Prefer: answer at once

POST /v1/checks answers 202 Accepted right away. The Location header has the path of the check, for example /v1/checks/chk_01M702VXG09GHG9EXG33H2V0BY, and the body has its current state (queued or running).

With Prefer: wait=N: wait up to N seconds

Prefer: wait=25

The API holds the request for up to N seconds (at most 30; larger values are cut to 30).

• If the check finishes in time: 201 Created with every cohort's result, and Preference-Applied: wait=….
• If not: 202 Accepted with Location and the state so far. Poll from there.
• If the check is cancelled during the wait: 202 with status: "cancelled". A 201 always means every cohort has a result.

Polling

curl https://api.linkspect.com/v1/checks/chk_01M702VXG09GHG9EXG33H2V0BY \
  -H "Authorization: Bearer $LINKSPECT_KEY"

The check's status is queued, running, completed or cancelled. While it runs, finished cohorts already have results. A cohort with final: true will not change any more, so you can show it straight away. Stop polling when the check is completed or cancelled.

Poll at a pace that fits the profile, every few seconds for quick, and keep an eye on your rate limit.

Cancelling

POST /v1/checks/{id}:cancel stops the unfinished cohorts. They become cancelled and are not charged; finished cohorts keep their results. Cancelling a check that is already finished changes nothing.