Skip to content
SarvexDocs
Esc
↑↓navigate↵open⌘Jpreview

Top products by agent request count

Top-N products (default 100) by summed agent request count over the range, with a per-surface breakdown. Counts only — reached_cart_count/completed_count are not represented (no telemetry correlates a specific catalog request to a specific later checkout; see this path group’s top-level description). Rows below the small-count suppression threshold (default 5) are omitted. Max range 92 days.

GET/insights/product_demand
Authorization
AuthorizationBearer token (JWT) · headerrequired

JWT issued by the external IdP via the OAuth 2.0 authorization-code flow (Kinde in production; a simulator in test). The client obtains it and sends it as a Bearer token on every authenticated call. Sarvex's services verify it — issuer, audience, signature (IdP JWKS), expiry — and read identity and tenant from its claims. Sarvex does not issue or revoke these tokens. merchant_id/store_id are read from the verified claims (and the merchant→store mapping), never from the URL. The operator scope is required for /operator/*. Operators acting on a specific merchant pass the X-Operate-As header, which is recorded in the audit log.

Query parameters
fromstring<date>

yyyy-MM-dd, inclusive. Defaults to 29 days before to. Range with to is capped at 92 days.

tostring<date>

yyyy-MM-dd, inclusive. Defaults to today (UTC). Range with from is capped at 92 days.

surfacechannel_surface

Restrict ranking and counts to one surface's contribution only. Omit for every surface combined.

Allowed:google_ai_modegoogle_geminiopenai_chatgptother_agentunknown
limitinteger

Top-N size. Defaults to 100.

default: 100
Responses
200

Top products by request count for the range, request-count descending.

datainsights_product_demand[]required
Show properties
Array of insights_product_demand
product_idstring
request_countinteger
surface_breakdownobject

Per-surface contribution to request_count. Keys are channel_surface values.

pagepagerequired
Show properties
cursorstring | nullrequired
has_morebooleanrequired
403

Authenticated but not permitted (e.g. non-operator on an operator route).

errorobjectrequired
Show properties
codestringrequired
messagestringrequired
detailsobject | null
422

Request body failed validation.

errorobjectrequired
Show properties
codestringrequired
messagestringrequired
detailsobject | null
Try it
Server
Authorization
Parameters
Request
curl -X GET "https://api.sarvex.example.com/v1/insights/product_demand" \
  -H "Authorization: Bearer YOUR_TOKEN"
Response
{
  "data": [
    {
      "product_id": "string",
      "request_count": 0,
      "surface_breakdown": {
        "property1": 0,
        "property2": 0
      }
    }
  ],
  "page": {
    "cursor": "string",
    "has_more": true
  }
}