Synupv1
Crear clave
v1Recursos/AEO

AEO

Haga seguimiento de la visibilidad de una ubicación en los motores de respuesta de IA (ChatGPT, Gemini, Perplexity): con qué frecuencia se la menciona, cómo se posiciona frente a la competencia y qué está frenando su puntuación.

Devuelve el informe de visibilidad en IA más reciente de una ubicación: puntuaciones generales y por motor, la matriz de palabras clave/prompts, comparaciones de brechas y posicionamiento frente a la competencia, cobertura de citas, sentimiento y correcciones recomendadas. La generación del informe es asíncrona — este es también el endpoint de sondeo para POST /api/v1/aeo/reports/enqueue: siga llamando a este endpoint y observe el campo generating hasta que vuelva a false y generatedAt se actualice. Indique prompt para profundizar en un prompt seguido específico en lugar del informe completo.

Obtener el informe AEO de una ubicación

get/api/v1/aeo/reports
aeo:read
Parámetros de consulta
locationIdstringobligatorio
La ubicación a consultar.
clientIdstringopcional
El cliente de la ubicación.
promptstringopcional
Profundiza en un prompt seguido (coincidencia sin distinción de mayúsculas) en lugar de devolver el informe completo. Devuelve celdas null si el prompt no está en la matriz de esta ubicación.
Respuesta
dataobjectopcional
Errores
400A la solicitud le falta un parámetro obligatorio o es inválida de otra forma.
401La clave de API falta, es inválida, expiró o fue revocada.
403A la clave le falta el permiso requerido, o no está autorizada para este cliente/ubicación.
404El recurso no se encontró, o no pertenece a su agencia.
429Demasiadas solicitudes. Reintente tras el número de segundos indicado en el encabezado Retry-After.
get/api/v1/aeo/reports
Su clave de API
locationId *
clientId
prompt
{
  "data": {
    "generatedAt": "2026-02-01T06:00:00.000Z",
    "generating": false,
    "configuredEngines": [
      "ChatGPT",
      "Gemini"
    ],
    "visibility": {
      "overall": 62,
      "label": "GOOD",
      "message": "Your business shows up for most of the prompts you're tracking.",
      "engines": {
        "ChatGPT": {
          "score": 68,
          "comparisonPct": 12,
          "configured": true
        },
        "Gemini": {
          "score": 56,
          "comparisonPct": -4,
          "configured": true
        },
        "Perplexity": {
          "score": null,
          "comparisonPct": null,
          "configured": false
        }
      }
    },
    "metrics": {
      "visibility": {
        "value": 62,
        "delta": 5
      },
      "mentionRate": {
        "value": 71,
        "delta": 3
      },
      "avgPosition": {
        "value": 2.1,
        "delta": -0.4
      },
      "promptsCovered": {
        "value": 8,
        "total": 10
      },
      "sourcesCited": {
        "value": 14,
        "delta": 2
      }
    },
    "keywordMap": {
      "ChatGPT": [
        {
          "keyword": "best dentist austin",
          "percentage": 82,
          "dataSources": [
            {
              "name": "Google Business Profile"
            }
          ]
        }
      ],
      "Gemini": [
        {
          "keyword": "emergency dentist austin",
          "percentage": 54,
          "dataSources": []
        }
      ],
      "Perplexity": []
    },
    "matrix": [
      {
        "keyword": "best dentist austin",
        "cells": {
          "ChatGPT": {
            "score": 82,
            "mentioned": true,
            "rank": 1,
            "answerExcerpt": "Acme Dental — Downtown is highly rated for..."
          },
          "Gemini": {
            "score": 54,
            "mentioned": true,
            "rank": 3,
            "answerExcerpt": null
          },
          "Perplexity": null
        },
        "best": 82
      }
    ],
    "gap": [
      {
        "business": "Acme Dental — Downtown",
        "isYou": true,
        "overall": 62,
        "chatgpt": 68,
        "gemini": 56,
        "perplexity": null,
        "comparisonPct": null
      },
      {
        "business": "Smile Bright Dental",
        "isYou": false,
        "overall": 71,
        "chatgpt": 74,
        "gemini": 68,
        "perplexity": null,
        "comparisonPct": 9
      }
    ],
    "ranking": {
      "All": {
        "primary": {
          "good": 6,
          "neutral": 2,
          "bad": 2
        },
        "competitors": []
      },
      "ChatGPT": {
        "primary": {
          "good": 7,
          "neutral": 1,
          "bad": 2
        },
        "competitors": []
      },
      "Gemini": {
        "primary": {
          "good": 5,
          "neutral": 3,
          "bad": 2
        },
        "competitors": []
      },
      "Perplexity": {
        "primary": {
          "good": 0,
          "neutral": 0,
          "bad": 0
        },
        "competitors": []
      }
    },
    "radar": {
      "ChatGPT": {
        "relevance": 78,
        "reviews": 88,
        "engagement": 65,
        "freshness": 74,
        "citations": 81
      },
      "Gemini": {
        "relevance": 70,
        "reviews": 80,
        "engagement": 75,
        "freshness": 85,
        "citations": 65
      },
      "Perplexity": {
        "relevance": 0,
        "reviews": 0,
        "engagement": 0,
        "freshness": 0,
        "citations": 0
      }
    },
    "factors": [
      {
        "key": "citations",
        "label": "Citations",
        "value": 81,
        "detail": "Cited by 14 of 20 tracked sources across configured engines.",
        "action": {
          "label": "Fix missing citations",
          "target": "citations"
        }
      }
    ],
    "citations": {
      "summary": {
        "totalSources": 20,
        "active": 14,
        "detected": 4,
        "missing": 2,
        "missingDirectories": [
          "Yelp"
        ]
      },
      "byEngine": {
        "ChatGPT": [
          {
            "name": "Google Business Profile",
            "status": "active"
          }
        ],
        "Gemini": [],
        "Perplexity": []
      }
    },
    "sentiment": {
      "positive": 62,
      "neutral": 30,
      "negative": 8,
      "mentions": []
    },
    "attention": [
      {
        "text": "Bing Places is missing your current hours.",
        "tone": "warn"
      }
    ],
    "recommendations": [
      {
        "id": "rec_reviews_1",
        "kind": "opportunity",
        "priority": "high",
        "title": "Add more customer reviews mentioning services",
        "detail": "Reviews that name specific services improve how often engines cite you for those prompts.",
        "action": {
          "label": "Request reviews",
          "target": "reviews"
        }
      }
    ],
    "history": [
      {
        "yearMonth": "2026-01",
        "overall": 57,
        "chatgpt": 61,
        "gemini": 53,
        "perplexity": null,
        "sources": 12
      },
      {
        "yearMonth": "2026-02",
        "overall": 62,
        "chatgpt": 68,
        "gemini": 56,
        "perplexity": null,
        "sources": 14
      }
    ],
    "competitorHistory": [
      {
        "name": "Smile Bright Dental",
        "points": [
          {
            "yearMonth": "2026-01",
            "overall": 65
          },
          {
            "yearMonth": "2026-02",
            "overall": 71
          }
        ]
      }
    ]
  }
}
v1Recursos/AEO/postEncolar la generación de un informe AEO

