> ## Documentation Index
> Fetch the complete documentation index at: https://docs.tryprofound.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Products
This report shows product visibility in ChatGPT shopping results. It can also
give the merchant offers for each product. The report returns each product as
`{ name, brand }` with its metrics as named fields.
* **Metrics:** `visibility_score`; `average_position` (a **lower** number is **better**); `visibility_rank`; the position-frequency metrics `position1_percentage`, `position2_percentage`, `position3_percentage`, `position_above3_percentage`; `product_rating`; `product_num_reviews`.
* **Position-frequency metrics:** Each one is the share of the product's appearances at that slot (`position1` = top; `position_above3` = below rank 3). The values are **0–1 fractions**, not 0–100. The four values sum to about 1.
* **`group_by`:** `date`, `topic`, or `prompt`.
* **Filter fields:** `topic`, `region`, `persona`, `prompt`, `tag`, `brand`, `merchant`.
### Merchant offers
To attach the merchant offers to each product, set `include_merchants: true`.
The report then adds `merchants` (a list of `{ name, price }`), `product_url`,
and `product_image_urls`. This mode does not accept `group_by` or
`target_product`. The position-frequency metrics are not available in this mode.
### Competitor mode
To return one product and its top competitors, set `target_product` to a
product name. To set the number of competitors, use `competitor_limit` (the
default is 5). Competitor mode is available in the item view only. Do not use it
with `include_merchants`.
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](/rest-api/reports/reports-v2-overview).
`POST /v2/reports/shopping/products/stream` uses the **same request body**.
It returns [Server-Sent Events](https://developer.mozilla.org/docs/Web/API/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).
```bash cURL theme={null}
curl -X POST https://api.tryprofound.com/v2/reports/shopping/products \
-H "X-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",
"include_merchants": true,
"metrics": ["visibility_score", "product_rating", "product_num_reviews"],
"limit": 10
}'
```
```json 200 theme={null}
{
"info": {
"total_results": 128,
"count": 10,
"next_cursor": "eyJvZmZzZXQiOjEwfQ==",
"models": ["ChatGPT"],
"include_merchants": true,
"metrics": ["visibility_score", "product_rating", "product_num_reviews"],
"start_date": "2026-06-01",
"end_date": "2026-06-30",
"filter": null
},
"data": [
{
"product": { "name": "Example Running Shoe", "brand": "Example Brand" },
"merchants": [
{ "name": "Example Retailer", "price": "$120.00" },
{ "name": "Example Brand", "price": "$110.00" }
],
"product_url": "https://www.example.com/p/example-running-shoe",
"product_image_urls": ["https://images.example.com/products/example-running-shoe.jpg"],
"product_rating": 4.5,
"product_num_reviews": 1200,
"visibility_score": 0.30
}
]
}
```
## OpenAPI
````yaml POST /v2/reports/shopping/products
openapi: 3.1.0
info:
title: External API
version: 8a280fe080bc62612cfa4d9ac5672343e0a2f720
servers:
- url: https://api.tryprofound.com
description: Production Server
security: []
paths:
/v2/reports/shopping/products:
post:
tags:
- Reports
- Reports
summary: Query Shopping Products V2
operationId: query_shopping_products_v2_v2_reports_shopping_products_post
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/ShoppingProductsV2Query'
required: true
responses:
'200':
description: Successful Response
content:
application/json:
schema:
$ref: '#/components/schemas/ShoppingProductsV2Response'
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
security:
- APIKeyHeader: []
- BearerAuth: []
x-codeSamples:
- lang: JavaScript
source: |-
import Profound from '@profoundai/client';
const client = new Profound({
apiKey: process.env['PROFOUND_API_KEY'], // This is the default and can be omitted
});
const response = await client.reports.shopping.products({
category_id: '182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e',
end_date: 'end_date',
start_date: 'start_date',
});
console.log(response.data);
- lang: Python
source: |-
import os
from profound import Profound
client = Profound(
api_key=os.environ.get("PROFOUND_API_KEY"), # This is the default and can be omitted
)
response = client.reports.shopping.products(
category_id="182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e",
end_date="end_date",
start_date="start_date",
)
print(response.data)
components:
schemas:
ShoppingProductsV2Query:
properties:
category_id:
type: string
format: uuid
title: Category Id
start_date:
type: string
title: Start Date
description: YYYY-MM-DD, ET, inclusive
end_date:
type: string
title: End Date
description: YYYY-MM-DD, ET, inclusive
group_by:
items:
type: string
enum:
- date
- topic
- prompt
type: array
title: Group By
metrics:
anyOf:
- items:
type: string
enum:
- visibility_score
- average_position
- visibility_rank
- position1_percentage
- position2_percentage
- position3_percentage
- position_above3_percentage
- product_rating
- product_num_reviews
type: array
- type: 'null'
title: Metrics
interval:
type: string
enum:
- day
- week
- month
title: Interval
default: day
include_merchants:
type: boolean
title: Include Merchants
description: Include per-product merchant offers (names, prices, urls, images).
default: false
target_product:
anyOf:
- type: string
minLength: 1
- type: 'null'
title: Target Product
description: Return this product plus its top competitors (item view only).
competitor_limit:
type: integer
minimum: 1
title: Competitor Limit
description: Competitors returned when `target_product` is set.
default: 5
filter:
anyOf:
- $ref: '#/components/schemas/FilterNode'
- type: 'null'
limit:
anyOf:
- type: integer
maximum: 50
exclusiveMinimum: 0
- type: 'null'
title: Limit
description: Page size; default 10, max 50.
max_results:
anyOf:
- type: integer
maximum: 50000
exclusiveMinimum: 0
- type: 'null'
title: Max Results
description: 'Stream endpoint only: cap streamed rows.'
cursor:
anyOf:
- type: string
- type: 'null'
title: Cursor
additionalProperties: false
type: object
required:
- category_id
- start_date
- end_date
title: ShoppingProductsV2Query
ShoppingProductsV2Response:
properties:
info:
$ref: '#/components/schemas/ShoppingProductsV2Info'
data:
items:
$ref: '#/components/schemas/ShoppingProductRow'
type: array
title: Data
type: object
required:
- info
- data
title: ShoppingProductsV2Response
HTTPValidationError:
properties:
detail:
items:
$ref: '#/components/schemas/ValidationError'
type: array
title: Detail
type: object
title: HTTPValidationError
FilterNode:
properties:
and:
anyOf:
- items:
$ref: '#/components/schemas/FilterNode'
type: array
- type: 'null'
title: And
or:
anyOf:
- items:
$ref: '#/components/schemas/FilterNode'
type: array
- type: 'null'
title: Or
not:
anyOf:
- $ref: '#/components/schemas/FilterNode'
- type: 'null'
field:
anyOf:
- type: string
- type: 'null'
title: Field
op:
anyOf:
- type: string
- type: 'null'
title: Op
value:
title: Value
additionalProperties: false
type: object
title: FilterNode
description: A leaf (`field`/`op`/`value`) or an `and`/`or`/`not` group.
ShoppingProductsV2Info:
properties:
total_results:
anyOf:
- type: integer
- type: 'null'
title: Total Results
description: Total products matching the query before pagination.
count:
type: integer
title: Count
description: >-
Number of products on this page. When grouped by
`date`/`topic`/`prompt`, `data` holds one row per product x bucket,
so `len(data)` can exceed `count`.
next_cursor:
anyOf:
- type: string
- type: 'null'
title: Next Cursor
description: Opaque cursor for the next page; null on the last page.
models:
items:
type: string
type: array
title: Models
description: Display names of the models the report covers.
start_date:
type: string
title: Start Date
description: Echoed request start date (YYYY-MM-DD, ET).
end_date:
type: string
title: End Date
description: Echoed request end date (YYYY-MM-DD, ET).
filter:
anyOf:
- additionalProperties: true
type: object
- type: 'null'
title: Filter
description: Echoed normalized filter tree, or null when no filter was sent.
include_merchants:
type: boolean
title: Include Merchants
description: Whether merchant offers are included in each row.
metrics:
items:
type: string
type: array
title: Metrics
description: Metrics returned per row.
additionalProperties: true
type: object
required:
- count
- models
- start_date
- end_date
- include_merchants
- metrics
title: ShoppingProductsV2Info
ShoppingProductRow:
properties:
product:
anyOf:
- additionalProperties: true
type: object
- type: 'null'
title: Product
date:
anyOf:
- type: string
- type: 'null'
title: Date
topic:
anyOf:
- $ref: '#/components/schemas/DimensionRef'
- type: 'null'
prompt:
anyOf:
- $ref: '#/components/schemas/DimensionRef'
- type: 'null'
visibility_score:
anyOf:
- type: number
- type: 'null'
title: Visibility Score
average_position:
anyOf:
- type: number
- type: 'null'
title: Average Position
visibility_rank:
anyOf:
- type: integer
- type: 'null'
title: Visibility Rank
position1_percentage:
anyOf:
- type: number
- type: 'null'
title: Position1 Percentage
position2_percentage:
anyOf:
- type: number
- type: 'null'
title: Position2 Percentage
position3_percentage:
anyOf:
- type: number
- type: 'null'
title: Position3 Percentage
position_above3_percentage:
anyOf:
- type: number
- type: 'null'
title: Position Above3 Percentage
product_rating:
anyOf:
- type: number
- type: 'null'
title: Product Rating
product_num_reviews:
anyOf:
- type: integer
- type: 'null'
title: Product Num Reviews
product_url:
anyOf:
- type: string
- type: 'null'
title: Product Url
product_image_urls:
anyOf:
- items:
type: string
type: array
- type: 'null'
title: Product Image Urls
merchants:
anyOf:
- items:
additionalProperties: true
type: object
type: array
- type: 'null'
title: Merchants
description: >-
Per-product merchant offers `{name, price}` (only with
`include_merchants`).
additionalProperties: true
type: object
title: ShoppingProductRow
description: >-
One product row. Merchant fields present only when `include_merchants`
is true.
ValidationError:
properties:
loc:
items:
anyOf:
- type: string
- type: integer
type: array
title: Location
msg:
type: string
title: Message
type:
type: string
title: Error Type
input:
title: Input
ctx:
type: object
title: Context
type: object
required:
- loc
- msg
- type
title: ValidationError
DimensionRef:
properties:
id:
anyOf:
- type: string
- type: 'null'
title: Id
name:
anyOf:
- type: string
- type: 'null'
title: Name
type: object
title: DimensionRef
description: An ``{id, name}`` reference for a grouped dimension value.
securitySchemes:
APIKeyHeader:
type: apiKey
in: header
name: X-API-Key
BearerAuth:
type: http
scheme: bearer
````