GET /api/audits

Cosa fa questo endpoint

GET /api/audits restituisce gli audit più recenti per l’account autenticato, deduplicati per URL. Se hai auditato lo stesso URL dieci volte, ricevi una riga indietro: l’ultima. La lista è ordinata per la posizione di display salvata dall’utente (impostata nella dashboard) e poi per created_at discendente.

• Deduplicato per URL: una riga per URL unico.
• Ordinato per display_position ASC NULLS LAST, created_at DESC.
• Restituisce fino a 100 righe per default. Niente parametri limit o offset in v1; la dashboard recupera la stessa forma.
• Economico e idempotente: nessun costo di piano, niente PSI, nessuna chiamata al crawler.

Perché è importante

Questo è l’endpoint che una dashboard, digest settimanale, o dashboard CI colpisce per primo. Restituisce ogni URL a cui l’account tiene con il suo ultimo punteggio, pronto per essere linkato a GET /api/audits/:id per la busta completa o a POST /api/audits per mettere in coda una nuova esecuzione.

Flussi concreti:

• Uno zap Zapier settimanale chiama GET /api/audits, confronta i punteggi con lo snapshot della settimana scorsa in Airtable, e posta un messaggio Slack per ogni URL che è calato di più di 5 punti.
• Una dashboard CI interna polla l’endpoint ogni minuto e renderizza una griglia di stato chiavata per display_position così le pagine più importanti appaiono per prime.

Come usarlo

Auth Bearer obbligatoria. Nessun parametro di query.

Richiesta

GET /api/audits HTTP/1.1
Host: app.metricspot.com
Authorization: Bearer ms_live_xxxxxxxxxxxxxxxxxxxxxxxx

curl

curl https://app.metricspot.com/api/audits \
  -H "authorization: Bearer ms_live_xxxxxxxxxxxxxxxxxxxxxxxx"

Node fetch

const res = await fetch("https://app.metricspot.com/api/audits", {
  headers: { authorization: "Bearer ms_live_xxxxxxxxxxxxxxxxxxxxxxxx" },
});
const { audits } = await res.json();
for (const a of audits) {
  console.log(a.score, a.url);
}

Python httpx

import httpx

r = httpx.get(
    "https://app.metricspot.com/api/audits",
    headers={"authorization": "Bearer ms_live_xxxxxxxxxxxxxxxxxxxxxxxx"},
    timeout=30.0,
)
for a in r.json()["audits"]:
    print(f"{a['score'] or '..'} {a['url']} ({a['status']})")

Risposta

200 OK:

{
  "audits": [
    {
      "id": 12345,
      "domain": "example.com",
      "url": "https://example.com",
      "status": "completed",
      "score": 78,
      "created_at": "2026-05-14T10:18:04.000Z",
      "completed_at": "2026-05-14T10:18:24.000Z",
      "display_position": 0
    },
    {
      "id": 12321,
      "domain": "example.com",
      "url": "https://example.com/pricing",
      "status": "completed",
      "score": 71,
      "created_at": "2026-05-13T09:02:11.000Z",
      "completed_at": "2026-05-13T09:02:34.000Z",
      "display_position": 1
    }
  ]
}

Campi per riga:

• id: id intero dell’audit, usato in chiamate successive.
• domain: hostname.
• url: URL completo auditato.
• status: uno di queued, running, completed, failed.
• score: intero 0 a 100, o null mentre in coda o in esecuzione.
• created_at: timestamp ISO 8601.
• completed_at: timestamp ISO 8601, o null se non ancora completo.
• display_position: rank intero impostato nella dashboard via drag-and-drop, o null se l’utente non ha riordinato. L’endpoint ordina per questo per primo.

L’endpoint restituisce sempre {"audits": [...]}. Non c’è busta di paginazione; il tetto è 100 righe. Usa POST /api/audits seguito da GET /api/audits/:id per dettaglio completo per audit.

Busta di errore

{ "error": "Unauthorized" }

Errori comuni

Codice	Quando	Azione
UNAUTHORIZED (401)	Bearer mancante o non valido	Genera una chiave su app.metricspot.com/settings/api-keys
UPSTREAM_FAILED (5xx)	Glitch del database	Riprova con backoff

L’endpoint non restituisce mai 404 o 429: è una lista delle tue risorse senza rate limit oltre il tuo piano.

Domande frequenti

Perché la lista è deduplicata per URL?

La dashboard mostra una card per URL: riauditare lo stesso URL sostituisce il punteggio della card precedente. L’API rispecchia quella vista esattamente così un’UI di terze parti può renderizzare la stessa lista senza reimplementare la deduplica.

Come ottengo ogni audit (incluse le esecuzioni più vecchie dello stesso URL)?

Usa l’endpoint di storia per URL esposto nel dettaglio dell’audit. L’endpoint di lista è intenzionalmente la vista “ultima per URL” perché è quello che dashboard e digest hanno bisogno. Una revisione futura potrebbe esporre una storia piatta non-paginata.

display_position è editabile via API?

Sì, indirettamente: il drag-and-drop della dashboard mappa a un endpoint di reorder separato che riceve un array di URL nel nuovo ordine. L’endpoint di lista legge le posizioni salvate; non scrive.

Questo conta contro quota del piano?

No. L’endpoint di lista è non-misurato. Solo POST /api/audits (e solo in successo) decrementa il contatore mensile.