Citation Analysis

curl -X POST https://api.querying.ai/v1/citation-analysis \
  -H "Authorization: Bearer $QUERYING_API_KEY" -H "Content-Type: application/json" \
  -d '{
    "answer": "…the AI answer, as raw markdown…",
    "prompt": "best password manager for a small team",
    "engine": "CHATGPT",
    "brand": "1Password",
    "competitors": ["Bitwarden"],
    "citations": [
      { "url": "https://example.com/best-password-managers", "body": "…the page markdown…" },
      { "url": "https://another.example.com/pricing" }
    ]
  }'

​

Analizar una tarea que ya ejecutaste

curl -X POST https://api.querying.ai/v1/citation-analysis \
  -H "Authorization: Bearer $QUERYING_API_KEY" -H "Content-Type: application/json" \
  -d '{ "taskId": "7c1f…", "brand": "1Password", "competitors": ["Bitwarden"] }'

​

Analiza cada respuesta mientras la recopilas

curl -X POST https://api.querying.ai/v1/async/task \
  -H "Authorization: Bearer $QUERYING_API_KEY" -H "Content-Type: application/json" \
  -d '{
    "taskType": "CHATGPT",
    "payload": { "prompt": "best password manager for a small team", "country": "US", "include": { "citationAnalysis": true } },
    "webhook": { "url": "https://example.com/hook" }
  }'

• Webhook: se envía una sola vez, cuando termina el análisis, con la respuesta y el análisis juntos.
• Consulta periódica: la tarea de respuesta pasa a COMPLETED en cuanto la respuesta está lista. Sigue consultando hasta que response.citationAnalysis.task.status sea COMPLETED o FAILED.
• Los lotes se completan cuando todas las respuestas y sus análisis han terminado.
• Sin análisis: si la respuesta no cita ninguna URL que leer, o tus créditos o el límite diario de la clave no cubren la reserva del análisis, response.citationAnalysis es { "error": "…" } y la respuesta se entrega de inmediato.
• Facturación: el análisis se cobra aparte, por uso, como cualquier tarea de Citation Analysis. El cobro de la respuesta no cambia. Una clave limitada a ciertos tipos de tarea también debe permitir CITATION_ANALYSIS.

​

Payload

​

Resultado

