Skip to main content
Los endpoints de reportes v2 comparten una misma estructura de solicitud y respuesta: Visibility, Citations, Sentiment, Query Fanouts, Answers y FactCheck (puntuaciones de precisión + afirmaciones). Apréndela una vez y todos los reportes funcionan igual. Los reportes sociales de YouTube también son reportes v2, con campos de agrupación y atribución específicos de canales y videos; consulta YouTube Channels y YouTube Videos para ver sus campos de solicitud y respuesta específicos de cada endpoint.
FactCheck usa el mismo envoltorio { info, data }, pero es por categoría (sin parámetros scope/assets/metrics) y acepta un filter más limitado: un and de nivel superior con hojas de un solo campo, y solo topic se puede negar. Consulta sus páginas para conocer los detalles.
Todos los endpoints v2 aceptan nombres o UUID en cualquier lugar donde un filtro reciba un valor. Obtén los UUID de GET /v1/org/models, /v1/org/regions, /v1/org/personas, /v1/org/assets, /v1/org/categories y los endpoints por categoría …/topics, …/tags, …/prompts.

​
Campos comunes de la solicitud

A diferencia de los reportes v1 (donde end_date es exclusivo), en v2 end_date es inclusivo. Para obtener del 9 al 15 de junio, envía start_date: "2026-06-09", end_date: "2026-06-15".

​
Agrupación

group_by convierte una fila agregada en una fila por valor. Cada campo agrupado se devuelve en la fila:
  • Agrupa por date (con interval) para obtener una serie temporal.
  • Las filas incluyen un rank cuando se agrupan por una dimensión que no es de fecha.
  • Las dimensiones disponibles varían según el reporte; consulta la referencia de cada endpoint.

​
Métricas

Solicita las métricas que quieras; se devuelven como campos con nombre en cada fila (sin arreglos posicionales ni búsquedas en info.query):

​
Alcance y selección de activos

  • scope: owned limita a los activos/dominios que te pertenecen; all clasifica todo.
  • Solo Visibility: elige los activos con el parámetro independiente assets: un nombre (is), una lista (in, que anula scope) o { op, value }. Una selección devuelve todas las coincidencias e ignora limit.
  • Sentiment requiere un asset (el sentimiento es por marca).

​
Filtros

filter es un árbol recursivo, con profundidad máxima de 3, para todos los reportes, incluidos los reportes sociales de YouTube:
Tipos de nodo: { "and": [ … ] }, { "or": [ … ] }, { "not": <node> } y hojas { "field", "op", "value" }.

​
Operadores

value es un único valor, o una lista para in / not_in. Nombres o UUID; contains / matches buscan coincidencias en los nombres.

​
Dos capas de filtros

Los campos se dividen en dos capas. Se combinan con and; or/not no pueden mezclar capas (hacerlo devuelve 422). Capa de prompts (árbol completo, conjunto completo de operadores): model, topic, region, persona, prompt, tag. Capa de entidades / citas (solo hojas and de nivel superior, varía según el reporte):
En citas, filtra por domain en el reporte de dominios y por page cuando uses group_by: ["page"]; cada uno filtra la entidad de su propio reporte.
Sentiment con source: "citation" siempre devuelve filas de páginas y no admite group_by. Usa filtros de la capa de prompts para limitar qué citas cuentan, y usa citation_category o page para limitar las páginas devueltas.
Los reportes de YouTube usan el filtro de entidad channel. Se puede combinar con filtros a nivel de prompt mediante and, pero no bajo or ni not. Los filtros domain y page de YouTube se rechazan en lugar de aproximarse.
Enumera las etiquetas de citas de una categoría con Get Citation Tags. Coloca todas las etiquetas que quieras en una sola hoja in (los valores se combinan con OR). Combinar con AND dos hojas citation_tag separadas, o pasar una lista vacía, devuelve 422.

​
Ordenamiento

Donde se admite, sort es { "field": "<metric>", "dir": "asc" | "desc" }. El campo debe ser una métrica solicitada y ordenable (o date cuando se agrupa por fecha). Citations no tiene sort: siempre se clasifica con las más citadas primero.

​
Paginación

Las respuestas devuelven limit filas más info.next_cursor. Envía ese token como cursor para obtener la página siguiente; next_cursor es null en la última página.

​
Streaming

Todos los endpoints de reportes, excepto los reportes sociales de YouTube, tienen una variante /stream (Server-Sent Events): un evento summary (el bloque info) y, luego, un evento result por fila. limit/cursor se ignoran; devuelve todo de forma predeterminada. Envía max_results para establecer un límite. El streaming de Sentiment acepta tanto source: "response" como source: "citation" usando las mismas estructuras de fila específicas de cada fuente que el endpoint paginado.

​
Estructura de la respuesta

Todos los reportes devuelven { info, data }:
info devuelve la consulta resuelta (modelos dentro del alcance, el filtro aplicado, las fechas, la paginación); data contiene las filas, con las métricas como campos con nombre y las dimensiones de group_by adjuntas.