Skip to main content
POST
This report shows brand visibility in ChatGPT shopping results. It gives how often each brand appears, its average position, and its rank. Select the brands with assets. Divide the results with group_by. Each metric is a named field on the row.
  • Metrics: visibility_score (the share of shopping results that include the brand); average_position (the average rank when the brand appears — a lower number is better); visibility_rank.
  • group_by: date, topic, region, or prompt.
  • Brand selection: Select the brands with the assets parameter. Give one name or a list. scope: "all" ranks all brands. scope: "owned" (the default) returns only your brands. An assets selection returns one page and ignores limit.
  • Filter fields: topic, region, persona, prompt, tag.
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/brands/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). Use the stream to get a large result in one request.

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>[]
Available options:
date,
topic,
region,
prompt
​
metrics
enum<string>[] | null
Available options:
visibility_score,
average_position,
visibility_rank
​
interval
enum<string>
default:day
Available options:
day,
week,
month
​
scope
enum<string>
default:owned
Available options:
owned,
all
​
assets

Restrict to these asset names (a name or list). Overrides scope.

​
filter
FilterNode · object | null

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

​
limit
integer | null

Page size for scope=all; default 10, max 50.

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

Stream endpoint only: cap the number of streamed rows (default: all).

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

Response

Successful Response

​
info
ShoppingBrandsV2Info · object
required
​
data
ShoppingBrandRow · object[]
required