Analytics Overview

August 3, 2026 · View on GitHub

Use case

Returns summary metrics for the dashboard overview: request volume, gateway share, setup status, and recent activity.

Authentication

Protected. Send either Authorization: Bearer <jwt_token> or x-api-key: <api_key>. In sandbox, also send x-feature: decision-engine.

For local development, start with:

export BASE_URL=http://localhost:8080
export AUTH_HEADER="Authorization: Bearer <jwt_token>"
export TENANT_HEADER="x-tenant-id: public"
# Sandbox only:
# export BASE_URL=https://sandbox.hyperswitch.io
# export FEATURE_HEADER="x-feature: decision-engine"

Request

  • Method and path: GET /analytics/overview
  • Parameters:
    • x-tenant-id (header, required, string) — see Environment setup.
    • range (query, optional, string)
    • start_ms (query, optional, integer)
    • end_ms (query, optional, integer)
    • page (query, optional, integer)
    • page_size (query, optional, integer)
    • payment_method_type (query, optional, string)
    • payment_method (query, optional, string)
    • card_network (query, optional, string)
    • card_is_in (query, optional, string)
    • currency (query, optional, string)
    • country (query, optional, string)
    • auth_type (query, optional, string)
    • gateway (query, optional, string)
    • payment_id (query, optional, string)
    • request_id (query, optional, string)
    • route (query, optional, string)
    • status (query, optional, string)
    • flow_type (query, optional, string)
    • routing_approach (query, optional, string)
    • exclude_routing_approach (query, optional, string)
    • error_code (query, optional, string)
  • Body: Optional query parameters include range, start_ms, and end_ms.

Example

Overview last day

curl "$BASE_URL/analytics/overview?range=1d" \
  --header "$AUTH_HEADER" \
  --header "$TENANT_HEADER"

Response

{
  "merchant_id": "merchant_demo",
  "kpis": [
    { "label": "Decision events / 1d", "value": "42", "subtitle": "Counts decision events, not unique payments" },
    { "label": "Score snapshots", "value": "18", "subtitle": "Latest gateway score updates" },
    { "label": "Rule hits", "value": "12", "subtitle": "Priority-logic hits" },
    { "label": "Errors", "value": "3", "subtitle": "Recorded error events" }
  ],
  "route_hits": [
    { "route": "decide_gateway", "count": 42 },
    { "route": "update_gateway_score", "count": 40 }
  ],
  "top_scores": [
    {
      "merchant_id": "merchant_demo",
      "payment_method_type": "CARD",
      "payment_method": "CREDIT",
      "gateway": "adyen",
      "score_value": 0.831,
      "sigma_factor": null,
      "average_latency": null,
      "tp99_latency": null,
      "transaction_count": 214,
      "last_updated_ms": 1808624000000
    }
  ],
  "top_errors": [
    { "route": "decide_gateway", "error_code": "processor_declined", "error_message": "Card declined by issuer", "count": 3, "last_seen_ms": 1808624000000 }
  ],
  "top_rules": [
    { "rule_name": "priority rule", "count": 12 }
  ],
  "smart_retry_stats": {
    "retried_count": 8,
    "recovered_count": 5,
    "by_trigger": [
      { "gateway": "stripe", "error_code": "processor_declined", "count": 3 }
    ],
    "by_fallback": [
      { "gateway": "adyen", "retried": 8, "recovered": 5 }
    ]
  }
}

Notes

  • Analytics reads are ClickHouse-backed and merchant-scoped by the authenticated context.
  • Use range=15m|1h|12h|1d|1w or start_ms plus end_ms for a custom window.
  • Use this for high-level status, not detailed payment debugging.