GET /api/audits

Què fa aquest endpoint

GET /api/audits retorna les auditories més recents del compte autenticat, deduplicades per URL. Si has auditat la mateixa URL deu vegades, en reps una fila: la més recent. La llista s’ordena per la posició de visualització desada per l’usuari (configurada al dashboard) i després per created_at descendent.

• Deduplicada per URL: una fila per URL única.
• Ordenada per display_position ASC NULLS LAST, created_at DESC.
• Retorna fins a 100 files per defecte. Sense paràmetres limit ni offset a la v1; el dashboard obté la mateixa forma.
• Econòmica i idempotent: sense cost de pla, sense PSI, sense crida al rastrejador.

Per què importa

Aquest és l’endpoint que un dashboard, un digest setmanal o un dashboard de CI consulten primer. Et dona totes les URLs que el compte segueix amb la seva darrera puntuació, llest per enllaçar amb GET /api/audits/:id per al sobre complet o amb POST /api/audits per encuar una nova execució.

Fluxos concrets:

• Un zap setmanal de Zapier crida GET /api/audits, compara puntuacions amb la instantània de la setmana passada a Airtable, i publica un missatge a Slack per cada URL que ha caigut més de 5 punts.
• Un dashboard intern de CI fa poll a l’endpoint cada minut i renderitza una graella d’estat ordenada per display_position perquè les pàgines més importants apareguin primer.

Com utilitzar-lo

Auth Bearer obligatòria. Sense paràmetres de consulta.

Petició

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']})")

Resposta

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
    }
  ]
}

Camps per fila:

• id: id enter de l’auditoria, utilitzat a les crides posteriors.
• domain: hostname.
• url: URL completa auditada.
• status: un de queued, running, completed, failed.
• score: enter de 0 a 100, o null mentre està encuada o en execució.
• created_at: timestamp ISO 8601.
• completed_at: timestamp ISO 8601, o null si encara no ha acabat.
• display_position: rang enter configurat al dashboard via drag-and-drop, o null si l’usuari no ha reordenat. L’endpoint ordena primer per aquest camp.

L’endpoint sempre retorna {"audits": [...]}. No hi ha sobre de paginació; el màxim són 100 files. Utilitza POST /api/audits seguit de GET /api/audits/:id per al detall complet per auditoria.

Sobre d’error

{ "error": "Unauthorized" }

Errors habituals

Codi	Quan	Acció
UNAUTHORIZED (401)	Token Bearer absent o invàlid	Emet una clau a app.metricspot.com/settings/api-keys
UPSTREAM_FAILED (5xx)	Petita aturada de base de dades	Reintenta un cop amb backoff

L’endpoint mai retorna 404 ni 429: és una llista dels teus propis recursos sense límit més enllà del teu pla.

Preguntes freqüents

Per què la llista està deduplicada per URL?

El dashboard mostra una targeta per URL: reauditar la mateixa URL substitueix la puntuació de la targeta anterior. L’API replica aquesta vista exactament perquè una UI de tercers pugui renderitzar la mateixa llista sense reimplementar la deduplicació.

Com obtinc totes les auditories (incloses execucions antigues de la mateixa URL)?

Utilitza l’endpoint d’historial per URL exposat al detall de l’auditoria. L’endpoint de llista és intencionadament la vista “darrera per URL” perquè és el que necessiten els dashboards i digests. Una revisió futura pot exposar un historial pla sense paginar.

Es pot editar display_position via API?

Sí, indirectament: el drag-and-drop del dashboard apunta a un endpoint de reordenació separat que rep un array d’URLs en el nou ordre. L’endpoint de llista llegeix les posicions desades; no les escriu.

Compta contra l’allocació del pla?

No. L’endpoint de llista no està comptabilitzat. Només POST /api/audits (i només en èxit) decrementa el comptador mensual.