Inicia la generación en segundo plano de un nuevo informe AEO para una ubicación. La generación del informe ejecuta varias llamadas a LLM por motor/prompt y nunca se ejecuta de forma síncrona dentro de la solicitud — esta llamada encola el trabajo y regresa de inmediato. No existe un recurso independiente de job-id o estado: sondee GET /api/v1/aeo/reports para la misma ubicación y observe el campo generating hasta que vuelva a false. No está disponible para ubicaciones anteriores a la caché de ubicaciones heredada de Synup (ubicaciones solo nativas).

Encolar la generación de un informe AEO

post/api/v1/aeo/reports/enqueue
aeo:write
Cuerpo de la solicitud
locationIdstringobligatorio
La ubicación para la que generar un informe.
clientIdstringopcional
El cliente de la ubicación.
forcebooleanopcional
Cuando es true, inicia una nueva generación aunque ya se haya generado un informe este mes.
Respuesta
dataobjectopcional
enqueuedbooleanopcional
Siempre true — se encoló el trabajo de generación.
forcebooleanopcional
Repite el indicador force de la solicitud.
Errores
400A la solicitud le falta un parámetro obligatorio o es inválida de otra forma.
401La clave de API falta, es inválida, expiró o fue revocada.
403A la clave le falta el permiso requerido, o no está autorizada para este cliente/ubicación.
404El recurso no se encontró, o no pertenece a su agencia.
429Demasiadas solicitudes. Reintente tras el número de segundos indicado en el encabezado Retry-After.
post/api/v1/aeo/reports/enqueue
Su clave de API
Cuerpo de la solicitud*
{
  "data": {
    "enqueued": true,
    "force": false
  }
}
v1Recursos/AEO/getObtener el resumen AEO de todas las ubicaciones

