> ## 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étriques d’achat > Renvoie le tableau de bord Shopping Insights d’un site web sur une période : fréquence d’apparition des produits de la marque dans les réponses shopping IA (carrousels de produits) face aux concurrents, position et prix moyens, principaux produits propres et concurrents, classement des concurrents, répartition par distributeur, distribution des positions, comparaison des prix et tendance quotidienne des apparitions. Un seul appel renvoie tous les blocs affichés sur la page Shopping de l’application. `models` accepte `chatgpt`, `ai_mode`, `gemini`, `perplexity` et `copilot`. Nécessite une offre payante. ## OpenAPI ````yaml fr/api-reference/openapi.json post /api/v1/metrics/shopping openapi: 3.1.0 info: title: API AthenaHQ description: >- L’API AthenaHQ permet de gérer vos sites et prompts par programme pour l’optimisation de contenu par IA. version: 1.0.0 contact: email: support@athenahq.ai servers: - url: https://api.athenahq.ai description: Serveur de production security: - apiKey: [] tags: - name: Basics description: Opérations API principales pour gérer sites et prompts - name: Metrics description: Points de terminaison de métriques et analyses de visibilité IA - name: Billing description: Points de facturation et crédits pour gérer la consommation - name: Team Management description: Points de terminaison de gestion des membres et invitations - name: Groups description: Points de terminaison de gestion des groupes de sites - name: Content description: >- Points de terminaison Content Hub : onglets, URL suivies et détail des prompts par URL. - name: Pitch Workspace description: >- Points de terminaison des rapports Pitch Workspace : exécutions à l’échelle de l’organisation avec concurrents, prompts, attributs et métriques agrégées. - name: Knowledge Base description: >- Endpoints de lecture de la base de connaissances de la marque — faits approuvés et piliers qui les organisent. paths: /api/v1/metrics/shopping: post: tags: - Metrics summary: Métriques d’achat description: >- Renvoie le tableau de bord Shopping Insights d’un site web sur une période : fréquence d’apparition des produits de la marque dans les réponses shopping IA (carrousels de produits) face aux concurrents, position et prix moyens, principaux produits propres et concurrents, classement des concurrents, répartition par distributeur, distribution des positions, comparaison des prix et tendance quotidienne des apparitions. Un seul appel renvoie tous les blocs affichés sur la page Shopping de l’application. `models` accepte `chatgpt`, `ai_mode`, `gemini`, `perplexity` et `copilot`. Nécessite une offre payante. operationId: getShoppingMetrics requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/ShoppingMetricsRequest' responses: '200': description: Réponse réussie avec les métriques d’achat 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: Requête incorrecte — paramètres invalides 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: Non autorisé — clé API invalide ou absente content: application/json: schema: $ref: '#/components/schemas/Error' '403': description: >- Interdit — aucun accès au site, concurrent d’un autre site ou organisation sur 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: Site introuvable content: application/json: schema: $ref: '#/components/schemas/Error' example: error: Website not found '500': description: Erreur interne du serveur content: application/json: schema: $ref: '#/components/schemas/Error' security: - apiKey: [] components: schemas: ShoppingMetricsRequest: type: object description: Corps de la requête pour l’endpoint des indicateurs shopping required: - website_id - filters properties: website_id: type: string format: uuid description: ID du site dont interroger les métriques d’achat example: 123e4567-e89b-12d3-a456-426614174000 filters: $ref: '#/components/schemas/ShoppingMetricsFilters' top_products_limit: type: integer minimum: 1 maximum: 50 default: 10 description: >- Nombre de produits à renvoyer dans chacun de top_own_products et 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: >- Blocs du tableau de bord Shopping Insights. Taux de 0 à 100 % ; positions à partir de 1, un nombre faible étant meilleur. required: - summary - offer_summary - top_own_products - top_competitor_products - competitor_breakdown - merchant_breakdown - position_distribution - price_comparison - trend properties: summary: type: object description: Totaux principaux sur toutes les réponses shopping de la période 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: Réponses contenant un carrousel de produits example: 50 responses_with_own_products: type: integer description: Réponses d’achat incluant au moins un produit de la marque example: 20 appearance_rate: type: number description: >- responses_with_own_products / total_shopping_responses en pourcentage de 0 à 100 example: 40 total_products: type: integer description: Apparitions des produits dans l’ensemble des réponses shopping example: 150 own_products: type: integer description: Apparitions des produits propres à la marque example: 40 competitor_products: type: integer description: Apparitions attribuées aux concurrents suivis example: 110 avg_own_position: type: - number - 'null' description: Position moyenne des produits de la marque dans les carrousels example: 2.5 avg_competitor_position: type: - number - 'null' description: Position moyenne des produits concurrents dans le carrousel example: 4.2 offer_summary: type: object description: >- Offres de distributeurs (prix affichés) associées aux produits de la période required: - total_offers - products_with_offers - competitor_offers - currency - avg_price properties: total_offers: type: integer description: Offres associées aux produits de la marque example: 200 products_with_offers: type: integer description: Apparitions de produits de marque comportant au moins une offre example: 80 competitor_offers: type: integer description: Offres des produits concurrents example: 60 currency: type: string description: Devise de avg_price, la devise d’offre la plus fréquente example: USD avg_price: type: - number - 'null' description: Prix moyen des offres des produits de la marque example: 149.99 top_own_products: type: array description: >- Produits de la marque les plus affichés, par nombre d’apparitions décroissant items: $ref: '#/components/schemas/ShoppingProduct' top_competitor_products: type: array description: >- Produits concurrents les plus souvent affichés, par nombre d’apparitions décroissant items: $ref: '#/components/schemas/ShoppingCompetitorProduct' competitor_breakdown: type: array description: >- Classement concurrentiel : concurrents suivis apparaissant le plus dans les réponses d’achat 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: Nom du concurrent example: Rival Runners product_count: type: integer description: Apparitions de produits attribuées au concurrent example: 30 avg_position: type: - number - 'null' description: >- Position moyenne des produits concurrents dans les carrousels ; null sans position connue example: 3.5 avg_rating: type: - number - 'null' description: Note moyenne affichée des produits concurrents example: 4.2 response_count: type: integer description: Réponses d’achat dans lesquelles le concurrent apparaît example: 15 merchant_breakdown: type: array description: >- Répartition des revendeurs des produits dans les réponses IA, propres et concurrents 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: Apparitions de produits de marque chez ce revendeur example: 15 competitor_count: type: integer description: Apparitions de produits concurrents chez ce revendeur example: 35 own_avg_position: type: - number - 'null' description: Position moyenne des produits de la marque chez ce revendeur example: 2.8 competitor_avg_position: type: - number - 'null' description: Position moyenne des produits concurrents de ce distributeur example: 3.6 own_response_count: type: integer description: Réponses d’achat avec un produit de marque de ce revendeur example: 12 competitor_response_count: type: integer description: Réponses d’achat avec un produit concurrent de ce revendeur example: 22 position_distribution: type: array description: >- Répartition des classements : occupant de chaque position du carrousel items: type: object required: - position - count - own_count - competitor_count properties: position: type: integer description: Position dans le carrousel à partir de 1 example: 1 count: type: integer description: Apparitions de produits à cette position example: 40 own_count: type: integer description: Apparitions de produits de marque à cette position example: 12 competitor_count: type: integer description: Apparitions de produits concurrents à cette position example: 28 price_comparison: type: array description: >- Fourchette des prix d’offre des produits de marque et concurrents, par devise 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: Prix moyen des offres example: 149.99 min_price: type: - number - 'null' description: Prix d’offre le plus bas example: 89 max_price: type: - number - 'null' description: Prix d’offre le plus élevé example: 219 product_count: type: integer description: Apparitions de produits avec un prix interprétable example: 80 trend: type: array description: Apparitions quotidiennes des produits, propres et concurrents 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: Réponses d’achat de ce jour example: 4 responses_with_own: type: integer description: Réponses d’achat de ce jour contenant un produit de la marque example: 2 Error: type: object description: Objet de réponse d’erreur required: - error properties: error: type: string description: Message expliquant l’erreur example: Unauthorized ShoppingMetricsFilters: type: object description: >- Filtres de l’endpoint des indicateurs shopping. Seuls les filtres appliqués par la page Shopping Insights sont acceptés ; toute autre clé de filtre est rejetée avec 400. required: - start_date properties: start_date: type: string format: date description: Début de période inclus, YYYY-MM-DD (UTC) example: '2026-08-01' end_date: type: string format: date description: >- Fin de période incluse, YYYY-MM-DD (UTC). Aujourd’hui par défaut. Doit être au moins start_date. example: '2026-08-31' schedule_id: $ref: '#/components/schemas/PromptScheduleSelection' models: type: array description: Modèles compatibles avec l’achat à inclure. Omettez pour tous. items: type: string enum: - chatgpt - ai_mode - gemini - perplexity - copilot example: - chatgpt competitor_ids: type: array description: >- UUID concurrents à conserver dans leurs blocs. Les produits propres sont toujours inclus. Omettez pour tous les concurrents. items: type: string format: uuid prompt_tags: type: array description: >- ID de tags de prompts selon lesquels filtrer (répertoriez les tags via GET /api/v1/prompt-tags). Omettez pour tous les tags. items: type: string format: uuid prompt_tags_operator: type: string enum: - is_any_of - has_all_of description: >- Combinaison de prompt_tags : is_any_of correspond à une des étiquettes ; has_all_of exige toutes les étiquettes. Par défaut : is_any_of. target_identifiers: type: array description: >- Identifiants cibles pour filtrer les réponses. La chaîne littérale no-identifier sélectionne les réponses sans identifiant cible. Omettez pour toutes. items: type: string ShoppingProduct: type: object required: - title - merchant - appearances - avg_position - avg_rating - image_url - product_url properties: title: type: string description: Titre du produit tel qu’affiché dans la réponse shopping example: Acme Trail Runner 3 merchant: type: - string - 'null' description: Revendeur du produit, si nommé dans la réponse example: Amazon appearances: type: integer description: Nombre de réponses d’achat contenant le produit example: 25 avg_position: type: - number - 'null' description: >- Position moyenne dans le carrousel, à partir de 1, faible étant meilleur ; null sans position connue example: 1.5 avg_rating: type: - number - 'null' description: Note moyenne affichée du produit, si disponible example: 4.5 image_url: type: - string - 'null' description: URL de l’image du produit dans la réponse example: https://example.com/trail-runner.jpg product_url: type: - string - 'null' description: URL de la fiche produit provenant de la réponse 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: Titre du produit tel qu’affiché dans la réponse shopping example: Acme Trail Runner 3 merchant: type: - string - 'null' description: Revendeur du produit, si nommé dans la réponse example: Amazon appearances: type: integer description: Nombre de réponses d’achat contenant le produit example: 25 avg_position: type: - number - 'null' description: >- Position moyenne dans le carrousel, à partir de 1, faible étant meilleur ; null sans position connue example: 1.5 avg_rating: type: - number - 'null' description: Note moyenne affichée du produit, si disponible example: 4.5 image_url: type: - string - 'null' description: URL de l’image du produit dans la réponse example: https://example.com/trail-runner.jpg product_url: type: - string - 'null' description: URL de la fiche produit provenant de la réponse example: https://example.com/products/trail-runner-3 competitor_id: type: - string - 'null' description: Concurrent auquel le produit est attribué example: 123e4567-e89b-12d3-a456-426614174222 PromptScheduleSelection: description: >- Sélectionnez une planification de collecte, avec la valeur renvoyée par GET /api/v1/prompt-schedules. Par défaut inclut l’historique antérieur à la transition et les exécutions ponctuelles ; les planifications archivées conservent leurs résultats. L’ancien jeton manual est accepté comme alias de default. Ce champ accepte une seule planification ; une liste renvoie 400. default: default oneOf: - type: string enum: - default - manual - type: string format: uuid securitySchemes: apiKey: type: apiKey in: header name: x-api-key description: >- Clé API d’authentification. Créez-en une [ici](https://app.athenahq.ai/organization?tab=api). ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.