Descubre dónde se queda fuera tu marca en una respuesta de IA

Citation Analysis muestra en qué páginas se apoyó una respuesta de IA, dónde está tu marca y qué hacer, empezando por tu propio sitio.

Qué cambia

• queries: las búsquedas que hizo el motor, cada una con las páginas que encontró.
• sources: cada página que recuperó el motor, con cited para separar las citadas del resto, su position en la búsqueda, los pasajes que el motor dijo citar, las marcas que nombra la página y un channel que indica quién la controla: tu sitio, otra marca, un medio, una tienda, una plataforma de reseñas, una comunidad, video, redes sociales, una plataforma de blogs o una obra de referencia.
• brands: tu marca, tus competidores y cada marca que nombra la respuesta, en el orden en que aparecen, con las páginas citadas y recuperadas que nombran a cada una.
• visibility: la etapa que alcanzó tu marca, desde nombrada en la respuesta hasta ausente de las páginas que leímos.
• actions: qué hacer, en orden de cuánto depende de ti: primero tus páginas, luego las plataformas donde puedes publicar y al final los medios a los que proponer algo. Cada acción trae steps concretos y las páginas que la respaldan.
• insights: lo que comparten las páginas citadas, como canal, formato, actualidad y criterios, y dónde está tu marca, cada lectura con las páginas y enlaces en que se apoya.

La respuesta de POST /v1/citation-analysis ahora incluye version: 4 y estos campos nuevos. links mantiene su forma, cada insight suma sus páginas en sourceIds junto a linkIds, y los resultados guardados antes de este cambio conservan la forma con la que se guardaron. El producto ahora se llama Citation Analysis: /v1/source-influence y /v1/geo-audit, los taskType SOURCE_INFLUENCE y GEO_AUDIT, e include.sourceInfluence e include.geoAudit siguen funcionando, y las respuestas usan /v1/citation-analysis, CITATION_ANALYSIS y citationAnalysis.

Cómo funciona

Con un taskId, las búsquedas y las páginas recuperadas salen de la propia tarea de respuesta cuando el motor las expone, como ChatGPT y Google AI Overview. También puedes enviarlas tú en queries y como citations con cited: false. Los demás motores solo listan páginas citadas.

Las recomendaciones salen sobre todo de páginas de terceros. En las respuestas de ChatGPT que estudiamos, el motor recuperó una mediana de 20 páginas y citó 3, y el sitio propio de una marca recomendada se recuperó en el 16 % de los casos y se citó en el 6,8 %. Las acciones siguen ese camino, empezando por lo que está en tus manos:

• improve_page: tu página que el motor recuperó y pasó por alto, o que citó mientras la respuesta deja fuera tu marca, con lo que conviene añadir para que responda al prompt como las páginas citadas.
• publish_page: un brief para una página nueva en tu sitio, para una búsqueda en la que ninguna de tus páginas fue citada, basado en las que sí lo fueron: tipo de página, patrón de título, secciones, pruebas y fecha.
• post_on_platform: una página de tienda, plataforma de reseñas, comunidad, video o red social que nombra a tus competidores, con pasos como completar tu ficha, pedir reseñas a clientes reales o responder identificándote como representante de la marca.
• pitch_publisher: una página editorial citada que solo su medio puede cambiar, con lo que conviene enviarle.

Cada coincidencia muestra qué página dice lo que dice la respuesta, y cada acción apunta a las páginas exactas en que se apoya. La etapa not_found significa que ninguna página que leímos nombra tu marca. Envía brand para recibir visibility y actions, y añade brandDomains y brandAliases para que cuenten tus páginas y tus otros nombres.

Para qué sirve

• Empieza por tu propio sitio: rehace la página que el motor pasó por alto o prepara una nueva basada en las citadas.
• Pasa a tu equipo de marketplaces y comunidades las fichas y los hilos donde aparecen tus competidores.
• Propón cambios a los medios con la página exacta y los pasajes que tomó la respuesta.

Envía la solicitud

Envía la solicitud con tu clave de API en la cabecera Authorization.

