Type at least two letters.

    ↑ ↓ to moveEnter to open

    Asynchronous audits

    Audits never run inside a request. Start one, poll it with Retry-After, read the results; schedule and repeat.

    Updated

    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

    1. POST /audit-runs answers 202 Accepted with the run in status queued, a Location header pointing at the run, and Retry-After: 5.
    2. Poll GET /audit-runs/{runId}. While the status is queued or running, the response carries Retry-After: wait that many seconds before the next call.
    3. When the status is succeeded, partial or failed, stop polling and read GET /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.