# Metrics

The same KPI tiles the dashboard shows, over a window you name. Money is integer
minor units (cents). `approval_rate` is a 0..1 fraction; `approval_rate_bps` is
the same figure in basis points (9356 = 93.56%).

```
GET    https://api.worthypayments.com/v1/metrics
```

| Scope | Grants |
|-------|--------|
| `metrics:read` | Read the KPI roll-up |

This is a reporting read, not a money-moving call. It does not replace
[charges](./03-charges.md) or [webhooks](./16-webhooks.md) for reconciling a
single payment.

---

## Query

| Parameter | Notes |
|-----------|-------|
| `period` | `today`, `7d`, `30d` (default), `90d`, or `all`. Ignored when both custom dates are set. |
| `start_date` | Custom window start, `YYYY-MM-DD`. Use with `end_date`. |
| `end_date` | Custom window end, `YYYY-MM-DD`. Use with `start_date`. |

```bash
curl "https://api.worthypayments.com/v1/metrics?period=30d" \
  -H "x-api-key: sk_test_xxx"
```

```json
{
  "object": "metrics",
  "gross_volume": 4820000,
  "approved_volume": 4510000,
  "net_volume": 4390000,
  "refunds": 120000,
  "approval_rate_bps": 9356,
  "approval_rate": 0.9356,
  "tx_count": 512,
  "approved_count": 479,
  "declined_count": 33,
  "refund_count": 8,
  "dispute_count": 2
}
```

A custom window:

```bash
curl "https://api.worthypayments.com/v1/metrics?start_date=2026-08-01&end_date=2026-08-31" \
  -H "x-api-key: sk_test_xxx"
```

Missing `metrics:read` is `403 permission_denied`.