> ## Documentation Index > Fetch the complete documentation index at: https://docs.athenahq.ai/llms.txt > Use this file to discover all available pages before exploring further. # Métricas de compras > Devuelve el panel de análisis de compras de un sitio en un intervalo: frecuencia de aparición de productos propios frente a competidores en carruseles de respuestas de IA, posición y precio medios, productos principales, clasificación de competidores, desglose por vendedor, distribución de posiciones, comparación de precios y tendencia diaria. Una llamada devuelve todos los bloques de la página de compras. `models` acepta `chatgpt`, `ai_mode`, `gemini`, `perplexity` y `copilot`. Requiere un plan de pago. ## OpenAPI ````yaml es/api-reference/openapi.json post /api/v1/metrics/shopping openapi: 3.1.0 info: title: API de AthenaHQ description: >- La API de AthenaHQ ofrece acceso programático para gestionar tus sitios web y consultas para optimizar el contenido con IA. version: 1.0.0 contact: email: support@athenahq.ai servers: - url: https://api.athenahq.ai description: Servidor de producción security: - apiKey: [] tags: - name: Basics description: Operaciones principales de la API para gestionar sitios web y consultas - name: Metrics description: Endpoints de métricas y análisis para monitorizar la visibilidad en IA - name: Billing description: Endpoints de facturación y créditos para gestionar el uso - name: Team Management description: Endpoints para gestionar miembros del equipo e invitaciones - name: Groups description: Endpoints para gestionar grupos de sitios web - name: Content description: >- Endpoints para acceder a los datos del centro de contenidos: pestañas, URL monitorizadas y desglose de consultas por URL. - name: Pitch Workspace description: >- Endpoints para acceder a los informes del espacio de propuestas: ejecuciones de propuestas con alcance de organización, con competidores, consultas, atributos y métricas agregadas. - name: Knowledge Base description: >- Endpoints para leer la base de conocimientos de la marca: datos aprobados sobre la marca y los pilares que los organizan. paths: /api/v1/metrics/shopping: post: tags: - Metrics summary: Métricas de compras description: >- Devuelve el panel de análisis de compras de un sitio en un intervalo: frecuencia de aparición de productos propios frente a competidores en carruseles de respuestas de IA, posición y precio medios, productos principales, clasificación de competidores, desglose por vendedor, distribución de posiciones, comparación de precios y tendencia diaria. Una llamada devuelve todos los bloques de la página de compras. `models` acepta `chatgpt`, `ai_mode`, `gemini`, `perplexity` y `copilot`. Requiere un plan de pago. operationId: getShoppingMetrics requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/ShoppingMetricsRequest' responses: '200': description: Respuesta correcta con métricas de compras content: application/json: schema: type: object required: - data properties: data: $ref: '#/components/schemas/ShoppingMetricsData' example: data: summary: total_shopping_responses: 50 responses_with_own_products: 20 appearance_rate: 40 total_products: 150 own_products: 40 competitor_products: 110 avg_own_position: 2.5 avg_competitor_position: 4.2 offer_summary: total_offers: 200 products_with_offers: 80 competitor_offers: 60 currency: USD avg_price: 149.99 top_own_products: - title: Acme Trail Runner 3 merchant: Amazon appearances: 25 avg_position: 1.5 avg_rating: 4.5 image_url: https://example.com/trail-runner.jpg product_url: https://example.com/products/trail-runner-3 top_competitor_products: - title: Rival Speed 2 merchant: Walmart appearances: 18 avg_position: 2.2 avg_rating: 4.1 image_url: null product_url: https://rival.example/speed-2 competitor_id: 123e4567-e89b-12d3-a456-426614174222 competitor_breakdown: - competitor_id: 123e4567-e89b-12d3-a456-426614174222 competitor_name: Rival Runners product_count: 30 avg_position: 3.5 avg_rating: 4.2 response_count: 15 merchant_breakdown: - merchant: Amazon own_count: 15 competitor_count: 35 own_avg_position: 2.8 competitor_avg_position: 3.6 own_response_count: 12 competitor_response_count: 22 position_distribution: - position: 1 count: 40 own_count: 12 competitor_count: 28 - position: 2 count: 38 own_count: 10 competitor_count: 28 price_comparison: - category: own currency: USD avg_price: 149.99 min_price: 89 max_price: 219 product_count: 80 - category: competitor currency: USD avg_price: 132.5 min_price: 59 max_price: 249 product_count: 60 trend: - date: '2026-08-01' total_products: 5 own_products: 2 competitor_products: 3 total_responses: 4 responses_with_own: 2 '400': description: 'Solicitud incorrecta: parámetros no válidos' content: application/json: schema: $ref: '#/components/schemas/Error' examples: missing_website_id: value: error: 'website_id: Required' missing_start_date: value: error: >- filters.start_date: Invalid input: expected string, received undefined unsupported_filter: value: error: 'filters: Unrecognized key: "prompt_ids"' '401': description: 'Sin autorización: falta la clave de API o no es válida' content: application/json: schema: $ref: '#/components/schemas/Error' '403': description: >- Acceso denegado: no tienes acceso a este sitio web, un ID de competidor pertenece a otro sitio web o la organización tiene el plan Free content: application/json: schema: $ref: '#/components/schemas/Error' examples: website: value: error: Unauthorized access to this website competitors: value: error: Unauthorized access to these competitors free_plan: value: error: Shopping requires a paid plan '404': description: Sitio web no encontrado content: application/json: schema: $ref: '#/components/schemas/Error' example: error: Website not found '500': description: Error interno del servidor content: application/json: schema: $ref: '#/components/schemas/Error' security: - apiKey: [] components: schemas: ShoppingMetricsRequest: type: object description: Cuerpo de la solicitud del endpoint de métricas de compras required: - website_id - filters properties: website_id: type: string format: uuid description: ID del sitio web cuyas métricas de compras se quieren consultar example: 123e4567-e89b-12d3-a456-426614174000 filters: $ref: '#/components/schemas/ShoppingMetricsFilters' top_products_limit: type: integer minimum: 1 maximum: 50 default: 10 description: >- Número de productos que se devolverán en cada uno de top_own_products y top_competitor_products example: website_id: 123e4567-e89b-12d3-a456-426614174000 filters: start_date: '2026-08-01' end_date: '2026-08-31' models: - chatgpt top_products_limit: 10 ShoppingMetricsData: type: object description: >- Bloques del panel de análisis de compras. Los porcentajes van de 0 a 100; las posiciones empiezan por 1 (cuanto menor, mejor). required: - summary - offer_summary - top_own_products - top_competitor_products - competitor_breakdown - merchant_breakdown - position_distribution - price_comparison - trend properties: summary: type: object description: >- Recuentos principales de todas las respuestas de compras del intervalo required: - total_shopping_responses - responses_with_own_products - appearance_rate - total_products - own_products - competitor_products - avg_own_position - avg_competitor_position properties: total_shopping_responses: type: integer description: Respuestas que incluyeron un carrusel de productos example: 50 responses_with_own_products: type: integer description: >- Respuestas de compras que incluyen al menos un producto de la marca example: 20 appearance_rate: type: number description: >- responses_with_own_products / total_shopping_responses como porcentaje de 0-100 example: 40 total_products: type: integer description: Apariciones de productos en todas las respuestas de compras example: 150 own_products: type: integer description: Apariciones de los productos de la propia marca example: 40 competitor_products: type: integer description: Apariciones atribuidas a los competidores que sigues example: 110 avg_own_position: type: - number - 'null' description: Posición media de los productos de la marca en el carrusel example: 2.5 avg_competitor_position: type: - number - 'null' description: Posición media de los productos de la competencia en el carrusel example: 4.2 offer_summary: type: object description: >- Ofertas comerciales (precios publicados) asociadas a los productos del intervalo required: - total_offers - products_with_offers - competitor_offers - currency - avg_price properties: total_offers: type: integer description: Ofertas asociadas a los productos de la marca example: 200 products_with_offers: type: integer description: Apariciones de productos de la marca con al menos una oferta example: 80 competitor_offers: type: integer description: Ofertas asociadas a productos de competidores example: 60 currency: type: string description: Moneda de avg_price (la moneda más habitual de las ofertas) example: USD avg_price: type: - number - 'null' description: Precio medio de oferta de los productos de la marca example: 149.99 top_own_products: type: array description: >- Productos de la marca más mostrados, ordenados por número de apariciones items: $ref: '#/components/schemas/ShoppingProduct' top_competitor_products: type: array description: >- Productos de la competencia más mostrados, ordenados por número de apariciones items: $ref: '#/components/schemas/ShoppingCompetitorProduct' competitor_breakdown: type: array description: >- Clasificación de competidores: qué competidores monitorizados aparecen más en las respuestas de compras items: type: object required: - competitor_id - competitor_name - product_count - avg_position - avg_rating - response_count properties: competitor_id: type: string format: uuid example: 123e4567-e89b-12d3-a456-426614174222 competitor_name: type: - string - 'null' description: Nombre del competidor example: Rival Runners product_count: type: integer description: Apariciones de productos atribuidas al competidor example: 30 avg_position: type: - number - 'null' description: >- Posición media de los productos del competidor en el carrusel; null si ninguna aparición tiene posición example: 3.5 avg_rating: type: - number - 'null' description: >- Valoración media que se muestra para los productos del competidor example: 4.2 response_count: type: integer description: Respuestas de compras en las que apareció el competidor example: 15 merchant_breakdown: type: array description: >- Desglose por vendedor: dónde se ofrecen los productos en las respuestas de IA, propios y de la competencia items: type: object required: - merchant - own_count - competitor_count - own_avg_position - competitor_avg_position - own_response_count - competitor_response_count properties: merchant: type: string example: Amazon own_count: type: integer description: >- Apariciones de productos de la marca ofrecidos por este vendedor example: 15 competitor_count: type: integer description: >- Apariciones de productos de la competencia ofrecidos por este vendedor example: 35 own_avg_position: type: - number - 'null' description: >- Posición media de los productos de la marca ofrecidos por este vendedor example: 2.8 competitor_avg_position: type: - number - 'null' description: >- Posición media de los productos de la competencia ofrecidos por este vendedor example: 3.6 own_response_count: type: integer description: >- Respuestas de compras con un producto de la marca ofrecido por este vendedor example: 12 competitor_response_count: type: integer description: >- Respuestas de compras con un producto de la competencia ofrecido por este vendedor example: 22 position_distribution: type: array description: 'Distribución de posiciones: quién ocupa cada posición del carrusel' items: type: object required: - position - count - own_count - competitor_count properties: position: type: integer description: Posición en el carrusel, empezando en uno example: 1 count: type: integer description: Apariciones de productos en esta posición example: 40 own_count: type: integer description: Apariciones de productos de la marca en esta posición example: 12 competitor_count: type: integer description: Apariciones de productos de la competencia en esta posición example: 28 price_comparison: type: array description: >- Intervalo de precios de oferta de los productos de la marca frente a la competencia, por moneda items: type: object required: - category - currency - avg_price - min_price - max_price - product_count properties: category: type: string enum: - own - competitor currency: type: string example: USD avg_price: type: - number - 'null' description: Precio medio de oferta example: 149.99 min_price: type: - number - 'null' description: Precio mínimo de oferta example: 89 max_price: type: - number - 'null' description: Precio máximo de oferta example: 219 product_count: type: integer description: >- Apariciones de productos con un precio que se puede interpretar example: 80 trend: type: array description: Apariciones diarias de productos propios y de la competencia items: type: object required: - date - total_products - own_products - competitor_products - total_responses - responses_with_own properties: date: type: string format: date example: '2026-08-01' total_products: type: integer example: 5 own_products: type: integer example: 2 competitor_products: type: integer example: 3 total_responses: type: integer description: Respuestas de compras de ese día example: 4 responses_with_own: type: integer description: Respuestas de compras de ese día con un producto de la marca example: 2 Error: type: object description: Objeto de respuesta de error required: - error properties: error: type: string description: Mensaje de error que describe qué ha fallado example: Unauthorized ShoppingMetricsFilters: type: object description: >- Filtros para el endpoint de métricas de compras. Solo se aceptan los que aplica la página de análisis de compras; cualquier otra clave de filtro se rechaza con 400. required: - start_date properties: start_date: type: string format: date description: Inicio del intervalo de fechas, YYYY-MM-DD (UTC), incluido example: '2026-08-01' end_date: type: string format: date description: >- Fin del intervalo de fechas, YYYY-MM-DD (UTC), incluido. Por defecto, hoy. Debe ser igual o posterior a start_date. example: '2026-08-31' schedule_id: $ref: '#/components/schemas/PromptScheduleSelection' models: type: array description: >- Modelos con funciones de compras que se incluirán. Omítelo para incluirlos todos. items: type: string enum: - chatgpt - ai_mode - gemini - perplexity - copilot example: - chatgpt competitor_ids: type: array description: >- UUID de competidores que se conservarán en los bloques de competidores. Los productos propios siempre se incluyen. Omítelos para incluir a todos los competidores. items: type: string format: uuid prompt_tags: type: array description: >- ID de etiquetas por los que se filtrarán las consultas (obtén las etiquetas con GET /api/v1/prompt-tags). Omítelos para incluirlas todas. items: type: string format: uuid prompt_tags_operator: type: string enum: - is_any_of - has_all_of description: >- Cómo se combinan prompt_tags: is_any_of selecciona consultas con cualquiera de las etiquetas; has_all_of, solo las que tienen todas. Por defecto, is_any_of. target_identifiers: type: array description: >- Identificadores de destino por los que se filtrarán las respuestas. La cadena literal no-identifier selecciona las respuestas sin identificador de destino. Omítelos para incluirlas todas. items: type: string ShoppingProduct: type: object required: - title - merchant - appearances - avg_position - avg_rating - image_url - product_url properties: title: type: string description: Título del producto tal como aparece en la respuesta de compras example: Acme Trail Runner 3 merchant: type: - string - 'null' description: Vendedor que ofrece el producto, si la respuesta menciona alguno example: Amazon appearances: type: integer description: Número de respuestas de compras en las que ha aparecido el producto example: 25 avg_position: type: - number - 'null' description: >- Posición media en el carrusel, empezando por 1 (cuanto menor, mejor); null si ninguna aparición tiene posición example: 1.5 avg_rating: type: - number - 'null' description: Valoración media mostrada para el producto, si existe example: 4.5 image_url: type: - string - 'null' description: URL de la imagen de producto incluida en la respuesta example: https://example.com/trail-runner.jpg product_url: type: - string - 'null' description: URL de la página de producto incluida en la respuesta example: https://example.com/products/trail-runner-3 ShoppingCompetitorProduct: type: object required: - title - merchant - appearances - avg_position - avg_rating - image_url - product_url - competitor_id properties: title: type: string description: Título del producto tal como aparece en la respuesta de compras example: Acme Trail Runner 3 merchant: type: - string - 'null' description: Vendedor que ofrece el producto, si la respuesta menciona alguno example: Amazon appearances: type: integer description: Número de respuestas de compras en las que ha aparecido el producto example: 25 avg_position: type: - number - 'null' description: >- Posición media en el carrusel, empezando por 1 (cuanto menor, mejor); null si ninguna aparición tiene posición example: 1.5 avg_rating: type: - number - 'null' description: Valoración media mostrada para el producto, si existe example: 4.5 image_url: type: - string - 'null' description: URL de la imagen de producto incluida en la respuesta example: https://example.com/trail-runner.jpg product_url: type: - string - 'null' description: URL de la página de producto incluida en la respuesta example: https://example.com/products/trail-runner-3 competitor_id: type: - string - 'null' description: Competidor al que se atribuyó el producto example: 123e4567-e89b-12d3-a456-426614174222 PromptScheduleSelection: description: >- Selecciona una programación de recopilación. Usa la selección devuelta por GET /api/v1/prompt-schedules. La predeterminada incluye el historial anterior al cambio y ejecuciones puntuales; las archivadas conservan resultados. El antiguo token manual se admite como alias de default. Solo acepta una programación; una lista devuelve 400. default: default oneOf: - type: string enum: - default - manual - type: string format: uuid securitySchemes: apiKey: type: apiKey in: header name: x-api-key description: >- Clave de API para autenticarse. Puedes crear una [aquí](https://app.athenahq.ai/organization?tab=api). ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.