---
title: "List Products"
method: POST
path: "/products/list"
tags: ["Products"]
---

# List Products

`POST /products/list`

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.

## Request body

- object
  - `project_id` string — Required if using a company api key
  - `start_date` string, date — full-date notation as defined by RFC 3339, section 5.6, for example, 2017-07-21
  - `end_date` string, date — full-date notation as defined by RFC 3339, section 5.6, for example, 2017-07-21
  - `product_ids` string[] — Filter to these product ids.
  - `brand_ids` string[] — Filter to products of these brands (global_brand_id).
  - `category_ids` string[] — 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_ids` string[] — Filter to products sold through these merchants.
  - `country_codes` string[]
  - `model_channel_ids` string[]
  - `topic_ids` string[]
  - `tag_ids` string[]
  - `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'
  - `search` string
  - `order_by` 'visibility' | 'win_rate' | 'avg_position' | 'avg_rating' | 'mention_count' | 'name'
  - `direction` 'asc' | 'desc'
  - `limit` number
  - `offset` number

## Response `200`

Products with headline metrics over the date range

- object — Products with headline metrics over the date range
  - `data` object[], required
    - `id` string, required
    - `name` string, required
    - `brand` string, required
    - `source` 'CATALOG' | 'LLM', required
    - `image_url` string, nullable, required
    - `price_range` object, required
    - `categories` string[], required
    - `mention_count` number, required
    - `win_count` number, required
    - `avg_position` number, nullable, required
    - `avg_rating` number, nullable, required
    - `visibility` number, required
    - `share_of_voice` number, required
  - `total_count` number, required

---

[API](https://skmtc.dev/peec/apis/peec-ai-customer-api.md) · [All operations](https://skmtc.dev/peec/apis/peec-ai-customer-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/peec/peec-ai-customer-api/revisions/92840a1bffa7/schema)