{
  "version": 4,
  "answer": "For most homes, the Coway Airmega 250 is the best all-round pick. Levoit Core 300 is a strong budget choice, and Blueair Blue Pure 211+ suits large rooms.",
  "queries": [
    { "id": "q0", "text": "best air purifiers 2026 reviews", "sourceIds": ["s0", "s1", "s2"] }
  ],
  "sources": [
    {
      "id": "s0",
      "url": "https://www.example-reviews.com/best-air-purifiers",
      "domain": "example-reviews.com",
      "channel": "editorial",
      "cited": true,
      "position": 1,
      "queryIds": ["q0"],
      "publishedAt": "October 7, 2026",
      "citedText": ["Levoit Core 300 is the best budget purifier we tested."],
      "brandIds": ["b1", "b2"],
      "own": false,
      "paragraphs": [
        { "id": "s0p0", "text": "Levoit Core 300 is the best budget purifier we tested." },
        { "id": "s0p1", "text": "For large rooms, the Blueair Blue Pure 211+ cleared the air fastest." }
      ]
    },
    {
      "id": "s1",
      "url": "https://www.coway.com/airmega-250",
      "domain": "coway.com",
      "channel": "own",
      "cited": false,
      "position": 4,
      "queryIds": ["q0"],
      "publishedAt": null,
      "citedText": [],
      "brandIds": ["b0"],
      "own": true,
      "paragraphs": []
    },
    {
      "id": "s2",
      "url": "https://www.reddit.com/r/AirPurifiers/comments/abc123/budget_pick",
      "domain": "reddit.com",
      "channel": "community",
      "cited": true,
      "position": 6,
      "queryIds": ["q0"],
      "publishedAt": null,
      "citedText": [],
      "brandIds": ["b1"],
      "own": false,
      "paragraphs": [
        { "id": "s2p0", "text": "Two years with the Levoit Core 300 and it is still quiet on sleep mode." }
      ]
    }
  ],
  "brands": [
    { "id": "b0", "name": "Coway", "role": "target", "rank": 1, "answerRanges": [{ "start": 20, "end": 25 }], "citedSourceIds": [], "retrievedSourceIds": ["s1"], "ownSourceIds": ["s1"] },
    { "id": "b1", "name": "Levoit", "role": "competitor", "rank": 2, "answerRanges": [{ "start": 66, "end": 72 }], "citedSourceIds": ["s0", "s2"], "retrievedSourceIds": [], "ownSourceIds": [] },
    { "id": "b2", "name": "Blueair", "role": "answer", "rank": 3, "answerRanges": [{ "start": 113, "end": 120 }], "citedSourceIds": ["s0"], "retrievedSourceIds": [], "ownSourceIds": [] }
  ],
  "links": [
    { "id": "l0", "paragraphId": "s0p0", "answerRanges": [{ "start": 66, "end": 154 }], "explanation": "Names the Levoit Core 300 as the budget pick." },
    { "id": "l1", "paragraphId": "s0p1", "answerRanges": [{ "start": 66, "end": 154 }], "explanation": "Recommends the Blueair Blue Pure 211+ for large rooms." },
    { "id": "l2", "paragraphId": "s2p0", "answerRanges": [{ "start": 66, "end": 154 }], "explanation": "Reports long-term use of the Levoit Core 300." }
  ],
  "visibility": { "brandId": "b0", "stage": "mentioned", "rank": 1, "answerBrands": 3 },
  "actions": [
    {
      "id": "a0",
      "type": "improve_page",
      "control": "owned",
      "priority": 1,
      "summary": "Coway's Airmega 250 page was retrieved for this search but not cited.",
      "steps": [
        "Add a table of room coverage, noise level and yearly filter cost, the criteria the cited review compares.",
        "Show when the specifications were last updated."
      ],
      "sourceIds": ["s1"],
      "brandIds": ["b0"],
      "queryIds": ["q0"],
      "linkIds": []
    },
    {
      "id": "a1",
      "type": "publish_page",
      "control": "owned",
      "priority": 2,
      "summary": "No Coway page was cited for this search; the cited review is a dated buying guide.",
      "steps": [
        "Publish a 2026 air purifier buying guide on coway.com, organized by room size and budget.",
        "Explain how models were compared, show measured results, and name the author and date."
      ],
      "sourceIds": ["s0"],
      "brandIds": ["b0"],
      "queryIds": ["q0"],
      "linkIds": ["l0", "l1"]
    },
    {
      "id": "a2",
      "type": "post_on_platform",
      "control": "platform",
      "priority": 3,
      "summary": "A cited Reddit thread recommends Levoit and never mentions Coway.",
      "steps": [
        "Reply as an identified Coway representative with the Airmega 250 details the thread asks about."
      ],
      "sourceIds": ["s2"],
      "brandIds": ["b1"],
      "queryIds": ["q0"],
      "linkIds": ["l2"]
    },
    {
      "id": "a3",
      "type": "pitch_publisher",
      "control": "outreach",
      "priority": 4,
      "summary": "The top cited review names Levoit and Blueair but not Coway; only its publisher can add the Airmega 250.",
      "steps": [
        "Offer the editors an Airmega 250 for testing.",
        "Send test data for the criteria the review uses: room coverage, noise and filter cost."
      ],
      "sourceIds": ["s0"],
      "brandIds": ["b1", "b2"],
      "queryIds": ["q0"],
      "linkIds": ["l0", "l1"]
    }
  ],
  "insights": [
    { "summary": "Both cited pages recommend Levoit for a budget; the review also backs Blueair for large rooms.", "sourceIds": ["s0", "s2"], "linkIds": ["l0", "l1", "l2"] },
    { "summary": "The answer names Coway first, yet no cited page names it; only its own page, which was not cited, does.", "sourceIds": ["s1"], "linkIds": [] }
  ]
}

​

version

​

answer

​

queries[]

​

sources[]: una entrada por página

• id: identificador opaco, único dentro del resultado.
• url: la URL de la página; domain: su host.
• channel: quién controla la página, deducido de su host:
  • own: el sitio propio de tu marca (exactamente cuando own es true).
  • brand: el sitio propio de otra marca que nombra el resultado.
  • editorial: un editor; solo el editor puede cambiar la página. Los hosts no reconocidos se informan como editorial.
  • retailer: una tienda online o un marketplace.
  • review_platform: un sitio de reseñas de clientes o de empresas.
  • community: un foro o un sitio de preguntas y respuestas.
  • video: una plataforma de vídeo.
  • social: una red social.
  • blog_platform: un servicio de blogs alojados.
  • reference: una enciclopedia o wiki; nunca es objetivo de una acción.
• cited: true si la respuesta cita la página, false si el motor solo la recuperó.
• position: la posición que el propio motor dio a la página, o null si no dio ninguna.
• queryIds[]: las búsquedas que encontraron la página.
• publishedAt: la fecha de publicación tal como la indicó el motor, o null.
• citedText[]: pasajes que el propio motor indicó haber citado; [] si no hay ninguno.
• brandIds[]: marcas nombradas en la página legible, su título o citedText.
• own: true si la página está en el sitio propio de tu marca.
• paragraphs[]: los párrafos de una página citada incluidos en el resultado. Cada uno tiene un id (único en todo el resultado) y el text del párrafo. Un párrafo puede incluirse sin ningún vínculo. Siempre vacío en páginas no citadas.
• error: solo aparece si la página no se pudo leer. En ese caso paragraphs está vacío y la cadena es un motivo breve para esa fuente.