Devuelve el resumen del informe AEO más reciente por ubicación, opcionalmente limitado a un cliente y/o etiquetas de ubicación, además de datos de tendencia de toda la cartera y de correcciones sistémicas. Las ubicaciones sin informe todavía muestran puntuaciones null.

Obtener el resumen AEO de todas las ubicaciones

get/api/v1/aeo/rollup
aeo:read
Parámetros de consulta
clientIdstringopcional
Restringe los resultados a un cliente. Cuando su clave está limitada a clientes específicos, esto es obligatorio.
tagsstringopcional
Nombres de etiquetas de ubicación separados por comas. Solo se incluyen las ubicaciones que tengan al menos una de estas etiquetas.
Respuesta
dataobjectopcional
rowsarray of objectopcional
Una fila por cada ubicación en el alcance.
locationIdstringopcional
Identificador único de la ubicación.
namestringopcional
El nombre comercial de la ubicación.
citystringopcional
Ciudad, o null.
overallnumberopcional
Última puntuación general de visibilidad en IA (de 0 a 100), o null si nunca se generó.
chatgptnumberopcional
Última puntuación de ChatGPT, o null.
gemininumberopcional
Última puntuación de Gemini, o null.
perplexitynumberopcional
Última puntuación de Perplexity, o null.
generatedAtstringopcional
Cuándo se generó el informe más reciente, como marca de tiempo ISO 8601, o null si nunca se generó.
yearMonthstringopcional
Mes del informe más reciente (YYYY-MM), o null.
tagsarray of stringopcional
Las etiquetas internas de la ubicación.
historyarray of numberopcional
Historial de puntuación general de esta ubicación, en orden cronológico, solo valores no null.
deltanumberopcional
Variación de la puntuación general respecto al informe anterior, o null en el primer informe o si no hay un mes previo.
topIssueobjectopcional
El factor de visibilidad más débil de esta ubicación, o null si aún no tiene un informe.
labelstringopcional
tonestring (good | warn | bad)opcional
configuredEnginesarray of string (ChatGPT | Gemini | Perplexity)opcional
Motores de IA para los que esta agencia tiene una clave de API configurada.
portfolioHistoryarray of objectopcional
Puntuación general promedio entre las ubicaciones en el alcance, por mes.
yearMonthstringopcional
Mes en formato YYYY-MM.
avgnumberopcional
Puntuación general promedio entre las ubicaciones con informe ese mes.
locationsnumberopcional
Número de ubicaciones con informe ese mes (el denominador del promedio).
systemicFixesarray of objectopcional
Debilidades compartidas entre varias ubicaciones, cada una con una única corrección por lotes, ordenadas por alcance.
factorstringopcional
Identificador del factor legible por máquina.
labelstringopcional
Nombre del factor legible por humanos.
detailstringopcional
Explicación de la debilidad sistémica.
targetstring (listings | citations | reviews | posts | competitors | prompts)opcional
A qué parte del producto dirige la corrección.
countnumberopcional
Número de ubicaciones afectadas.
pctnumberopcional
Porcentaje de ubicaciones con informe afectadas.
Errores
401La clave de API falta, es inválida, expiró o fue revocada.
403A la clave le falta el permiso requerido, o no está autorizada para este cliente/ubicación.
429Demasiadas solicitudes. Reintente tras el número de segundos indicado en el encabezado Retry-After.
get/api/v1/aeo/rollup
Su clave de API
clientId
tags
{
  "data": {
    "rows": [
      {
        "locationId": "cm_loc_1",
        "name": "Acme Dental — Downtown",
        "city": "Austin",
        "overall": 62,
        "chatgpt": 68,
        "gemini": 56,
        "perplexity": null,
        "generatedAt": "2026-02-01T06:00:00.000Z",
        "yearMonth": "2026-02",
        "tags": [
          "priority"
        ],
        "history": [
          57,
          62
        ],
        "delta": 5,
        "topIssue": null
      }
    ],
    "configuredEngines": [
      "ChatGPT",
      "Gemini"
    ],
    "portfolioHistory": [
      {
        "yearMonth": "2026-01",
        "avg": 57,
        "locations": 5
      },
      {
        "yearMonth": "2026-02",
        "avg": 62,
        "locations": 5
      }
    ],
    "systemicFixes": [
      {
        "factor": "citations",
        "label": "Citations",
        "detail": "6 locations are missing citations on Yelp.",
        "target": "citations",
        "count": 6,
        "pct": 30
      }
    ]
  }
}