> ## 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. # Shopping Metrics > 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. Only ChatGPT and AI Mode answer with product carousels, so `models` accepts those two ids. Requires a paid plan. ## OpenAPI ````yaml /api-reference/openapi.json post /api/v1/metrics/shopping openapi: 3.1.0 info: title: AthenaHQ API description: >- AthenaHQ API provides programmatic access to manage your websites and prompts for AI-powered content optimization. version: 1.0.0 contact: email: support@athenahq.ai servers: - url: https://api.athenahq.ai description: Production server security: - apiKey: [] tags: - name: Basics description: Core API operations for managing websites and prompts - name: Metrics description: Metrics and analytics endpoints for tracking AI visibility - name: Billing description: Billing and credits endpoints for managing usage - name: Team Management description: Endpoints for managing team members and invitations - name: Groups description: Endpoints for managing groups of websites - name: Content description: >- Endpoints for accessing Content Hub data — tabs, tracked URLs, and per-URL prompt breakdowns. - name: Pitch Workspace description: >- Endpoints for accessing pitch workspace reports — org-scoped pitch runs with competitors, prompts, attributes, and aggregate metrics. - name: Knowledge Base description: >- Endpoints for reading the brand Knowledge Base — approved brand facts and the pillars that organize them. paths: /api/v1/metrics/shopping: post: tags: - Metrics summary: Shopping Metrics description: >- 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. Only ChatGPT and AI Mode answer with product carousels, so `models` accepts those two ids. Requires a paid plan. operationId: getShoppingMetrics requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/ShoppingMetricsRequest' responses: '200': description: Successful response with shopping metrics 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: Bad request - Invalid parameters 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: Unauthorized - Invalid or missing API key content: application/json: schema: $ref: '#/components/schemas/Error' '403': description: >- Forbidden - You don't have access to this website, a competitor id belongs to another website, or the organization is on the Free plan 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: Website not found content: application/json: schema: $ref: '#/components/schemas/Error' example: error: Website not found '500': description: Internal server error content: application/json: schema: $ref: '#/components/schemas/Error' security: - apiKey: [] components: schemas: ShoppingMetricsRequest: type: object description: Request body for the shopping metrics endpoint required: - website_id - filters properties: website_id: type: string format: uuid description: The ID of the website to query shopping metrics for example: 123e4567-e89b-12d3-a456-426614174000 filters: $ref: '#/components/schemas/ShoppingMetricsFilters' top_products_limit: type: integer minimum: 1 maximum: 50 default: 10 description: >- How many products to return in each of top_own_products and 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: >- The Shopping Insights dashboard blocks. Rates are percentages 0-100; positions are 1-based (lower is better). required: - summary - offer_summary - top_own_products - top_competitor_products - competitor_breakdown - merchant_breakdown - position_distribution - price_comparison - trend properties: summary: type: object description: Headline counts across every shopping answer in the range 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: Responses that included a product carousel example: 50 responses_with_own_products: type: integer description: >- Shopping answers that included at least one of the brand's products example: 20 appearance_rate: type: number description: >- responses_with_own_products / total_shopping_responses as a percentage 0-100 example: 40 total_products: type: integer description: Product appearances across all shopping answers example: 150 own_products: type: integer description: Appearances of the brand's own products example: 40 competitor_products: type: integer description: Appearances attributed to tracked competitors example: 110 avg_own_position: type: - number - 'null' description: Average carousel position of the brand's products example: 2.5 avg_competitor_position: type: - number - 'null' description: Average carousel position of competitor products example: 4.2 offer_summary: type: object description: Retail offers (price listings) attached to the products in the range required: - total_offers - products_with_offers - competitor_offers - currency - avg_price properties: total_offers: type: integer description: Offers attached to the brand's products example: 200 products_with_offers: type: integer description: Brand product appearances that carried at least one offer example: 80 competitor_offers: type: integer description: Offers attached to competitor products example: 60 currency: type: string description: Currency of avg_price (the most common offer currency) example: USD avg_price: type: - number - 'null' description: Average offer price of the brand's products example: 149.99 top_own_products: type: array description: The brand's most frequently shown products, most appearances first items: $ref: '#/components/schemas/ShoppingProduct' top_competitor_products: type: array description: Competitor products shown most often, most appearances first items: $ref: '#/components/schemas/ShoppingCompetitorProduct' competitor_breakdown: type: array description: >- Competitor leaderboard: which tracked competitors show up most in shopping answers 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: Competitor name example: Rival Runners product_count: type: integer description: Product appearances attributed to the competitor example: 30 avg_position: type: - number - 'null' description: >- Average carousel position of the competitor's products; null when no appearance carried a position example: 3.5 avg_rating: type: - number - 'null' description: Average rating shown for the competitor's products example: 4.2 response_count: type: integer description: Shopping answers the competitor appeared in example: 15 merchant_breakdown: type: array description: >- Retailer breakdown: where products are stocked in AI answers, own versus competitor 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: Brand product appearances listed from this retailer example: 15 competitor_count: type: integer description: Competitor product appearances listed from this retailer example: 35 own_avg_position: type: - number - 'null' description: Average position of the brand's products from this retailer example: 2.8 competitor_avg_position: type: - number - 'null' description: Average position of competitor products from this retailer example: 3.6 own_response_count: type: integer description: Shopping answers with a brand product from this retailer example: 12 competitor_response_count: type: integer description: Shopping answers with a competitor product from this retailer example: 22 position_distribution: type: array description: 'Rank distribution: who occupies each carousel position' items: type: object required: - position - count - own_count - competitor_count properties: position: type: integer description: 1-based carousel position example: 1 count: type: integer description: Product appearances at this position example: 40 own_count: type: integer description: Brand product appearances at this position example: 12 competitor_count: type: integer description: Competitor product appearances at this position example: 28 price_comparison: type: array description: >- Offer price range for the brand's products versus competitors, per currency 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: Average offer price example: 149.99 min_price: type: - number - 'null' description: Lowest offer price example: 89 max_price: type: - number - 'null' description: Highest offer price example: 219 product_count: type: integer description: Product appearances with a parseable price example: 80 trend: type: array description: Daily product appearances, own versus competitor 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: Shopping answers that day example: 4 responses_with_own: type: integer description: Shopping answers that day with a brand product example: 2 Error: type: object description: Error response object required: - error properties: error: type: string description: Error message describing what went wrong example: Unauthorized ShoppingMetricsFilters: type: object description: >- Filters for the shopping metrics endpoint. Only the filters the Shopping Insights page applies are accepted; any other filter key is rejected with 400. required: - start_date properties: start_date: type: string format: date description: Start of the date range, YYYY-MM-DD (UTC), inclusive example: '2026-08-01' end_date: type: string format: date description: >- End of the date range, YYYY-MM-DD (UTC), inclusive. Defaults to today. Must be on or after start_date. example: '2026-08-31' schedule_id: $ref: '#/components/schemas/PromptScheduleSelection' models: type: array description: Shopping-capable models to include. Omit for both. items: type: string enum: - chatgpt - ai_mode example: - chatgpt competitor_ids: type: array description: >- Competitor UUIDs to keep in the competitor blocks. Own products are always included. Omit for all competitors. items: type: string format: uuid prompt_tags: type: array description: >- Prompt tag IDs to filter prompts by (list tags with GET /api/v1/prompt-tags). Omit for all tags. items: type: string format: uuid prompt_tags_operator: type: string enum: - is_any_of - has_all_of description: >- 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: type: array description: >- Target identifier strings to filter responses to. The literal string no-identifier selects responses with no target identifier. Omit for all. items: type: string ShoppingProduct: type: object required: - title - merchant - appearances - avg_position - avg_rating - image_url - product_url properties: title: type: string description: Product title as shown in the shopping answer example: Acme Trail Runner 3 merchant: type: - string - 'null' description: Retailer the product was listed from, when the answer named one example: Amazon appearances: type: integer description: Number of shopping answers the product appeared in example: 25 avg_position: type: - number - 'null' description: >- Average 1-based position in the carousel (lower is better); null when no appearance carried a position example: 1.5 avg_rating: type: - number - 'null' description: Average rating shown for the product, when any example: 4.5 image_url: type: - string - 'null' description: Product image URL from the answer example: https://example.com/trail-runner.jpg product_url: type: - string - 'null' description: Product page URL from the answer 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: Product title as shown in the shopping answer example: Acme Trail Runner 3 merchant: type: - string - 'null' description: Retailer the product was listed from, when the answer named one example: Amazon appearances: type: integer description: Number of shopping answers the product appeared in example: 25 avg_position: type: - number - 'null' description: >- Average 1-based position in the carousel (lower is better); null when no appearance carried a position example: 1.5 avg_rating: type: - number - 'null' description: Average rating shown for the product, when any example: 4.5 image_url: type: - string - 'null' description: Product image URL from the answer example: https://example.com/trail-runner.jpg product_url: type: - string - 'null' description: Product page URL from the answer example: https://example.com/products/trail-runner-3 competitor_id: type: - string - 'null' description: Competitor the product was attributed to example: 123e4567-e89b-12d3-a456-426614174222 PromptScheduleSelection: description: >- 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. No All schedules selection. default: default oneOf: - type: string enum: - default - manual - type: string format: uuid securitySchemes: apiKey: type: apiKey in: header name: x-api-key description: >- API key for authentication. You can create one [here](https://app.athenahq.ai/organization?tab=api). ````