Skip to content

analytics-endpoints.mdx

Latest commit

 

History

History
158 lines (123 loc) · 3.84 KB

analytics-endpoints.mdx

File metadata and controls

158 lines (123 loc) · 3.84 KB
title Analytics Endpoints
description Curl examples for ClickHouse-backed analytics, charts, payment audit, and decision trace.

Analytics Endpoints

Analytics routes derive the merchant from the authenticated user/API key context and read from the analytics store. Use these endpoints for dashboard charts, payment audit, rule/volume decision inspection, and debit-routing audit.

Common query parameters:

Parameter Values
range 15m, 1h, 12h, 1d, 1w
start_ms, end_ms custom epoch-millisecond window
page, page_size paginated list endpoints
gateway, status, route, flow_type, routing_approach, exclude_routing_approach filters
payment_id exact payment lookup for audit and trace views
error_code failure filtering

Overview

High-level dashboard summary for the selected merchant and time window.

curl "$BASE_URL/analytics/overview?range=1d" \
  --header "$AUTH_HEADER"
{
  "request_count": 42,
  "top_gateway": "adyen",
  "gateway_share": [
    { "gateway": "adyen", "count": 22, "share": 52.4 }
  ]
}

Gateway Scores

Auth-rate score snapshots and connector success-rate trend.

curl "$BASE_URL/analytics/gateway-scores?range=1d&gateway=stripe,adyen" \
  --header "$AUTH_HEADER"
{
  "latest": [
    { "gateway": "adyen", "score": 0.831 },
    { "gateway": "stripe", "score": 0.829 }
  ],
  "series": [
    { "timestamp_ms": 1777136400000, "gateway": "adyen", "score": 0.831 }
  ]
}

Decisions

Decision volume by connector and routing approach.

curl "$BASE_URL/analytics/decisions?range=1d" \
  --header "$AUTH_HEADER"
curl "$BASE_URL/analytics/decisions?range=1d&exclude_routing_approach=NTW_BASED_ROUTING" \
  --header "$AUTH_HEADER"

Routing Stats

Connector share, rule hits, routing filter options, and chart data.

curl "$BASE_URL/analytics/routing-stats?range=1d&payment_method_type=CARD" \
  --header "$AUTH_HEADER"

Log Summaries

Failure aggregates and recent error samples.

curl "$BASE_URL/analytics/log-summaries?range=1d&status=failure" \
  --header "$AUTH_HEADER"

Payment Audit

Payment-level trail search. Prefer payment_id for exact lookup.

curl "$BASE_URL/analytics/payment-audit?range=1d&page=1&page_size=12&payment_id=pay_001" \
  --header "$AUTH_HEADER"
curl "$BASE_URL/analytics/payment-audit?range=1d&gateway=stripe&status=success&page=1&page_size=10" \
  --header "$AUTH_HEADER"
{
  "summary": {
    "matching_payments": 1,
    "failures": 0,
    "active_gateways": ["stripe"]
  },
  "payments": [
    {
      "payment_id": "pay_001",
      "latest_status": "success",
      "gateways": ["stripe"]
    }
  ],
  "timeline": [
    {
      "route": "decide_gateway",
      "event_stage": "gateway_decided",
      "gateway": "stripe",
      "status": "success"
    }
  ]
}

Preview Trace

Rule/volume decisions captured from /routing/evaluate. The transport route remains /analytics/preview-trace even when the UI labels these as decisions.

curl "$BASE_URL/analytics/preview-trace?range=1d&page=1&page_size=12&route=routing_evaluate" \
  --header "$AUTH_HEADER"
curl "$BASE_URL/analytics/preview-trace?range=1d&payment_id=volume_decision_001" \
  --header "$AUTH_HEADER"

Debit Routing Audit

curl "$BASE_URL/analytics/payment-audit?range=1d&routing_approach=NTW_BASED_ROUTING" \
  --header "$AUTH_HEADER"

Notes

  • Use range for preset windows and start_ms/end_ms for custom windows.
  • Use page and page_size on list-heavy views such as payment audit and preview trace.
  • Use exclude_routing_approach=NTW_BASED_ROUTING when auth-rate audit should hide debit-routing decisions.
  • Freshly inserted analytics events may take a short moment to appear because writes are asynchronous.