curl -X POST https://api.querying.ai/v1/citation-analysis \
  -H "Authorization: Bearer $QUERYING_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "taskId": "…",
    "brand": "Blueair",
    "competitors": ["Coway", "Levoit"],
    "brandDomains": ["blueair.com"]
  }'

Campos de la solicitud

taskIdstringObligatorio

Una tarea de respuesta tuya ya completada. Su respuesta y sus páginas citadas pasan a ser answer y citations.

brandstring

El nombre de tu marca. Con él, el resultado suma visibility y actions.

competitorsarray

Nombres de competidores que se siguen en la respuesta y sus páginas.

brandDomainsarray

Hasta 10 nombres de host de tus sitios, como coway.com. Sus páginas cuentan como own.

brandAliasesarray

Hasta 10 nombres alternativos de tu marca, como líneas de producto o grafías locales.

citations[].citedboolean

Por defecto true. Envía false para una página que el motor recuperó y no citó, con su position y query si los tienes.

countrystring

País desde el que se leen las páginas citadas. Por defecto US.

webhook.urlstring

Una dirección HTTPS de tu servidor. La tarea terminada se envía allí en cuanto se completa.

idempotencyKeystring

Tu propio ID para la solicitud. Cada clave crea una sola tarea por cuenta, así que un reenvío sigue siendo una sola tarea.

Respuesta

Así llega una tarea terminada, recortada para que se lea mejor.

{
  "success": true,
  "task": {
    "id": "…",
    "taskType": "CITATION_ANALYSIS",
    "status": "COMPLETED",
    "createdAt": "…"
  },
  "credits": { "creditsToCharge": "…", "creditsCharged": "…" },
  "response": {
    "version": 4,
    "answer": "The best-reviewed air purifiers depend on whether you …",
    "queries": [
      {
        "id": "q0",
        "text": "best air purifiers 2026 reviews independent testing …",
        "sourceIds": ["s0", "s1", "s2", "…", "s20"]
      }
    ],
    "sources": [
      {
        "id": "s13",
        "url": "https://www.blueair.com/products/blue-pure-211i-max",
        "domain": "blueair.com",
        "channel": "own",
        "cited": false,
        "position": 14,
        "queryIds": ["q0"],
        "publishedAt": null,
        "citedText": [],
        "brandIds": ["b0"],
        "own": true,
        "paragraphs": []
      },
      {
        "id": "s14",
        "url": "https://www.target.com/p/levoit-core-300-air-…",
        "domain": "target.com",
        "channel": "retailer",
        "cited": true,
        "position": 15,
        "queryIds": ["q0"],
        "publishedAt": null,
        "citedText": [
          "A compact, straightforward option with a 4.6/5 rating …"
        ],
        "brandIds": ["b2"],
        "own": false,
        "paragraphs": [
          {
            "id": "s14p1",
            "text": "Levoit Core 300 Air Purifier White … $99.99 …"
          }
        ]
      },
      "…"
    ],
    "brands": [
      {
        "id": "b0",
        "name": "Blueair",
        "role": "target",
        "rank": 2,
        "answerRanges": ["…"],
        "citedSourceIds": ["s1", "s3", "s11"],
        "retrievedSourceIds": ["s5", "s6", "s8", "s9", "s13"],
        "ownSourceIds": ["s11", "s13"]
      },
      {
        "id": "b1",
        "name": "Coway",
        "role": "competitor",
        "rank": 1,
        "answerRanges": ["…"],
        "citedSourceIds": ["s1", "s3", "s4", "s7"],
        "retrievedSourceIds": ["s0", "s5", "s6", "s9", "s10", "s18"],
        "ownSourceIds": []
      },
      {
        "id": "b2",
        "name": "Levoit",
        "role": "competitor",
        "rank": 3,
        "answerRanges": ["…"],
        "citedSourceIds": ["s3", "s7", "s14"],
        "retrievedSourceIds": ["s6", "s15", "s16"],
        "ownSourceIds": []
      },
      "…"
    ],
    "links": [
      {
        "id": "l40",
        "paragraphId": "s14p1",
        "answerRanges": ["…"],
        "explanation": "Lists the Levoit Core 300 at $99.99, …"
      },
      "…"
    ],
    "visibility": {
      "brandId": "b0",
      "stage": "mentioned",
      "rank": 2,
      "answerBrands": 5
    },
    "actions": [
      {
        "id": "a0",
        "type": "improve_page",
        "control": "owned",
        "priority": 1,
        "summary": "Update Blueair’s site with a current, …",
        "steps": [
          "Add a page on best air purifiers in 2026 that covers …",
          "Include Blueair models in direct comparisons using published …",
          "…"
        ],
        "sourceIds": ["s13"],
        "brandIds": ["b0"],
        "queryIds": ["q0"],
        "linkIds": []
      },
      {
        "id": "a1",
        "type": "post_on_platform",
        "control": "platform",
        "priority": 2,
        "summary": "Improve Blueair’s Target product listing with …",
        "steps": [
          "Ensure the Blueair listing clearly states the model, current …",
          "…",
          "Keep product details current and invite genuine purchasers to …"
        ],
        "sourceIds": ["s14"],
        "brandIds": ["b2"],
        "queryIds": ["q0"],
        "linkIds": ["l40"]
      },
      "…"
    ],
    "insights": [
      {
        "summary": "Blueair’s second-place position is reflected in …",
        "sourceIds": ["s1", "s3", "s11"],
        "linkIds": ["l1", "l12", "l36"]
      },
      "…"
    ]
  }
}