​

brands[]

• rank: el orden en que el nombre de la marca aparece por primera vez en la respuesta, empezando por 1; null si la respuesta no nombra la marca.
• answerRanges[]: los tramos exactos donde la respuesta nombra la marca o uno de sus nombres de producto, en los mismos offsets UTF-16; answer.slice(start, end) devuelve el nombre tal como está escrito. La búsqueda no distingue mayúsculas y toma palabras completas (salvo en escrituras sin espacios); incluye títulos y celdas de tabla, nunca URL de enlaces ni marcado de imágenes. A diferencia de los rangos de links[], no son unidades completas de la respuesta.
• citedSourceIds[]: fuentes citadas cuya página la nombra.
• retrievedSourceIds[]: fuentes no citadas cuya página la nombra.
• ownSourceIds[]: fuentes en el sitio propio de la marca; solo se rellena para la marca objetivo.

​

links[]: una relación por párrafo

• paragraphId: el párrafo al que se refiere el vínculo. Siempre apunta a un párrafo que existe en sources[].
• answerRanges[]: las partes de la respuesta con las que se corresponde este párrafo, como pares start/end en los mismos offsets UTF-16. Un vínculo puede tener varios rangos; el mismo texto de respuesta no se repite entre ellos. Cada rango es una unidad completa de la respuesta (frase, elemento de lista o celda de tabla).
• explanation: una frase breve que describe la correspondencia: qué afirma el párrafo sobre esa parte de la respuesta.

​

visibility

• brandId: tu marca en brands[].
• stage: uno de:
  • mentioned: la respuesta nombra tu marca.
  • on_cited_page: la respuesta no la nombra, pero sí una página citada.
  • on_retrieved_page: solo la nombran páginas que el motor recuperó sin citar.
  • not_found: ninguna página leída la nombra.
• rank: el rank de tu marca en brands[].
• answerBrands: cuántas marcas nombra la respuesta.

​

actions[]

​

insights[]

​

Cómo leer bien el resultado

• La ausencia de vínculo no es un veredicto. Un párrafo sin vínculo simplemente no coincidió con un rango de la respuesta, y una parte de la respuesta sin rango significa que ningún párrafo se vinculó a ella. Ninguna de las dos cosas dice que la página sea irrelevante, no se usara o no sea fiable.
• Una página no leída sigue siendo incierta. Si sources[].error está presente, esa cita quedó fuera del análisis; no trates su falta de vínculos como un hallazgo negativo. Reinténtala o aporta su body si importa.
• Correspondencia, no causalidad. El resultado describe cómo encajan a posteriori una respuesta existente y el texto de una página existente, y qué marcas nombran esas páginas. No mide influencia en la generación, no puntúa la página ni informa de cómo se produjo la respuesta.
• not_found significa que no está en ninguna página leída. No significa que tu marca esté ausente de la web.
• Los datos de recuperación dependen del motor. Las páginas no citadas solo aparecen cuando el motor las expone (ChatGPT, Google AI Overview) o cuando envías páginas con cited: false. Si no, todas las fuentes son citadas y tu propia página solo puede aparecer como citada.
• Los canales se deducen del host. channel se infiere del host de la página, no de leer quién la escribió.
• Las acciones son sugerencias, no garantías. Se priorizan a partir de las páginas listadas en este resultado; aplicar una no asegura que la respuesta cambie.
• Los ids son internos. No guardes los identificadores s…/q…/b…/l…/a… como claves estables entre ejecuciones; solo valen dentro de un resultado.

​

Ejecución y límites

• El tamaño no es un motivo de fallo. Todo lo que acepta el contrato de la solicitud, una answer de hasta 200.000 caracteres con hasta 100 citas, se analiza. Las respuestas largas, los conjuntos grandes de fuentes y las páginas muy largas se gestionan dividiendo el trabajo, no rechazando la tarea.
• La profundidad depende de la respuesta, no de la página. Una página larga no produce más vínculos de los que la respuesta puede sostener: el análisis se concentra en los pasajes con más probabilidad de corresponderse con la respuesta, y cada fuente que muestra una correspondencia aparece representada. En una página grande, o que repite la misma afirmación en navegación, listados y reseñas, espera los pasajes más sólidos y no cada aparición.
• El marcado no es evidencia. Los mapas del sitio, los índices de enlaces y las galerías de imágenes no aportan vínculos; una página formada solo por ellos se informa sin párrafos en lugar de con correspondencias inventadas.
• Una fuente que no se pudo leer se informa en sources[].error sin hacer fallar la tarea si otra fuente es legible. La tarea falla cuando no se pudo leer ninguna fuente, ante un fallo del análisis, un timeout o un error de configuración del servicio.
• Las solicitudes se miden por uso, como el resto de la API. La respuesta de envío muestra la retención temporal de créditos; el cargo final se liquida cuando la tarea llega a un estado final.