> For the complete index of the 402pay docs, see [llms.txt](https://developer.402pay.co/llms.txt).

# Retrieve metrics

Get revenue, payment counts, new customers and approval rate over time, with the period before.

`GET https://dash.402pay.co/api/v1/metrics`

The numbers on the dashboard's home page, for any range. Each metric has a `total`, a `series` with one value per bucket in `buckets`, and the same for the period just before in `previous_total` and `previous_series`. `change_pct` compares the two, and is `null` without a comparison or when the previous total is zero.

Payments count in the bucket they were created in. Money is in US cents, and `range.end` is exclusive. A restricted key needs read access to payments.

### Metrics

- `revenue` (currency): What succeeded payments were worth.
- `net_revenue` (currency): Revenue plus fees customers paid, less 402pay's rate and flat fee on each payment.
- `successful_payments` (count): Payments that succeeded.
- `new_customers` (count): Customers whose first successful payment falls in the bucket.
- `average_payment` (currency): Revenue divided by successful payments.
- `approval_rate` (percent): The share of payments with an outcome that didn't fail, from 0 to 100. `pending` and `expired` payments never reached one, so they don't count.

### Query

- `period` (string): 24h, 3d, 7d, 30d, 4w, 3m, 12m, ytd or all, counted back from today. `all` starts at your first payment. Defaults to `30d`.
- `from` (date): A calendar date such as `2026-09-24`, sent with `to` instead of `period`.
- `to` (date): The last day of the range, included.
- `timezone` (string): An IANA time zone, such as `America/New_York`, that days and buckets follow. Defaults to `UTC`.
- `interval` (string): The bucket size: hour, day, week or month. Defaults to `hour` for `24h` and `day` otherwise.
- `compare` (string): `previous_period`, the default, or `none`, which leaves the previous fields `null`.

### Errors

- 400 `invalid_request` A parameter has a value it can't take, `period` was sent with `from` and `to`, or the range needs more than 1,000 buckets at the interval.

Any request can also fail on its key or its body. See [errors](https://developer.402pay.co/api/errors.md).

Request, cURL:

```bash
curl "https://dash.402pay.co/api/v1/metrics?from=2026-09-24&to=2026-09-26" \
  -H "Authorization: Bearer $PAY402_SECRET_KEY"
```

Request, Node.js:

```js
const response = await fetch("https://dash.402pay.co/api/v1/metrics?from=2026-09-24&to=2026-09-26", {
  headers: {
    Authorization: `Bearer ${process.env.PAY402_SECRET_KEY}`,
  },
});
const { data } = await response.json();
```

Request, Python:

```python
import os

import requests

response = requests.get(
    "https://dash.402pay.co/api/v1/metrics?from=2026-09-24&to=2026-09-26",
    headers={
        "Authorization": f"Bearer {os.environ['PAY402_SECRET_KEY']}",
    },
)
data = response.json()["data"]
```

Response, 200 OK:

```json
{
  "data": {
    "kind": "metrics",
    "currency": "USD",
    "timezone": "UTC",
    "interval": "day",
    "period": null,
    "range": {
      "start": "2026-09-24T00:00:00.000Z",
      "end": "2026-09-27T00:00:00.000Z"
    },
    "compare_range": {
      "start": "2026-09-21T00:00:00.000Z",
      "end": "2026-09-24T00:00:00.000Z"
    },
    "buckets": [
      "2026-09-24T00:00:00.000Z",
      "2026-09-25T00:00:00.000Z",
      "2026-09-26T00:00:00.000Z"
    ],
    "metrics": {
      "revenue": {
        "unit": "currency",
        "total": 184900,
        "series": [17400, 97500, 70000],
        "previous_total": 303000,
        "previous_series": [39800, 34500, 228700],
        "change_pct": -39
      },
      "net_revenue": {
        "unit": "currency",
        "total": 181944,
        "series": [17072, 95853, 69019],
        "previous_total": 300937,
        "previous_series": [39375, 33909, 227653],
        "change_pct": -39.5
      },
      "successful_payments": {
        "unit": "count",
        "total": 22,
        "series": [4, 9, 9],
        "previous_total": 17,
        "previous_series": [5, 6, 6],
        "change_pct": 29.4
      },
      "new_customers": {
        "unit": "count",
        "total": 3,
        "series": [0, 0, 3],
        "previous_total": 4,
        "previous_series": [0, 0, 4],
        "change_pct": -25
      },
      "average_payment": {
        "unit": "currency",
        "total": 8405,
        "series": [4350, 10833, 7778],
        "previous_total": 17824,
        "previous_series": [7960, 5750, 38117],
        "change_pct": -52.8
      },
      "approval_rate": {
        "unit": "percent",
        "total": 95.7,
        "series": [80, 100, 100],
        "previous_total": 89.5,
        "previous_series": [100, 85.7, 85.7],
        "change_pct": 6.9
      }
    }
  }
}
```