curl -X POST https://api.tryprofound.com/v2/reports/shopping/merchants \
-H "X-API-Key: <your-api-key>" \
-H "Content-Type: application/json" \
-d '{
"category_id": "182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e",
"start_date": "2026-06-01",
"end_date": "2026-06-30",
"metrics": ["merchant_share", "merchant_share_rank", "merchant_visibility", "merchant_visibility_rank"],
"limit": 10
}'
{
"info": {
"total_results": 24,
"count": 10,
"next_cursor": "eyJvZmZzZXQiOjEwfQ==",
"view": "distribution",
"models": ["ChatGPT"],
"metrics": ["merchant_share", "merchant_share_rank", "merchant_visibility", "merchant_visibility_rank"],
"start_date": "2026-06-01",
"end_date": "2026-06-30",
"filter": null
},
"data": [
{
"merchant_name": "Example Retailer",
"merchant_share": 0.25,
"merchant_share_rank": 1,
"merchant_visibility": 0.40,
"merchant_visibility_rank": 1
}
]
}
Shopping
Merchants
POST
/
v2
/
reports
/
shopping
/
merchants
curl -X POST https://api.tryprofound.com/v2/reports/shopping/merchants \
-H "X-API-Key: <your-api-key>" \
-H "Content-Type: application/json" \
-d '{
"category_id": "182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e",
"start_date": "2026-06-01",
"end_date": "2026-06-30",
"metrics": ["merchant_share", "merchant_share_rank", "merchant_visibility", "merchant_visibility_rank"],
"limit": 10
}'
{
"info": {
"total_results": 24,
"count": 10,
"next_cursor": "eyJvZmZzZXQiOjEwfQ==",
"view": "distribution",
"models": ["ChatGPT"],
"metrics": ["merchant_share", "merchant_share_rank", "merchant_visibility", "merchant_visibility_rank"],
"start_date": "2026-06-01",
"end_date": "2026-06-30",
"filter": null
},
"data": [
{
"merchant_name": "Example Retailer",
"merchant_share": 0.25,
"merchant_share_rank": 1,
"merchant_visibility": 0.40,
"merchant_visibility_rank": 1
}
]
}
This report gives merchant data for ChatGPT shopping results.
group_by
selects one of three views. merchant_share is the merchant’s share of offers.
merchant_visibility is the merchant’s share of the runs it appears in. These
are two different measures.
Views
- Distribution (omit
group_by) — one row for each merchant. Metrics:merchant_share,merchant_share_rank,merchant_visibility,merchant_visibility_rank. To get a time series, adddate. - Brand share (
group_by: ["brand"]) — one row for each merchant and brand. Metrics:merchant_share,brand_share(the brand’s share in the merchant),visibility_rank. - Top products (
group_by: ["product"]) — one row for each merchant and product. Metrics:merchant_visibility,product_visibility,product_rank.
topic, region, persona, prompt, tag. The
distribution view also accepts a brand filter.
Rules
- Use the metrics that are valid for the view. Other metrics return
422. - Group by
brandorproduct. Do not use both. dateis available in the distribution view only.group_by: ["brand", "date"]or["product", "date"]returns422.- The
brandfilter is available in the distribution view only.
In the distribution view,
merchant_visibility and merchant_visibility_rank
are run-appearance metrics. The report gets them from a second query and adds
them to each merchant. Request them only when you need them.Shopping data comes from ChatGPT only. No shopping report has a
model
group_by or a model filter.The v2 reports share one request shape. For the filter tree, grouping, and
pagination, see Filtering & concepts.
Streaming (SSE) variant (same body, /stream)
Streaming (SSE) variant (same body, /stream)
POST /v2/reports/shopping/merchants/stream uses the same request body.
It returns Server-Sent Events:
one summary event (the info block), then one result event for each row.
The stream rejects limit and cursor. It returns all rows by default. To
set a maximum, use max_results (maximum 50000).curl -X POST https://api.tryprofound.com/v2/reports/shopping/merchants \
-H "X-API-Key: <your-api-key>" \
-H "Content-Type: application/json" \
-d '{
"category_id": "182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e",
"start_date": "2026-06-01",
"end_date": "2026-06-30",
"metrics": ["merchant_share", "merchant_share_rank", "merchant_visibility", "merchant_visibility_rank"],
"limit": 10
}'
{
"info": {
"total_results": 24,
"count": 10,
"next_cursor": "eyJvZmZzZXQiOjEwfQ==",
"view": "distribution",
"models": ["ChatGPT"],
"metrics": ["merchant_share", "merchant_share_rank", "merchant_visibility", "merchant_visibility_rank"],
"start_date": "2026-06-01",
"end_date": "2026-06-30",
"filter": null
},
"data": [
{
"merchant_name": "Example Retailer",
"merchant_share": 0.25,
"merchant_share_rank": 1,
"merchant_visibility": 0.40,
"merchant_visibility_rank": 1
}
]
}
Authorizations
APIKeyHeaderBearerAuth
Body
application/json
YYYY-MM-DD, ET, inclusive
YYYY-MM-DD, ET, inclusive
[] = distribution; [brand] = brand share within each merchant; [product] = top products per merchant. date (distribution only) adds a time series.
Available options:
date, brand, product Defaults to the chosen view's metrics; must be valid for that view.
Available options:
merchant_share, merchant_share_rank, merchant_visibility, merchant_visibility_rank, visibility_rank, brand_share, product_visibility, product_rank Available options:
day, week, month A leaf (field/op/value) or an and/or/not group.
Show child attributes
Show child attributes
Page size; default 10, max 50.
Required range:
0 < x <= 50Stream endpoint only: cap streamed rows.
Required range:
0 < x <= 50000Was this page helpful?