API de mediciones de solo lectura

Lleva tus datos de visibilidad en IA a tus propios paneles, hojas de cálculo o informes de agencia. JSON o CSV, una clave por integración y solo los datos de tu espacio de trabajo.

Autenticación

Crea una clave en Cuenta, Claves de API (solo propietarios del espacio de trabajo). Envíala como token Bearer. La clave completa se muestra una vez; solo guardamos un hash. Las claves revocadas dejan de funcionar en la siguiente solicitud.

curl -H "Authorization: Bearer aeo_YOUR_KEY" \
  "https://YOUR-AEODA-DOMAIN/api/v1/brands/BRAND_ID/scores?from=2026-09-01&limit=50"

# CSV
curl -H "Authorization: Bearer aeo_YOUR_KEY" -o scores.csv \
  "https://YOUR-AEODA-DOMAIN/api/v1/brands/BRAND_ID/scores?format=csv&delimiter=semicolon"

Planes

La API se incluye en Pro y Agency; la exportación CSV, desde Starter. Si se baja de plan, las claves existentes responden 403 hasta que el espacio de trabajo vuelva a mejorar.

Si se baja de plan, las claves quedan suspendidas y responden 403; vuelven a funcionar en cuanto el espacio de trabajo mejora. Las claves no se eliminan.

Endpoints

Todos los endpoints son GET y de solo lectura. URL base: tu dominio de aeoda.

Endpoint	Devuelve
GET /api/v1/brands	Tus marcas (id, nombre, dominio, mercado).
GET /api/v1/brands/{brandId}/scores	Historial de puntuación: fecha, motor, puntuación, rango de confianza, tasa de menciones.
GET /api/v1/brands/{brandId}/answers	Respuestas: prompt, motor, mencionada o no, posición, sentimiento, competidores, texto.
GET /api/v1/brands/{brandId}/sources	Fuentes citadas: dominio, URL, número de respuestas, propia o competidor.
GET /api/v1/brands/{brandId}/competitors	Comparación con competidores: marca, puntuación, cuota de voz.
GET /api/v1/brands/{brandId}/recommendations	Plan de acción: título, prioridad, esfuerzo, estado.

Parámetros de consulta

from y to: fechas como YYYY-MM-DD (por defecto, últimos 30 días, limitado por el historial de tu plan). limit: de 1 a 1000 (por defecto 100). cursor: el valor nextCursor de la página anterior. format: json (por defecto) o csv. delimiter: comma o semicolon (CSV). lang: idioma de los títulos de recomendaciones. Los parámetros desconocidos devuelven 400.

Ejemplo

{
  "data": [
    {
      "brand": "Northwind Coffee",
      "date": "2026-10-01T09:00:00.000Z",
      "engine": "all",
      "score": 55,
      "ci_low": 40,
      "ci_high": 70,
      "mention_rate": 25,
      "sov": 31.5,
      "avg_position": 2.4
    }
  ],
  "nextCursor": "eyJ0IjoiMjAyNi0xMC0wMSAwOTowMDowMCswMCIsImlkIjoiLi4uIn0",
  "range": { "from": "2026-09-01", "to": "2026-10-18" }
}

Formato CSV

El CSV es UTF-8 con marca de orden de bytes para que Excel abra bien los acentos. Las celdas de texto que empiezan por = + - @ llevan un apóstrofo para evitar la inyección de fórmulas. Las respuestas CSV se envían en flujo y están limitadas a 100 000 filas: si llegas al límite (413), reduce el rango de fechas.

Límites de uso y paginación

Cada clave permite 60 solicitudes por minuto. Las respuestas incluyen x-ratelimit-limit y x-ratelimit-remaining; un 429 incluye retry-after. Las listas JSON se paginan con nextCursor (null en la última página).

format=csv tiene su propio límite, más bajo: 6 descargas por hora y clave, y una respuesta se limita a 50 MB (una última línea "# truncated" marca un archivo cortado).

Errores

401Clave ausente, mal formada o revocada.
403El plan del espacio de trabajo no incluye la API.
404La marca no existe en tu espacio de trabajo.
413Límite de filas CSV superado: usa un rango de fechas más corto.
429Límite de uso alcanzado: espera los segundos de retry-after.