Products

List Products

Changed on Nov 3, 2026

List a project's products with headline metrics (mention_count, win_count, avg_position, avg_rating, visibility, share_of_voice) over the date range, filterable by category, merchant, brand, country, model channel, topic, and tag. Paginated.

post/products/list

Request

Base URL
https://api.peec.ai/customer/v1
URL
https://api.peec.ai/customer/v1/products/list
Auth
- API key in header X-API-Key
- or API key in query parameter api_key
- or HTTP bearer

Request body

project_idstring

Required if using a company api key

start_datestring date

full-date notation as defined by RFC 3339, section 5.6, for example, 2017-07-21

end_datestring date

full-date notation as defined by RFC 3339, section 5.6, for example, 2017-07-21

product_idsstring[]

Filter to these product ids.

brand_idsstring[]

Filter to products of these brands (global_brand_id).

category_idsstring[]

Filter to products in any of these categories (OR — a product matches if it falls under at least one). Category ids roll up: selecting a parent also matches products in its descendant categories.

merchant_idsstring[]

Filter to products sold through these merchants.

country_codesstring[]

model_channel_idsstring[]

topic_idsstring[]

tag_idsstring[]

tag_operator'and' | 'or'

chat_scope'all' | 'shopping'

Which chats the visibility denominator counts: every in-scope chat ('all') or only product-gallery ('shopping') chats. Defaults to 'shopping'.

source'CATALOG' | 'LLM'

searchstring

direction'asc' | 'desc'

limitinteger

offsetinteger

Example request

{
  "project_id": "or_f45b94ba-5e35-4982-93ed-285e72ee14eb",
  "start_date": "2025-09-22",
  "end_date": "2025-09-22"
}

Response

Products with headline metrics over the date range

total_countnumber required

Changes

Nov 3, 20269d774600c8eb Revision changes
- info
  added the new exa-0 enum value to the request property / (media type: application/json)
- info
  added the new exa-0 enum value to the request property / (media type: application/x-www-form-urlencoded)
- info
  added the new exa-0 enum value to the request property / (media type: multipart/form-data)
Nov 3, 20269fdffdff48a5 Revision changes
- breaking
  the request property type changed from number to integer (media type: application/json)
- breaking
  the request property type changed from number to integer (media type: application/x-www-form-urlencoded)
- breaking
  the request property type changed from number to integer (media type: multipart/form-data)
- breaking
  the request property type changed from number to integer (media type: application/json)
- breaking
  the request property type changed from number to integer (media type: application/x-www-form-urlencoded)
- breaking
  the request property type changed from number to integer (media type: multipart/form-data)
- warning
  the request property's max was set to 9007199254740991.00 (media type: application/json)
- warning
  the request property's max was set to 9007199254740991.00 (media type: application/x-www-form-urlencoded)
- warning
  the request property's max was set to 9007199254740991.00 (media type: multipart/form-data)
- info
  added the new anthropic-2 enum value to the request property / (media type: application/json)
- info
  added the new anthropic-2 enum value to the request property / (media type: application/x-www-form-urlencoded)
- info
  added the new anthropic-2 enum value to the request property / (media type: multipart/form-data)
- info
  added the new anthropic-3 enum value to the request property / (media type: application/json)
- info
  added the new anthropic-3 enum value to the request property / (media type: application/x-www-form-urlencoded)
- info
  added the new anthropic-3 enum value to the request property / (media type: multipart/form-data)
- info
  added the new baidu-0 enum value to the request property / (media type: application/json)
- info
  added the new baidu-0 enum value to the request property / (media type: application/x-www-form-urlencoded)
- info
  added the new baidu-0 enum value to the request property / (media type: multipart/form-data)
- info
  added the new google-5 enum value to the request property / (media type: application/json)
- info
  added the new google-5 enum value to the request property / (media type: application/x-www-form-urlencoded)
- info
  added the new google-5 enum value to the request property / (media type: multipart/form-data)
- info
  added the new meta-1 enum value to the request property / (media type: application/json)
- info
  added the new meta-1 enum value to the request property / (media type: application/x-www-form-urlencoded)
- info
  added the new meta-1 enum value to the request property / (media type: multipart/form-data)
- info
  added the new meta-2 enum value to the request property / (media type: application/json)
- info
  added the new meta-2 enum value to the request property / (media type: application/x-www-form-urlencoded)
- info
  added the new meta-2 enum value to the request property / (media type: multipart/form-data)
- info
  added the new naver-0 enum value to the request property / (media type: application/json)
- info
  added the new naver-0 enum value to the request property / (media type: application/x-www-form-urlencoded)
- info
  added the new naver-0 enum value to the request property / (media type: multipart/form-data)
- info
  added the new openai-3 enum value to the request property / (media type: application/json)
- info
  added the new openai-3 enum value to the request property / (media type: application/x-www-form-urlencoded)
- info
  added the new openai-3 enum value to the request property / (media type: multipart/form-data)
- info
  added the new openai-4 enum value to the request property / (media type: application/json)
- info
  added the new openai-4 enum value to the request property / (media type: application/x-www-form-urlencoded)
- info
  added the new openai-4 enum value to the request property / (media type: multipart/form-data)
- info
  added the new openai-5 enum value to the request property / (media type: application/json)
- info
  added the new openai-5 enum value to the request property / (media type: application/x-www-form-urlencoded)
- info
  added the new openai-5 enum value to the request property / (media type: multipart/form-data)

Operation history