> ## Documentation Index
> Fetch the complete documentation index at: https://docs.meterlane.app/llms.txt
> Use this file to discover all available pages before exploring further.

# Gateway Metrics API: Usage Stats and Facilitator Health

> Query request volume, payment settlement counts, average latency, and on-chain facilitator status for your Meterlane Agent Gateway.

The metrics endpoint gives you a real-time summary of traffic and payment health across your gateway routes. You can query a rolling 24-hour or 7-day window to understand how many requests your routes are receiving, how many are converting from unpaid `402` challenges to settled payments, and whether the on-chain facilitator is operating normally. The same data is surfaced visually in the Meterlane dashboard under **Gateway → Metrics**.

***

## GET /api/gateway/metrics

Returns aggregated usage statistics and facilitator status for your organisation.

```http theme={null}
GET https://gateway.meterlane.app/api/gateway/metrics?window=24h
Authorization: Bearer bp_live_…
```

### Query parameters

<ParamField query="window" type="string" required>
  The time window to aggregate over. Accepted values:

  * `24h` — rolling last 24 hours
  * `7d` — rolling last 7 days
</ParamField>

### Response shape

The response is a JSON object with two top-level keys: `metrics` and `facilitator`.

#### `metrics` object

<ResponseField name="metrics.totalRequests" type="number">
  Total number of requests received across all routes in the window, including both unpaid probes and paid requests.
</ResponseField>

<ResponseField name="metrics.unpaid402" type="number">
  Number of requests that returned a `402 Payment Required` response. High values relative to `metrics.paid` may indicate agents are probing but not completing payment.
</ResponseField>

<ResponseField name="metrics.paid" type="number">
  Number of requests where payment was verified and the upstream was proxied successfully.
</ResponseField>

<ResponseField name="metrics.errors" type="number">
  Number of requests that resulted in a server-side error (5xx status).
</ResponseField>

<ResponseField name="metrics.avgChallengeMs" type="number | null">
  Average latency in milliseconds for the gateway to issue the `402` challenge response. `null` if no challenge requests were recorded in the window.
</ResponseField>

<ResponseField name="metrics.avgSettleMs" type="number | null">
  Average latency in milliseconds for the full payment verification and settlement cycle before the upstream response is returned. `null` if no paid requests were recorded in the window.
</ResponseField>

<ResponseField name="metrics.errorRate" type="number">
  Fraction of total requests that resulted in a server-side error, expressed as a decimal between `0` and `1`.
</ResponseField>

<ResponseField name="metrics.window" type="string">
  The time window that was aggregated: `"24h"` or `"7d"`.
</ResponseField>

#### `facilitator` object

<ResponseField name="facilitator.status" type="string">
  Current reachability of the x402 facilitator. Possible values: `"up"`, `"degraded"`, `"down"`.
</ResponseField>

<ResponseField name="facilitator.latencyMs" type="number">
  Round-trip latency in milliseconds for the most recent facilitator health probe.
</ResponseField>

<ResponseField name="facilitator.checkedAt" type="string">
  ISO 8601 timestamp of when the facilitator health probe was last run.
</ResponseField>

<ResponseField name="facilitator.facilitatorUrl" type="string">
  The facilitator URL that was probed.
</ResponseField>

### Example request

```bash theme={null}
curl "https://gateway.meterlane.app/api/gateway/metrics?window=24h" \
  -H "Authorization: Bearer bp_live_…"
```

### Example response

```json theme={null}
{
  "metrics": {
    "window": "24h",
    "orgId": "org_01hx9abcdefg",
    "totalRequests": 4821,
    "unpaid402": 1304,
    "paid": 3517,
    "errors": 12,
    "avgChallengeMs": 38,
    "avgSettleMs": 214,
    "errorRate": 0.0025
  },
  "facilitator": {
    "status": "up",
    "latencyMs": 112,
    "checkedAt": "2025-01-15T14:32:00Z",
    "facilitatorUrl": "https://x402.org"
  }
}
```

***

## Interpreting the metrics

<Tip>
  A healthy gateway typically shows `metrics.paid` close to `metrics.totalRequests - metrics.unpaid402`. If `metrics.unpaid402` is unexpectedly high and `metrics.paid` is low, check that your agent clients are correctly handling the `402` challenge and signing payments.
</Tip>

| Metric                                                  | What to watch for                                                                                    |
| ------------------------------------------------------- | ---------------------------------------------------------------------------------------------------- |
| `facilitator.status: "degraded"`                        | Settlement is slower than normal. Requests still succeed but `metrics.avgSettleMs` will be elevated. |
| `facilitator.status: "down"`                            | The on-chain facilitator is unreachable. Paid requests will fail until the facilitator recovers.     |
| `metrics.avgSettleMs` above 1000 ms                     | May indicate network congestion on the settlement chain.                                             |
| `metrics.unpaid402` / `metrics.totalRequests` above 50% | Agents are probing but not completing payment — check client integration.                            |

***

## Dashboard access

You can view these metrics without using the API directly. In the Meterlane dashboard, navigate to **Gateway → Metrics** and use the window selector to switch between the 24-hour and 7-day views. The dashboard also plots historical trends and breaks down traffic per route.

<Note>
  Metrics are updated approximately every 60 seconds. There may be a short lag between a request being processed and its data appearing in the API response or dashboard.
</Note>