--- title: "Shopping Metrics" method: POST path: "/api/v1/metrics/shopping" tags: ["Metrics"] --- # Shopping Metrics `POST /api/v1/metrics/shopping` ## Request - Base URL: `https://api.athenahq.ai` - URL: `https://api.athenahq.ai/api/v1/metrics/shopping` - Auth: API key in header `x-api-key` Returns the Shopping Insights dashboard for a website over a date range: how often the brand's products appear in AI shopping answers (product carousels) versus competitors, average position and price, the top own and competitor products, the competitor leaderboard, retailer breakdown, rank distribution, price comparison, and a daily appearances trend. One call returns every block the in-app Shopping page renders. `models` accepts `chatgpt`, `ai_mode`, `gemini`, `perplexity` and `copilot`. Requires a paid plan. ## Request body - ShoppingMetricsRequest: Request body for the shopping metrics endpoint - `website_id` string, uuid, required: The ID of the website to query shopping metrics for - `filters` ShoppingMetricsFilters, required: Filters for the shopping metrics endpoint. Only the filters the Shopping Insights page applies are accepted; any other filter key is rejected with 400. - `start_date` string, date, required: Start of the date range, YYYY-MM-DD (UTC), inclusive - `end_date` string, date: End of the date range, YYYY-MM-DD (UTC), inclusive. Defaults to today. Must be on or after start_date. - `schedule_id` union: Select one streaming schedule. Use the selection returned by GET /api/v1/prompt-schedules. Default includes all pre-cutover history and ad hoc runs; archived schedules retain results. The retired manual token is accepted as an alias of default. This field takes one schedule; a list returns 400. - 'default' | 'manual' - string, uuid - `models` string[]: Shopping-capable models to include. Omit for all. - `competitor_ids` string[]: Competitor UUIDs to keep in the competitor blocks. Own products are always included. Omit for all competitors. - `prompt_tags` string[]: Prompt tag IDs to filter prompts by (list tags with GET /api/v1/prompt-tags). Omit for all tags. - `prompt_tags_operator` 'is_any_of' | 'has_all_of': How prompt_tags combine: is_any_of matches prompts with any listed tag, has_all_of only prompts carrying every listed tag. Defaults to is_any_of. - `target_identifiers` string[]: Target identifier strings to filter responses to. The literal string no-identifier selects responses with no target identifier. Omit for all. - `top_products_limit` integer: How many products to return in each of top_own_products and top_competitor_products ## Response `200` Successful response with shopping metrics - object - `data` ShoppingMetricsData, required: The Shopping Insights dashboard blocks. Rates are percentages 0-100; positions are 1-based (lower is better). - `summary` object, required: Headline counts across every shopping answer in the range - `total_shopping_responses` integer, required: Responses that included a product carousel - `responses_with_own_products` integer, required: Shopping answers that included at least one of the brand's products - `appearance_rate` number, required: responses_with_own_products / total_shopping_responses as a percentage 0-100 - `total_products` integer, required: Product appearances across all shopping answers - `own_products` integer, required: Appearances of the brand's own products - `competitor_products` integer, required: Appearances attributed to tracked competitors - `avg_own_position` number, nullable, required: Average carousel position of the brand's products - `avg_competitor_position` number, nullable, required: Average carousel position of competitor products - `offer_summary` object, required: Retail offers (price listings) attached to the products in the range - `total_offers` integer, required: Offers attached to the brand's products - `products_with_offers` integer, required: Brand product appearances that carried at least one offer - `competitor_offers` integer, required: Offers attached to competitor products - `currency` string, required: Currency of avg_price (the most common offer currency) - `avg_price` number, nullable, required: Average offer price of the brand's products - `top_own_products` ShoppingProduct[], required: The brand's most frequently shown products, most appearances first - `title` string, required: Product title as shown in the shopping answer - `merchant` string, nullable, required: Retailer the product was listed from, when the answer named one - `appearances` integer, required: Number of shopping answers the product appeared in - `avg_position` number, nullable, required: Average 1-based position in the carousel (lower is better); null when no appearance carried a position - `avg_rating` number, nullable, required: Average rating shown for the product, when any - `image_url` string, nullable, required: Product image URL from the answer - `product_url` string, nullable, required: Product page URL from the answer - `top_competitor_products` ShoppingCompetitorProduct[], required: Competitor products shown most often, most appearances first - `title` string, required: Product title as shown in the shopping answer - `merchant` string, nullable, required: Retailer the product was listed from, when the answer named one - `appearances` integer, required: Number of shopping answers the product appeared in - `avg_position` number, nullable, required: Average 1-based position in the carousel (lower is better); null when no appearance carried a position - `avg_rating` number, nullable, required: Average rating shown for the product, when any - `image_url` string, nullable, required: Product image URL from the answer - `product_url` string, nullable, required: Product page URL from the answer - `competitor_id` string, nullable, required: Competitor the product was attributed to - `competitor_breakdown` object[], required: Competitor leaderboard: which tracked competitors show up most in shopping answers - `competitor_id` string, uuid, required - `competitor_name` string, nullable, required: Competitor name - `product_count` integer, required: Product appearances attributed to the competitor - `avg_position` number, nullable, required: Average carousel position of the competitor's products; null when no appearance carried a position - `avg_rating` number, nullable, required: Average rating shown for the competitor's products - `response_count` integer, required: Shopping answers the competitor appeared in - `merchant_breakdown` object[], required: Retailer breakdown: where products are stocked in AI answers, own versus competitor - `merchant` string, required - `own_count` integer, required: Brand product appearances listed from this retailer - `competitor_count` integer, required: Competitor product appearances listed from this retailer - `own_avg_position` number, nullable, required: Average position of the brand's products from this retailer - `competitor_avg_position` number, nullable, required: Average position of competitor products from this retailer - `own_response_count` integer, required: Shopping answers with a brand product from this retailer - `competitor_response_count` integer, required: Shopping answers with a competitor product from this retailer - `position_distribution` object[], required: Rank distribution: who occupies each carousel position - `position` integer, required: 1-based carousel position - `count` integer, required: Product appearances at this position - `own_count` integer, required: Brand product appearances at this position - `competitor_count` integer, required: Competitor product appearances at this position - `price_comparison` object[], required: Offer price range for the brand's products versus competitors, per currency - `category` 'own' | 'competitor', required - `currency` string, required - `avg_price` number, nullable, required: Average offer price - `min_price` number, nullable, required: Lowest offer price - `max_price` number, nullable, required: Highest offer price - `product_count` integer, required: Product appearances with a parseable price - `trend` object[], required: Daily product appearances, own versus competitor - `date` string, date, required - `total_products` integer, required - `own_products` integer, required - `competitor_products` integer, required - `total_responses` integer, required: Shopping answers that day - `responses_with_own` integer, required: Shopping answers that day with a brand product ## Other responses - `400`: Bad request - Invalid parameters - `401`: Unauthorized - Invalid or missing API key - `403`: Forbidden - You don't have access to this website, a competitor id belongs to another website, or the organization is on the Free plan - `404`: Website not found - `500`: Internal server error ## Changes - **2026-11-03** `2d1d86d5e067`: 1 info - endpoint added [Operation history](https://skmtc.dev/athenahq/apis/athenahq-api/changes/api/v1/metrics/shopping/post.md) --- [API](https://skmtc.dev/athenahq/apis/athenahq-api.md) - [All operations](https://skmtc.dev/athenahq/apis/athenahq-api/llms.txt) - [OpenAPI document](https://skmtc.dev/athenahq/apis/athenahq-api/revisions/6cf9ca58edf6?raw)