GET /api/audits

Qué hace este endpoint

GET /api/audits devuelve las auditorías más recientes de la cuenta autenticada, deduplicadas por URL. Si auditaste la misma URL diez veces, obtienes una fila: la última. La lista se ordena por la posición que el usuario guarda en el panel y luego por created_at descendente.

• Deduplicada por URL: una fila por URL única.
• Ordenada por display_position ASC NULLS LAST, created_at DESC.
• Devuelve hasta 100 filas por defecto. Sin parámetros limit o offset en v1; el panel oficial consume la misma forma.
• Barato e idempotente: sin coste de plan, sin PSI, sin llamada al crawler.

Por qué importa

Es el endpoint que toca primero un panel, un digest semanal o un dashboard CI. Te da cada URL que le interesa a la cuenta con su puntuación más reciente, lista para enlazar a GET /api/audits/:id o relanzarse con POST /api/audits.

Workflows concretos:

• Un zap semanal llama a GET /api/audits, calcula deltas frente al snapshot anterior en Airtable y manda un mensaje a Slack por cada URL que pierda más de 5 puntos.
• Un dashboard CI interno hace polling cada minuto y pinta una rejilla de estado ordenada por display_position, dejando arriba las páginas más críticas.

Cómo usarlo

Bearer obligatorio. Sin parámetros de query.

Petición

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

Respuesta

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

Campos por fila:

• id: id entero de auditoría, usado en llamadas posteriores.
• domain: hostname.
• url: URL completa auditada.
• status: uno de queued, running, completed, failed.
• score: entero 0 a 100, o null mientras está en cola o ejecutándose.
• created_at: timestamp ISO 8601.
• completed_at: timestamp ISO 8601, o null si todavía no terminó.
• display_position: rango entero fijado en el panel con drag-and-drop, o null si el usuario no reordenó. El endpoint ordena primero por este campo.

El endpoint siempre devuelve {"audits": [...]}. No hay envoltorio de paginación; el tope son 100 filas. Usa POST /api/audits y luego GET /api/audits/:id para el detalle completo por auditoría.

Envoltorio de error

{ "error": "Unauthorized" }

Errores comunes

Código	Cuándo	Acción
UNAUTHORIZED (401)	Bearer ausente o inválido	Crea una clave en app.metricspot.com/settings/api-keys
UPSTREAM_FAILED (5xx)	Tropiezo de base de datos	Reintenta una vez con backoff

El endpoint nunca devuelve 404 ni 429: es una lista de tus propios recursos sin rate limit más allá del plan.

Preguntas frecuentes

¿Por qué se deduplica por URL?

El panel muestra una tarjeta por URL: reauditar la misma URL reemplaza la puntuación de la tarjeta anterior. La API refleja esa vista exactamente para que una UI de terceros pinte la misma lista sin tener que reimplementar la deduplicación.

¿Cómo obtengo cada auditoría, incluidos runs antiguos de la misma URL?

Usa el endpoint de historial por URL expuesto en el detalle de cada auditoría. La lista está pensada como “última por URL” porque eso es lo que necesitan paneles y digests. Una revisión futura puede exponer el historial plano sin paginar.

¿Es display_position editable por API?

Sí, indirectamente: el drag-and-drop del panel mapea a un endpoint de reorden separado que recibe un array de URLs en el nuevo orden. La lista lee las posiciones guardadas; no las escribe.

¿Consume cupo del plan?

No. El endpoint de listado no consume. Solo POST /api/audits (y solo con éxito) decrementa el contador mensual.