ATathenahq
Metrics

Shopping Metrics

Changed on

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.

post/api/v1/metrics/shopping

Request

  • Base URL
    https://api.athenahq.ai
  • Auth
    API key in header x-api-key

Request body

website_idstring uuid required

The ID of the website to query shopping metrics for

top_products_limitinteger

How many products to return in each of top_own_products and top_competitor_products

Example request

{
  "website_id": "123e4567-e89b-12d3-a456-426614174000",
  "filters": {
    "start_date": "2026-08-01",
    "end_date": "2026-08-31",
    "models": [
      "chatgpt"
    ]
  },
  "top_products_limit": 10
}

Response

Successful response with shopping metrics

Example response

{
  "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": "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",
        "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
      }
    ],
    "price_comparison": [
      {
        "currency": "USD",
        "avg_price": 149.99,
        "min_price": 89,
        "max_price": 219,
        "product_count": 80
      }
    ],
    "trend": [
      {
        "date": "2026-08-01",
        "total_products": 5,
        "own_products": 2,
        "competitor_products": 3,
        "total_responses": 4,
        "responses_with_own": 2
      }
    ]
  }
}

Changes