Asynchronous audits
Audits never run inside a request. Start one, poll it with Retry-After, read the results; schedule and repeat.
An audit can take from a few seconds to about a minute, and Metricevo paces its outgoing requests through a queue. So the API never makes you wait on an audit: starting one stores it, puts it on the queue and answers at once.
The flow
POST /audit-runsanswers202 Acceptedwith the run in statusqueued, aLocationheader pointing at the run, andRetry-After: 5.- Poll
GET /audit-runs/{runId}. While the status isqueuedorrunning, the response carriesRetry-After: wait that many seconds before the next call. - When the status is
succeeded,partialorfailed, stop polling and readGET /audit-runs/{runId}/observations.
curl -i -X POST "$METRICEVO_API/audit-runs" \
-H "Authorization: Bearer $METRICEVO_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: $(uuidgen)" \
-d '{"siteId":"site_01JC9Z0000000000000000000"}'
HTTP/1.1 202 Accepted
Location: /api/v1/audit-runs/run_01JCA40000000000000000000
Retry-After: 5
{ "id": "run_01JCA40000000000000000000", "status": "queued", ... }
Run statuses
| Status | Final? | What to do |
|---|---|---|
queued |
No | Wait Retry-After seconds, poll again. |
running |
No | Wait Retry-After seconds, poll again. |
succeeded |
Yes | Read the observations. |
partial |
Yes | Read the observations; some are failed (not measured). |
failed |
Yes | Read errorCode: url_policy_denied, too_many_redirects, timed_out or internal_error. |
Poll politely: honour Retry-After, and stop after a few minutes. A run that has not finished after its retries ends as failed with timed_out, so you never poll forever.
Idempotency
POST /audit-runs requires an Idempotency-Key header: a unique string of at most 255 characters, a UUID works well.
- The same key again returns the same run instead of starting a second audit. A retry after a timeout or a dropped connection is safe.
- A key already used for another site is refused with
409 idempotency_conflict. - No key, or a key over 255 characters:
400 idempotency_key_required.
Use a new key for each audit you mean to start.
One audit at a time per site
A site can have one waiting or running run. Starting another answers 409 run_in_progress, and the body has the runId of the existing run, so you can poll that one instead:
{ "code": "run_in_progress", "runId": "run_01JCA40000000000000000000", ... }
Start later
Send scheduledFor, an ISO 8601 time within the next 90 days. The run is created at once with status queued and starts within five minutes of that time. A time less than a minute away starts now.
{ "siteId": "site_01JC9Z0000000000000000000", "scheduledFor": "2026-12-01T06:00:00Z" }
Repeat
Repeating is a property of the site, not of a run:
curl -X PATCH "$METRICEVO_API/sites/$SITE_ID" \
-H "Authorization: Bearer $METRICEVO_API_KEY" \
-H "Content-Type: application/json" \
-d '{"schedule":{"frequency":"weekly"}}'
frequency is weekly, monthly or none. The first repeated run starts one period after you set it; the site’s schedule.nextRunAt says when. Repeated runs have triggerType: scheduled.
Read the results
curl "$METRICEVO_API/audit-runs/$RUN_ID/observations?status=fail" \
-H "Authorization: Bearer $METRICEVO_API_KEY"
Filters: status (pass, fail, no_data, not_tested, failed) and area. The run itself also carries a per-area summary with counts, enough for a dashboard without reading every observation.
To list runs: GET /audit-runs, newest first, filtered by siteId or status. See Pagination.