Cada informe existe de tres maneras, y las tres devuelven los mismos datos:
- una habilidad (ability), como
vireo-analytics/get-top-pages, para PHP y la Abilities API - una herramienta MCP, como
vireo-analytics-get-top-pages, para asistentes de IA - una ruta REST, como
GET /wp-json/vireo-analytics/v1/stats/top-pages, para scripts
Todas son de solo lectura y necesitan un usuario con la capacidad view_vireo_analytics. Las de Pro además necesitan una licencia de Vireo Pro activa.
Entradas comunes
| Entrada | Tipo | Notas |
|---|---|---|
start |
fecha, YYYY-MM-DD |
Por defecto, 30 días antes de end. Obligatoria en las rutas REST gratuitas. |
end |
fecha, YYYY-MM-DD |
Por defecto, hoy. Obligatoria en las rutas REST gratuitas. |
limit |
entero, de 1 a 100 | El valor por defecto se indica en cada entrada. Sin paginación. |
Las fechas están en la zona horaria de tu sitio y se mantienen dentro de los últimos dos años. En las rutas REST gratuitas, una fecha con formato incorrecto devuelve 400; en el resto, vuelve al valor por defecto.
Las habilidades, y por tanto las herramientas MCP, solo aceptan las entradas que se listan para ellas. Cualquier otra clave se rechaza con ability_invalid_input. Las rutas REST ignoran los parámetros de consulta que no usan.
Formas de las respuestas
Toda habilidad devuelve un objeto JSON. Cuando los datos son una lista, va bajo rows: {"rows": [...]}, o {"rows": []} cuando no hay nada que informar. El mismo objeto llega desde PHP, desde la ruta /run de la Abilities API, desde MCP y desde las rutas REST, salvo las rutas marcadas con † más abajo, que devuelven un array plano.
Habilidades
Las habilidades del plugin gratuito:
| Habilidad | Ruta REST | Entrada adicional | Devuelve |
|---|---|---|---|
get-totals |
/stats/totals |
pageviews, visitors, days, avg_daily, avg_time_on_page_seconds, timed_views, bounce_rate_percent |
|
get-daily-stats |
/stats/daily † |
rows, uno por día: date, pageviews, visitors |
|
get-hourly-stats |
/stats/hourly |
rows, uno por hora: date, hour, pageviews, visitors. Como máximo los dos últimos días del rango; por defecto, hoy. |
|
get-changes |
/stats/changes |
limit (3) |
El rango frente al anterior: pageviews, visitors, change_pct, prior, una frase summary, headline, detail, mix, pages y sources que gained y lost, y avisos de health |
get-highlights |
/stats/highlights |
limit (3) |
start, end y highlights: cada uno con un kind y un text listo para citar. Por defecto, los últimos siete días completos. |
get-top-pages |
/stats/top-pages † |
limit (10) |
rows: post_id, path, title, pageviews, visitors, avg_time_on_page_seconds |
get-top-referrers |
/stats/top-referrers † |
limit (10) |
rows: url (el host de referencia), pageviews, visitors |
get-traffic-sources |
/stats/channels |
rows, uno por canal (direct, search, ai, social, referral): source, label, pageviews, visitors, share_pct |
|
get-referrer-detail |
/stats/referrer |
host (obligatorio), limit (10) |
host, label, source, totales de period, serie daily y las pages a las que envió gente |
get-ai-referrals |
/stats/ai-referrals |
start, end, since (el primer día en que se contaron rastreadores, cuando es posterior a start), referred_visitors, crawler_requests, crawler_requests_per_reader y by_source por asistente |
|
get-search-console |
/stats/search-console |
limit (10), post_id o path |
connected; después summary de todo el sitio (clicks, impressions, position, ctr) y las queries principales, o con post_id o path, las queries de esa página |
get-countries |
/stats/countries † |
limit (20) |
rows: code, name, pageviews, visitors |
get-devices |
/stats/devices |
browsers, os y device_types, cada uno con filas de label, visitors, pct |
|
get-events |
/stats/events † |
name, limit (10) |
rows de los eventos principales: name, count, unique_count. Con name, los valores de ese evento. |
get-event-detail |
/stats/event/{name} |
name (obligatorio), limit (20) |
totales de period, serie daily, value_count y los values principales |
get-post-stats |
/stats/post/{id} |
post_id (obligatorio) |
post_id, title, url, lifetime, period, daily, referrers |
get-clicks |
/stats/clicks |
limit (20) |
rows: kind, label, target, page, clicks, previous_clicks. Los enlaces a tus propias páginas y los botones más pulsados, con la página en la que estaba cada uno. |
get-404s |
/stats/404s |
limit (20) |
rows (path, hits, top_referrer), broken_links (path, hits, linked_from, linking_pages) y probes |
get-bot-stats |
/stats/bots |
filtered_requests, counted_pageviews, share_of_all_requests_pct, ai_crawler_requests y by_category (category, label, hits) |
|
get-vitals |
/stats/vitals |
rows, uno por métrica (lcp, inp, cls): metric, label, p75, display, rating, samples |
|
get-annotations |
/stats/annotations |
rows de notas del gráfico: id, date, label |
|
get-year-review |
/stats/year-review |
year (el año en curso) |
El Resumen del año de un año natural. No admite start ni end. |
get-goals |
/stats/goals † |
Necesita Pro. rows, uno por objetivo: id, name, type, pattern, value, active, completions, unique_completions, total_value |
Los nombres de las habilidades empiezan por vireo-analytics/; la tabla lo omite. /stats/goals/{id} devuelve el detalle de un objetivo.
† Por REST, estas rutas devuelven la lista como un array plano en lugar de {"rows": [...]}. En cualquier otro caso, y en el resto de rutas, la forma es la indicada.
Las rutas, las consultas, los referentes y los valores de eventos vienen de los visitantes. Toda habilidad elimina de ellos los caracteres de control, los saltos de línea y los corchetes antes de devolverlos.
Tiempo en la página y tasa de rebote, desde Vireo Analytics 0.13.0:
| Campo | Tipo | Significado |
|---|---|---|
avg_time_on_page_seconds |
entero o null |
Media de segundos activos por vista con tiempo medido. En get-totals para todo el sitio, y en cada fila de get-top-pages para esa página. null cuando ninguna vista del rango informó de un tiempo. |
timed_views |
entero | En get-totals: cuántas vistas abarca la media. 0 cuando no hay ninguna. |
bounce_rate_percent |
número o null |
En get-totals: el porcentaje de visitantes que vieron una sola página, con un decimal. null cuando el recuento de rebotes no cubre ningún día del rango, o no se contó ningún visitante. |
Qué se cuenta tiene las definiciones exactas. Ninguna de las dos cifras se puede desglosar por país, dispositivo ni fuente.
Habilidades de Pro
Todas necesitan una licencia de Vireo Pro activa. En REST, aquí start y end son opcionales y por defecto son los últimos 30 días.
| Habilidad | Ruta REST | Entrada adicional | Devuelve |
|---|---|---|---|
get-realtime |
/stats/realtime |
ninguna, ni siquiera fechas | active_last_5_minutes, window_minutes, las pages, referrers y countries principales de los últimos 15 minutos con visitors y su change respecto a los 15 anteriores, y arrived_via por canal |
get-campaigns |
/stats/campaigns |
limit (20) |
campaigns: source, medium, campaign, visitors, pageviews |
get-site-searches |
/stats/site-searches |
limit (20), view (top, zero_results o no_click; por defecto top), engine (wp, woocommerce, searchwp, relevanssi, fibosearch, elasticpress o live; por defecto todos) |
start, end, engine, un summary con el cambio respecto al periodo anterior, engines y los términos: query, searches, results, clicks, click_through_rate, average_click_position, searches_with_no_click, left_after_search |
get-search-journeys |
/stats/search-journeys |
limit (20), engine |
refinements (searched, then_searched, visits) y after_search: visitors_who_searched, orders, revenue y goal_completions (goal, completions) |
get-leads-by-source |
/stats/leads-by-source |
limit (20) |
leads: source, medium, campaign, leads, people, previous_leads, visitors, conversion_rate y los forms por los que llegaron (form, leads) |
get-outbound-clicks |
/stats/outbound |
limit (10) |
external_sites (host, clicks) y affiliate_links (path, clicks) |
get-downloads |
/stats/downloads |
limit (10) |
downloads: host, path, clicks |
get-engagement |
/stats/engagement |
limit (10) |
site y pages por página: samples, avg_seconds, avg_scroll_pct. Desde Pro 1.4.2 con Vireo Analytics 0.13.0 o posterior, avg_seconds es el tiempo en la página del plugin gratuito, y null cuando no hay ninguno para el rango. |
get-entry-exit-pages |
/stats/entry-exit |
limit (10) |
entry_pages y exit_pages: path, entries, exits, exit_ratio |
get-page-paths |
/stats/page-paths |
path, limit (20) |
Sin path, los pairs principales (from, to, visits). Con él, adónde fue la gente next (to, visits, share_pct). |
get-authors |
/stats/authors |
limit (10) |
authors: author_id, name, posts_read, pageviews, visitors, avg_per_post |
get-post-types |
/stats/post-types |
post_types: cada tipo con su número de entradas leídas, páginas vistas, visitantes y porcentaje |
|
get-taxonomy-terms |
/stats/taxonomy-terms |
taxonomy (category), limit (10) |
taxonomy, tracked_taxonomies y terms: term_id, name, slug, pageviews, visitors, url |
get-page-vitals |
/stats/page-vitals |
metric (lcp, inp o cls; por defecto lcp), limit (10) |
metric, unit y las pages peores primero: path, p75, samples, rating. Las páginas con menos de 10 muestras se omiten. |
get-cities |
/stats/cities |
limit (10) |
database_ready y cities: país, región y ciudad con páginas vistas y visitantes |
get-funnels |
/stats/funnels |
funnels: id, name y steps (step, goal_id, goal, visitors, pct_from_previous, pct_from_first) |
Pro: sitios conectados
Añadido en Pro 1.2.0, para agencias que leen varios sitios a través de una sola instalación. El sitio 0 es la instalación a la que llamas; los sitios conectados se numeran desde el 1.
| Habilidad | Ruta REST | Entrada adicional | Devuelve |
|---|---|---|---|
get-sites |
/stats/sites |
limit (100) |
count de sitios conectados, el limit del plan, accepts_site (las herramientas que admiten site) y sites: id, name, url, this_site, last_data |
get-sites-overview |
/stats/sites-overview |
start, end, prior_start, prior_end y sites, el más activo primero: los campos de get-sites más pageviews, visitors, prior_pageviews, prior_visitors, pageviews_change_pct, visitors_change_pct |
La entrada site
Con Pro 1.2.0 activo, estas habilidades gratuitas admiten una entrada adicional site (entero, 0 por defecto) para leer un sitio conectado en lugar de este: get-totals, get-daily-stats, get-hourly-stats, get-changes, get-highlights, get-top-pages, get-top-referrers, get-traffic-sources, get-referrer-detail, get-ai-referrals, get-countries, get-devices, get-events, get-event-detail, get-404s, get-bot-stats, get-vitals, get-annotations.
- Funciona a través de habilidades, MCP y la ruta
/runde la Abilities API. Las rutas REST gratuitas/stats/...no la admiten y responden por esta instalación. - Un id que no coincide con ningún sitio conectado devuelve
vireo_site_unknown(404 por REST). - Las habilidades propias de Pro no admiten
site: unsitedistinto de cero devuelvevireo_site_unsupported(400). Las habilidades gratuitas que no están en la lista anterior lo rechazan como entrada desconocida (ability_invalid_input, 400). - Sin una licencia de Pro activa, cualquier
sitedistinto de cero devuelvevireo_site_pro(403), y un usuario que no puede leer las cifras de ese sitio recibevireo_site_forbidden(403). - Las respuestas de un sitio conectado se aplanan igual que las de este sitio.
Pro: habilidades de tienda
Se registran solo mientras hay una tienda compatible activa: WooCommerce, Easy Digital Downloads, FluentCart, Freemius, Paid Memberships Pro, Restrict Content, MemberPress, LifterLMS, GiveWP o SureCart. Cada una admite store (woo, edd, fluentcart, freemius, pmpro, rcp, memberpress, lifterlms, give o surecart) para limitarla a una tienda; omítelo para incluirlas todas.
| Habilidad | Ruta REST | Entrada adicional | Devuelve |
|---|---|---|---|
get-revenue |
/stats/revenue (forma propia, más abajo) |
store |
revenue neto, orders, conversions, items, visitors, revenue_per_visitor, currency |
get-daily-revenue |
store |
days: date, revenue, orders |
|
get-revenue-forecast |
/stats/revenue-forecast |
store; no admite rango de fechas |
available, reason, history_days, min_history_days, store, currency. Cuando available: month (start, end, so_far, days_left, expected, low, high), next_30 (start, end, expected, low, high), y los days y month_days proyectados (date, revenue). Con menos de 28 días de pedidos, o sin ingresos en las últimas 8 semanas, da available: false con un reason y un message. |
get-revenue-by-source |
/stats/sources (forma propia, más abajo) |
store, limit (10) |
sources por fuente, medio y campaña, con pedidos y valor medio del pedido |
get-revenue-by-landing-page |
/stats/landing-pages |
store, limit (10) |
pages: path, orders, revenue, aov, entries, conversion |
get-top-products |
/stats/products (forma propia, más abajo) |
store, limit (10) |
products: product_id, name, views, add_to_cart, purchases, revenue, conv_rate |
get-store-funnel |
/stats/store-funnel |
store |
stages desde la vista de producto hasta la compra: stage, count, porcentaje respecto a la etapa anterior y si la tienda lo informa |
get-subscriptions |
/stats/subscriptions |
store, limit (10) |
mrr, subscribers, currency, other_currencies, period (start_mrr, end_mrr, net, new, expansion, reactivation, contraction, churn, recuentos de suscriptores, active_at_start, active_at_end, logo_churn_rate), una trend de 12 meses, y el MRR by_source y by_landing_page |
get-stores |
Qué tiendas están connected y cuáles tienen pedidos en el rango (with_orders) |
/stats/revenue, /stats/products y /stats/sources son anteriores a las habilidades y conservan su propia forma de respuesta. /stats/revenue devuelve range, store, totals, daily, revenue_per_visitor y currency; /stats/products y /stats/sources devuelven sus filas como una lista plana. Las tres exigen start y end.
Otros tres informes son solo rutas REST, sin habilidad ni herramienta MCP. Admiten start, end, limit y store igual que /stats/revenue, y devuelven los campos de resumen con una lista al lado:
| Ruta REST | Devuelve |
|---|---|
/stats/abandonment |
abandoned, value, valued, checkouts, rate, carts y sources: source, medium, campaign, abandoned, value |
/stats/coupons |
orders, with_coupon, discount, share y coupons: code, orders, revenue, discount, aov |
/stats/refunds |
orders, full, partial, amount, placed, rate y refunds: store, order_id, date, refunded_date, total, refunded, full, is_renewal, source, medium, campaign, url |
Cada una devuelve también currency. Los ingresos son netos de reembolsos. Los totales están en la moneda de la tienda, sin conversión.
Rutas REST
Todas son GET bajo /wp-json/vireo-analytics/v1 y se autentican como se describe en Consulta tus estadísticas con la API REST. La ruta de cada informe está en las tablas anteriores.
GET /stats/last-hour devuelve pageviews de los últimos 60 minutos, una series de doce recuentos de cinco minutos y as_of (hora Unix), para la tarjeta Última hora; no tiene habilidad ni herramienta MCP.
Una ruta más no sirve para leer datos: con Pro y Freemius, POST /freemius/webhook recibe los eventos de pago de Freemius. Consulta Seguimiento de ingresos.
Rutas de la Abilities API
| Ruta | Uso |
|---|---|
GET /wp-json/wp-abilities/v1/abilities?category=vireo-analytics |
Lista las habilidades de Vireo, con sus esquemas de entrada y de salida |
GET /wp-json/wp-abilities/v1/abilities/{name}/run?input[key]=value |
Ejecuta una. El nombre conserva su barra, por ejemplo vireo-analytics/get-totals. |
MCP
/wp-json/vireo-analytics/mcp sirve como herramienta cada habilidad de arriba, con el nombre escrito con un guion en lugar de la barra: vireo-analytics-get-top-pages. Un desarrollador puede cambiar la lista con el filtro vireo_mcp_tools.