Menú de la documentaciónReferencia de habilidades y REST

Referencia de habilidades y REST

Todas las habilidades y rutas REST de Vireo, gratuitas y de Pro, con sus entradas, valores por defecto y respuestas. Las herramientas MCP usan los mismos nombres.

En esta página

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 /run de 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: un site distinto de cero devuelve vireo_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 site distinto de cero devuelve vireo_site_pro (403), y un usuario que no puede leer las cifras de ese sitio recibe vireo_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.

Actualizado el 19 de octubre de 2026. ¿Algo está mal o falta? Avísanos.