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

KPI summary, per surface and combined, with prior-period deltas

One row per surface the merchant has data for that month, plus one combined “all” row. Deltas are against the prior calendar month, computed server-side from stored counts — never a stored percentage. sessions_inferred is always reported alongside sessions so a reconstructed count is never mistaken for an exact one.

GET/channel/summary
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
monthstring

yyyy-MM. Defaults to the current UTC month.

store_idstring

Restrict to one store. Omit for every store the merchant operates (modelled for multiple stores per merchant).

Responses
200

One summary row per surface, plus one combined row.

datachannel_summary[]required
Show properties
Array of channel_summary
surfacechannel_surface_or_all

channel_surface's domain plus the literal "all", used only on the combined-across-surfaces row (channel_summary, channel_funnel). Distinct from channel_surface because the query parameter and channel_daily_entry never emit "all" — a daily row is always one real surface.

Allowed:google_ai_modegoogle_geminiopenai_chatgptother_agentunknownall
monthstring
sessionsinteger
sessions_confirmedinteger

sessions minus sessions_inferred, exposed directly rather than left for the caller to derive — an aggregate can honestly contain both confirmed and inferred sessions, so this is a count, not a single categorical attribution flag.

sessions_inferredinteger

The subset of sessions whose correlation to their initiating event had to be reconstructed rather than observed directly — never presented as exact.

checkouts_completedinteger
revenue_minorinteger
currencystring | null

Absent (with currency_mixed=false) when no revenue-bearing day exists yet in this row; absent with currency_mixed=true when the summed days/surfaces genuinely disagree on currency. Never a silently-picked first-seen value.

currency_mixedboolean
cart_ratenumber<double>
checkout_ratenumber<double>
completion_ratenumber<double>
aov_minorinteger
prior_periodobject

Deltas against the prior calendar month, computed server-side from stored counts (never a stored delta).

Show properties
sessions_deltainteger
checkouts_completed_deltainteger
revenue_minor_deltainteger
aov_minor_deltainteger

Current aov_minor minus the prior period's.

completion_rate_deltanumber<double>

Current completion_rate minus the prior period's.

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/channel/summary" \
  -H "Authorization: Bearer YOUR_TOKEN"
Response
{
  "data": [
    {
      "surface": "google_ai_mode",
      "month": "2026-08",
      "sessions": 0,
      "sessions_confirmed": 0,
      "sessions_inferred": 0,
      "checkouts_completed": 0,
      "revenue_minor": 0,
      "currency": "string",
      "currency_mixed": true,
      "cart_rate": 0.1,
      "checkout_rate": 0.1,
      "completion_rate": 0.1,
      "aov_minor": 0,
      "prior_period": {
        "sessions_delta": 0,
        "checkouts_completed_delta": 0,
        "revenue_minor_delta": 0,
        "aov_minor_delta": 0,
        "completion_rate_delta": 0.1
      }
    }
  ],
  "page": {
    "cursor": "string",
    "has_more": true
  }
}