> ## Documentation Index
> Fetch the complete documentation index at: https://docs.peec.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# List Shopping Demand

> List top shopping queries, web-search fan-out queries, or query terms over a date range.



## OpenAPI

````yaml https://api.peec.ai/customer/v1/openapi/json post /products/demand
openapi: 3.0.3
info:
  title: Peec AI Customer API
  description: Development documentation
  version: 1.0.0
  contact:
    name: Peec AI Team
    email: support@peec.ai
servers:
  - url: https://api.peec.ai/customer/v1
security: []
paths:
  /products/demand:
    post:
      tags:
        - Products
      summary: List Shopping Demand
      description: >-
        List top shopping queries, web-search fan-out queries, or query terms
        over a date range.
      operationId: postProductsDemand
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                project_id:
                  description: Required if using a company api key
                  example: or_f45b94ba-5e35-4982-93ed-285e72ee14eb
                  type: string
                start_date:
                  default: '2026-01-01'
                  description: >-
                    full-date notation as defined by RFC 3339, section 5.6, for
                    example, 2017-07-21
                  example: '2025-09-22'
                  type: string
                  format: date
                  pattern: >-
                    ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))$
                end_date:
                  default: '2026-01-01'
                  description: >-
                    full-date notation as defined by RFC 3339, section 5.6, for
                    example, 2017-07-21
                  example: '2025-09-22'
                  type: string
                  format: date
                  pattern: >-
                    ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))$
                category_ids:
                  description: >-
                    Filter by shopping categories. Parent categories include
                    descendants.
                  type: array
                  items:
                    type: string
                    format: uuid
                    pattern: >-
                      ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
                country_codes:
                  type: array
                  items:
                    type: string
                model_channel_ids:
                  type: array
                  items:
                    type: string
                    enum:
                      - openai-0
                      - openai-1
                      - qwen-0
                      - openai-2
                      - perplexity-0
                      - perplexity-1
                      - google-0
                      - google-1
                      - google-2
                      - google-3
                      - anthropic-0
                      - anthropic-1
                      - deepseek-0
                      - meta-0
                      - xai-0
                      - xai-1
                      - microsoft-0
                      - amazon-0
                topic_ids:
                  type: array
                  items:
                    type: string
                tag_ids:
                  type: array
                  items:
                    type: string
                tag_operator:
                  type: string
                  enum:
                    - and
                    - or
                previous_start_date:
                  description: >-
                    Start of an explicit comparison window for deltas. Provide
                    together with previous_end_date, or omit both to auto-derive
                    an equal-length window immediately before [start_date,
                    end_date].
                  type: string
                  format: date
                  pattern: >-
                    ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))$
                previous_end_date:
                  description: >-
                    End of the explicit comparison window. Provide together with
                    previous_start_date, or omit both to auto-derive.
                  type: string
                  format: date
                  pattern: >-
                    ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))$
                kind:
                  type: string
                  enum:
                    - shopping_query
                    - fanout_query
                    - query_term
                  description: >-
                    shopping_query = product fan-out queries; fanout_query =
                    web-search fan-out queries; query_term = n-grams across
                    shopping queries.
                mode:
                  default: top
                  description: >-
                    top = highest now; trending = gainers; losing = losers; new
                    = appeared this window only.
                  type: string
                  enum:
                    - top
                    - trending
                    - losing
                    - new
                limit:
                  default: 50
                  type: integer
                  minimum: 1
                  maximum: 1000
                'n':
                  default: 2
                  description: n-gram width for kind=query_term (default 2 = bigrams).
                  type: integer
                  minimum: 1
                  maximum: 3
              required:
                - kind
          application/x-www-form-urlencoded:
            schema:
              type: object
              properties:
                project_id:
                  description: Required if using a company api key
                  example: or_f45b94ba-5e35-4982-93ed-285e72ee14eb
                  type: string
                start_date:
                  default: '2026-01-01'
                  description: >-
                    full-date notation as defined by RFC 3339, section 5.6, for
                    example, 2017-07-21
                  example: '2025-09-22'
                  type: string
                  format: date
                  pattern: >-
                    ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))$
                end_date:
                  default: '2026-01-01'
                  description: >-
                    full-date notation as defined by RFC 3339, section 5.6, for
                    example, 2017-07-21
                  example: '2025-09-22'
                  type: string
                  format: date
                  pattern: >-
                    ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))$
                category_ids:
                  description: >-
                    Filter by shopping categories. Parent categories include
                    descendants.
                  type: array
                  items:
                    type: string
                    format: uuid
                    pattern: >-
                      ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
                country_codes:
                  type: array
                  items:
                    type: string
                model_channel_ids:
                  type: array
                  items:
                    type: string
                    enum:
                      - openai-0
                      - openai-1
                      - qwen-0
                      - openai-2
                      - perplexity-0
                      - perplexity-1
                      - google-0
                      - google-1
                      - google-2
                      - google-3
                      - anthropic-0
                      - anthropic-1
                      - deepseek-0
                      - meta-0
                      - xai-0
                      - xai-1
                      - microsoft-0
                      - amazon-0
                topic_ids:
                  type: array
                  items:
                    type: string
                tag_ids:
                  type: array
                  items:
                    type: string
                tag_operator:
                  type: string
                  enum:
                    - and
                    - or
                previous_start_date:
                  description: >-
                    Start of an explicit comparison window for deltas. Provide
                    together with previous_end_date, or omit both to auto-derive
                    an equal-length window immediately before [start_date,
                    end_date].
                  type: string
                  format: date
                  pattern: >-
                    ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))$
                previous_end_date:
                  description: >-
                    End of the explicit comparison window. Provide together with
                    previous_start_date, or omit both to auto-derive.
                  type: string
                  format: date
                  pattern: >-
                    ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))$
                kind:
                  type: string
                  enum:
                    - shopping_query
                    - fanout_query
                    - query_term
                  description: >-
                    shopping_query = product fan-out queries; fanout_query =
                    web-search fan-out queries; query_term = n-grams across
                    shopping queries.
                mode:
                  default: top
                  description: >-
                    top = highest now; trending = gainers; losing = losers; new
                    = appeared this window only.
                  type: string
                  enum:
                    - top
                    - trending
                    - losing
                    - new
                limit:
                  default: 50
                  type: integer
                  minimum: 1
                  maximum: 1000
                'n':
                  default: 2
                  description: n-gram width for kind=query_term (default 2 = bigrams).
                  type: integer
                  minimum: 1
                  maximum: 3
              required:
                - kind
          multipart/form-data:
            schema:
              type: object
              properties:
                project_id:
                  description: Required if using a company api key
                  example: or_f45b94ba-5e35-4982-93ed-285e72ee14eb
                  type: string
                start_date:
                  default: '2026-01-01'
                  description: >-
                    full-date notation as defined by RFC 3339, section 5.6, for
                    example, 2017-07-21
                  example: '2025-09-22'
                  type: string
                  format: date
                  pattern: >-
                    ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))$
                end_date:
                  default: '2026-01-01'
                  description: >-
                    full-date notation as defined by RFC 3339, section 5.6, for
                    example, 2017-07-21
                  example: '2025-09-22'
                  type: string
                  format: date
                  pattern: >-
                    ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))$
                category_ids:
                  description: >-
                    Filter by shopping categories. Parent categories include
                    descendants.
                  type: array
                  items:
                    type: string
                    format: uuid
                    pattern: >-
                      ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
                country_codes:
                  type: array
                  items:
                    type: string
                model_channel_ids:
                  type: array
                  items:
                    type: string
                    enum:
                      - openai-0
                      - openai-1
                      - qwen-0
                      - openai-2
                      - perplexity-0
                      - perplexity-1
                      - google-0
                      - google-1
                      - google-2
                      - google-3
                      - anthropic-0
                      - anthropic-1
                      - deepseek-0
                      - meta-0
                      - xai-0
                      - xai-1
                      - microsoft-0
                      - amazon-0
                topic_ids:
                  type: array
                  items:
                    type: string
                tag_ids:
                  type: array
                  items:
                    type: string
                tag_operator:
                  type: string
                  enum:
                    - and
                    - or
                previous_start_date:
                  description: >-
                    Start of an explicit comparison window for deltas. Provide
                    together with previous_end_date, or omit both to auto-derive
                    an equal-length window immediately before [start_date,
                    end_date].
                  type: string
                  format: date
                  pattern: >-
                    ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))$
                previous_end_date:
                  description: >-
                    End of the explicit comparison window. Provide together with
                    previous_start_date, or omit both to auto-derive.
                  type: string
                  format: date
                  pattern: >-
                    ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))$
                kind:
                  type: string
                  enum:
                    - shopping_query
                    - fanout_query
                    - query_term
                  description: >-
                    shopping_query = product fan-out queries; fanout_query =
                    web-search fan-out queries; query_term = n-grams across
                    shopping queries.
                mode:
                  default: top
                  description: >-
                    top = highest now; trending = gainers; losing = losers; new
                    = appeared this window only.
                  type: string
                  enum:
                    - top
                    - trending
                    - losing
                    - new
                limit:
                  default: 50
                  type: integer
                  minimum: 1
                  maximum: 1000
                'n':
                  default: 2
                  description: n-gram width for kind=query_term (default 2 = bigrams).
                  type: integer
                  minimum: 1
                  maximum: 3
              required:
                - kind
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      type: object
                      properties:
                        kind:
                          type: string
                          enum:
                            - shopping_query
                            - fanout_query
                            - query_term
                        text:
                          type: string
                        distinct_chat_count:
                          type: number
                        distinct_chat_count_previous:
                          type: number
                        delta:
                          nullable: true
                          type: number
                      required:
                        - kind
                        - text
                        - distinct_chat_count
                        - distinct_chat_count_previous
                        - delta
                  total_count:
                    type: number
                required:
                  - data
                  - total_count
                description: Success
      security:
        - APIKeyHeader: []
        - APIKeyQuery: []
        - BearerAuth: []
components:
  securitySchemes:
    APIKeyHeader:
      type: apiKey
      in: header
      name: X-API-Key
    APIKeyQuery:
      type: apiKey
      in: query
      name: api_key
    BearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT

````