Usar la API REST
La API REST de Searcherries da a scripts, hojas de cálculo y plataformas de automatización acceso de lectura a los datos que Searcherries ha recopilado para tus proyectos: métricas de visibilidad en IA, respuestas de IA almacenadas con sus valoraciones, competidores, URL y dominios citados, instantáneas de Google Search Console y Bing Webmaster Tools, instantáneas de tráfico de IA de GA4 y un plan de acción priorizado. Devuelve los mismos conjuntos de datos que la conexión MCP, como JSON sobre HTTPS.
La API es de solo lectura. No puede editar proyectos, cambiar preguntas, borrar datos, gestionar la facturación ni lanzar llamadas nuevas a los proveedores de analítica. Cada respuesta se construye con datos que Searcherries ya tiene almacenados, y cada una indica cuándo se obtuvieron esos datos. Lee sobre las actualizaciones de datos.
La API está disponible con acceso a un plan de pago, incluido un periodo de prueba activo que cumpla los requisitos.
URL base y formato
Todos los endpoints están bajo:
https://app.searcherries.com/api/v1Las peticiones usan GET con parámetros en la cadena de consulta. Las respuestas son documentos JSON. Los booleanos de la cadena de consulta aceptan true, false, 1 y 0. Las listas como include aceptan un valor separado por comas.
La descripción legible por máquinas de cada endpoint, parámetro y respuesta es un documento OpenAPI 3.1 en https://app.searcherries.com/openapi/v1.yaml. Impórtalo en un cliente de API o en una plataforma de integración para tener los endpoints listos para llamar.
Autenticarse
La API usa los tokens de acceso personal de la página MCP. Crea un token en la pestaña Other clients (Otros clientes) de MCP y envíalo como token bearer:
Authorization: Bearer YOUR_TOKENYOUR_TOKEN es un marcador de posición del valor que generaste. Un token creado para un cliente MCP también funciona con la API, y un token revocado en la página MCP deja de funcionar en todas partes a la vez. Una cuenta puede tener hasta cinco tokens activos; cada uno caduca en la fecha que muestra la tabla.
Una petición sin un token válido recibe 401. Un token de una cuenta sin acceso a un plan de pago recibe 403 con el código de error paid_plan_required.
Pruébala
Lista tus proyectos:
curl -H "Authorization: Bearer YOUR_TOKEN" https://app.searcherries.com/api/v1/projectsLa respuesta contiene el id numérico de cada proyecto. Úsalo para leer el resumen del proyecto:
curl -H "Authorization: Bearer YOUR_TOKEN" https://app.searcherries.com/api/v1/projects/123Sustituye 123 por el id de tu proyecto. La referencia de endpoints enumera todos los endpoints y parámetros.
Periodos
Los datos de visibilidad en IA (respuestas, competidores, citas, las métricas del resumen) usan periodos de informe anclados a la última comprobación completada: last_30_days (predeterminado), last_60_days, last_90_days, this_year y last_year. Un periodo sin historial suficiente recurre al más cercano disponible, y el objeto period de la respuesta indica qué periodo se usó.
Las fuentes conectadas (Google Search Console, Bing Webmaster Tools, GA4) se almacenan como ventanas móviles que terminan el día de la recopilación: 30d, 90d y 365d. Sus respuestas incluyen period, fetched_at e is_stale. Cuando una fuente o una ventana no tiene datos almacenados, la respuesta dice "available": false y explica el motivo en reason.
Paginación
Los conjuntos de datos que devuelven filas incluyen un objeto pagination:
{
"offset": 0,
"limit": 25,
"returned": 25,
"total": 112,
"has_more": true
}Pide la página siguiente con un offset mayor mientras has_more sea true. La página predeterminada tiene 25 filas y el máximo es 100 (50 para competidores). Las listas de las fuentes conectadas son la muestra principal almacenada, no una exportación exhaustiva.
Límites de peticiones
Cada cuenta puede hacer 60 peticiones por minuto en Starter y 120 en Pro. Cada respuesta incluye X-RateLimit-Limit y X-RateLimit-Remaining. Cuando se agota el presupuesto, la API responde 429 con una cabecera Retry-After y el mismo número de segundos en retry_after. Espera y vuelve a intentarlo; no reintentes en un bucle cerrado.
Errores
Cada error es un objeto JSON con una sola clave error:
{
"error": {
"code": "validation_failed",
"message": "The request parameters are invalid.",
"status": 422,
"errors": {
"period": ["The selected period is invalid."]
}
}
}| Estado | Código | Significado |
|---|---|---|
| 401 | unauthenticated | Token ausente, caducado o revocado. |
| 403 | insufficient_scope | El token no puede leer la API. Crea un token nuevo en la página MCP. |
| 403 | paid_plan_required | La cuenta no tiene acceso a un plan de pago. plans_url apunta a la página de planes. |
| 404 | not_found | El id del proyecto no existe o pertenece a otra cuenta. |
| 422 | validation_failed | Un parámetro no es válido; errors enumera los mensajes por parámetro. |
| 429 | rate_limited | El presupuesto por minuto está agotado; retry_after indica cuánto esperar. |
| 500 | server_error | Algo falló en el lado de Searcherries. Vuelve a intentarlo más tarde o contacta con soporte. |
Privacidad y acceso
Un token lee los datos de la cuenta de Searcherries que lo creó y nada más. Mantén los tokens fuera de repositorios públicos, documentos compartidos y capturas de pantalla; si uno queda expuesto, revócalo en la página MCP y crea uno de sustitución.
La API sirve datos almacenados a la herramienta que conectes. Esa herramienta puede tener su propia suscripción, sus cargos por uso y su configuración de tratamiento de datos. Conecta solo herramientas que pienses usar con los datos de tu proyecto.