task.statusstring

QUEUED, PROCESSING y al final COMPLETED con la respuesta o FAILED con error.

credits.creditsChargedinteger

Créditos cobrados por la tarea terminada. Una tarea fallida cobra 0.

response.versionnumber

La forma del resultado. 4 en los análisis con búsquedas, páginas recuperadas, marcas y acciones.

response.answerstring

La respuesta que enviaste, tal cual. Los rangos son posiciones UTF-16 de este mismo texto.

response.queriesarray

Las búsquedas que hizo el motor, cada una con id, su text y los sourceIds que encontró.

response.sourcesarray

Cada página que recuperó el motor. cited distingue las citadas del resto y channel indica quién controla la página (own, brand, editorial, retailer, review_platform, community, video, social, blog_platform o reference). También lleva position, queryIds, citedText, brandIds y own. Las citadas llevan paragraphs.

response.brandsarray

Tu marca, tus competidores y las marcas que nombra la respuesta, cada una con role, su rank en la respuesta, answerRanges y las páginas citadas y recuperadas que la nombran.

response.linksarray

Cada enlace une un párrafo con los answerRanges que le corresponden y una explanation de una frase.

response.visibilityobject

Hasta dónde llegó tu marca: stage es mentioned, on_cited_page, on_retrieved_page o not_found, con su rank y answerBrands. null sin brand.

response.actionsarray

Qué hacer, por priority: primero el trabajo owned en tu sitio (improve_page, publish_page), luego las publicaciones platform (post_on_platform) y al final el outreach (pitch_publisher). Cada acción lleva su control, un summary, de 1 a 5 steps y las fuentes, marcas, búsquedas y enlaces que la respaldan. Vacío sin brand.

response.insightsarray

Hasta 4 lecturas breves de lo que comparten las páginas citadas y de dónde está tu marca, cada una con sus páginas en sourceIds y sus enlaces en linkIds.

Recibe el resultado

La solicitud devuelve la tarea al instante con status QUEUED. Consulta GET /v1/async/task/{id} hasta que status sea COMPLETED o FAILED, o añade webhook.url y la tarea terminada llega a tu servidor con los mismos task, credits y response. Los resultados siguen disponibles 24 horas después de terminar la tarea.

curl https://api.querying.ai/v1/async/task/$TASK_ID \
  -H "Authorization: Bearer $QUERYING_API_KEY"

Precio

El precio no cambia: los créditos se reservan cuando empieza el análisis y se liquidan cuando termina.