Skip to main content
POST
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, add date.
  • 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.
Filter fields: 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 brand or product. Do not use both.
  • date is available in the distribution view only. group_by: ["brand", "date"] or ["product", "date"] returns 422.
  • The brand filter 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.
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).

Authorizations

​
X-API-Key
string
header
required

Body

application/json
​
category_id
string<uuid>
required
​
start_date
string
required

YYYY-MM-DD, ET, inclusive

​
end_date
string
required

YYYY-MM-DD, ET, inclusive

​
group_by
enum<string>[]

[] = distribution; [brand] = brand share within each merchant; [product] = top products per merchant. date (distribution only) adds a time series.

Available options:
date,
brand,
product
​
metrics
enum<string>[] | null

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
​
interval
enum<string>
default:day
Available options:
day,
week,
month
​
filter
FilterNode · object | null

A leaf (field/op/value) or an and/or/not group.

​
limit
integer | null

Page size; default 10, max 50.

Required range: 0 < x <= 50
​
max_results
integer | null

Stream endpoint only: cap streamed rows.

Required range: 0 < x <= 50000
​
cursor
string | null

Response

Successful Response

​
info
ShoppingMerchantsV2Info · object
required
​
data
ShoppingMerchantRow · object[]
required