Shopping Metrics
curl --request POST \
--url https://api.athenahq.ai/api/v1/metrics/shopping \
--header 'Content-Type: application/json' \
--header 'x-api-key: <api-key>' \
--data '
{
"website_id": "123e4567-e89b-12d3-a456-426614174000",
"filters": {
"start_date": "2026-08-01",
"end_date": "2026-08-31",
"models": [
"chatgpt"
]
},
"top_products_limit": 10
}
'import requests
url = "https://api.athenahq.ai/api/v1/metrics/shopping"
payload = {
"website_id": "123e4567-e89b-12d3-a456-426614174000",
"filters": {
"start_date": "2026-08-01",
"end_date": "2026-08-31",
"models": ["chatgpt"]
},
"top_products_limit": 10
}
headers = {
"x-api-key": "<api-key>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {'x-api-key': '<api-key>', 'Content-Type': 'application/json'},
body: JSON.stringify({
website_id: '123e4567-e89b-12d3-a456-426614174000',
filters: {start_date: '2026-08-01', end_date: '2026-08-31', models: ['chatgpt']},
top_products_limit: 10
})
};
fetch('https://api.athenahq.ai/api/v1/metrics/shopping', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://api.athenahq.ai/api/v1/metrics/shopping",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => json_encode([
'website_id' => '123e4567-e89b-12d3-a456-426614174000',
'filters' => [
'start_date' => '2026-08-01',
'end_date' => '2026-08-31',
'models' => [
'chatgpt'
]
],
'top_products_limit' => 10
]),
CURLOPT_HTTPHEADER => [
"Content-Type: application/json",
"x-api-key: <api-key>"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://api.athenahq.ai/api/v1/metrics/shopping"
payload := strings.NewReader("{\n \"website_id\": \"123e4567-e89b-12d3-a456-426614174000\",\n \"filters\": {\n \"start_date\": \"2026-08-01\",\n \"end_date\": \"2026-08-31\",\n \"models\": [\n \"chatgpt\"\n ]\n },\n \"top_products_limit\": 10\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("x-api-key", "<api-key>")
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.post("https://api.athenahq.ai/api/v1/metrics/shopping")
.header("x-api-key", "<api-key>")
.header("Content-Type", "application/json")
.body("{\n \"website_id\": \"123e4567-e89b-12d3-a456-426614174000\",\n \"filters\": {\n \"start_date\": \"2026-08-01\",\n \"end_date\": \"2026-08-31\",\n \"models\": [\n \"chatgpt\"\n ]\n },\n \"top_products_limit\": 10\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.athenahq.ai/api/v1/metrics/shopping")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["x-api-key"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"website_id\": \"123e4567-e89b-12d3-a456-426614174000\",\n \"filters\": {\n \"start_date\": \"2026-08-01\",\n \"end_date\": \"2026-08-31\",\n \"models\": [\n \"chatgpt\"\n ]\n },\n \"top_products_limit\": 10\n}"
response = http.request(request)
puts response.read_body{
"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
}
]
}
}Shopping
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.
POST
/
api
/
v1
/
metrics
/
shopping
Shopping Metrics
curl --request POST \
--url https://api.athenahq.ai/api/v1/metrics/shopping \
--header 'Content-Type: application/json' \
--header 'x-api-key: <api-key>' \
--data '
{
"website_id": "123e4567-e89b-12d3-a456-426614174000",
"filters": {
"start_date": "2026-08-01",
"end_date": "2026-08-31",
"models": [
"chatgpt"
]
},
"top_products_limit": 10
}
'import requests
url = "https://api.athenahq.ai/api/v1/metrics/shopping"
payload = {
"website_id": "123e4567-e89b-12d3-a456-426614174000",
"filters": {
"start_date": "2026-08-01",
"end_date": "2026-08-31",
"models": ["chatgpt"]
},
"top_products_limit": 10
}
headers = {
"x-api-key": "<api-key>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {'x-api-key': '<api-key>', 'Content-Type': 'application/json'},
body: JSON.stringify({
website_id: '123e4567-e89b-12d3-a456-426614174000',
filters: {start_date: '2026-08-01', end_date: '2026-08-31', models: ['chatgpt']},
top_products_limit: 10
})
};
fetch('https://api.athenahq.ai/api/v1/metrics/shopping', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://api.athenahq.ai/api/v1/metrics/shopping",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => json_encode([
'website_id' => '123e4567-e89b-12d3-a456-426614174000',
'filters' => [
'start_date' => '2026-08-01',
'end_date' => '2026-08-31',
'models' => [
'chatgpt'
]
],
'top_products_limit' => 10
]),
CURLOPT_HTTPHEADER => [
"Content-Type: application/json",
"x-api-key: <api-key>"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://api.athenahq.ai/api/v1/metrics/shopping"
payload := strings.NewReader("{\n \"website_id\": \"123e4567-e89b-12d3-a456-426614174000\",\n \"filters\": {\n \"start_date\": \"2026-08-01\",\n \"end_date\": \"2026-08-31\",\n \"models\": [\n \"chatgpt\"\n ]\n },\n \"top_products_limit\": 10\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("x-api-key", "<api-key>")
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.post("https://api.athenahq.ai/api/v1/metrics/shopping")
.header("x-api-key", "<api-key>")
.header("Content-Type", "application/json")
.body("{\n \"website_id\": \"123e4567-e89b-12d3-a456-426614174000\",\n \"filters\": {\n \"start_date\": \"2026-08-01\",\n \"end_date\": \"2026-08-31\",\n \"models\": [\n \"chatgpt\"\n ]\n },\n \"top_products_limit\": 10\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.athenahq.ai/api/v1/metrics/shopping")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["x-api-key"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"website_id\": \"123e4567-e89b-12d3-a456-426614174000\",\n \"filters\": {\n \"start_date\": \"2026-08-01\",\n \"end_date\": \"2026-08-31\",\n \"models\": [\n \"chatgpt\"\n ]\n },\n \"top_products_limit\": 10\n}"
response = http.request(request)
puts response.read_body{
"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
}
]
}
}Body
application/json
Request body for the shopping metrics endpoint
The ID of the website to query shopping metrics for
Example:
"123e4567-e89b-12d3-a456-426614174000"
Filters for the shopping metrics endpoint. Only the filters the Shopping Insights page applies are accepted; any other filter key is rejected with 400.
Show child attributes
Show child attributes
How many products to return in each of top_own_products and top_competitor_products
Required range:
1 <= x <= 50Response
Successful response with shopping metrics
The Shopping Insights dashboard blocks. Rates are percentages 0-100; positions are 1-based (lower is better).
Show child attributes
Show child attributes
Was this page helpful?