> For the complete documentation index, see [llms.txt](https://docs.blinklabs.xyz/blink/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.blinklabs.xyz/blink/data-api/metrics.md).

# Metrics

Time-series metrics API powering the Blink dashboard graphs

Returns the same time-series data that backs the graphs on your [dashboard](https://portal.blinklabs.xyz/dashboard). One bucketed series per metric, over a date range, for a single chain.

```
GET https://portal.blinklabs.xyz/api/metrics
```

Requests are authenticated with a bearer token:

```
Authorization: Bearer blink_...
```

The token determines whose data is returned — you always receive your own metrics, and an `originator` query parameter is ignored.

### Query parameters

| Parameter | Required | Description                                                                       |
| --------- | -------- | --------------------------------------------------------------------------------- |
| `type`    | Yes\*    | A single metric name. Returns a bare array.                                       |
| `types`   | Yes\*    | Comma-separated metric names. Returns an object keyed by metric name.             |
| `from`    | Yes      | Start of the range, ISO 8601 (e.g. `2026-08-01T00:00:00Z`). Inclusive.            |
| `to`      | Yes      | End of the range, ISO 8601. Inclusive.                                            |
| `chain`   | Yes      | `ethereum`, `base`, `bsc`, `arbitrum`, `robinhood` or `solana`. Case-insensitive. |
| `period`  | No       | Bucket size: `hour` or `day`. Defaults to `day`.                                  |

\*Supply exactly one of `type` or `types`. If both are present, `types` wins and `type` is ignored.

Prefer `types` whenever you need more than one metric — the batch form resolves every metric in a single database round trip, whereas repeated `type` calls run one query each.

Two things to watch when building the query string:

* `chain` falls back to `ethereum` if the value isn't recognised, rather than returning an error. A typo produces plausible-looking Ethereum data.
* `period` only meaningfully supports `hour` and `day`. Other values are passed through to bucketing but the response series is still generated at hourly granularity, so the buckets will not line up.

### Metrics

| Metric                        | Unit                     | Notes                                                                                                                |
| ----------------------------- | ------------------------ | -------------------------------------------------------------------------------------------------------------------- |
| `mev_recoveries`              | Native (ETH / BNB / SOL) | Your share, after your recovery percentage is applied                                                                |
| `gas_recoveries`              | Native                   | Your share, after your gas recovery percentage is applied                                                            |
| `transaction_count`           | Count                    | Transactions in the bucket                                                                                           |
| `revert_percentage`           | Percent, `0`–`100`       | Reverted transactions ÷ total transactions                                                                           |
| `latency`                     | Seconds, 4 dp            | Mean, weighted by transaction count                                                                                  |
| `priority_fee`                | Gwei                     | Mean, weighted by transaction count. **Ethereum only**                                                               |
| `exclusive_count`             | Count                    | Transactions eligible for gas recovery — shown as **Gas Recoverable** on the dashboard. **Ethereum only**            |
| `swap_volume_usd`             | USD, 2 dp                | Swap volume                                                                                                          |
| `sponsored_swap_volume_usd`   | USD, 2 dp                | Swap volume on gas-sponsored transactions                                                                            |
| `sponsored_transaction_count` | Count                    | Gas-sponsored transactions                                                                                           |
| `sponsor_cost`                | Native or USD            | Sponsorship cost. Derived from sponsored volume for billed originators; native spend for self-sponsoring originators |

Note that `exclusive_count` is the figure shown as **Gas Recoverable** on the dashboard — the metric name and the label differ.

Requesting an Ethereum-only metric on another chain is not an error. With `type` you get an empty array; with `types` you get a fully-formed series of zeros.

An unrecognised metric name is likewise not an error — `type` returns `[]`, and `types` returns a zero-filled series for that name. Check your spelling against the table above; a typo is silent.

### Response

Every response is a series of `{ timestamp, value }` points:

* `timestamp` is ISO 8601 UTC (`2026-08-01T00:00:00.000Z`), aligned to the start of the bucket.
* The series is **gap-filled**: every bucket in the range is present. A bucket with no underlying data has `value: 0`.
* Buckets in the future have `value: null`.

So the length of the array is determined entirely by `from`, `to` and `period` — not by how much data exists.

#### Single metric

```bash
curl -H "Authorization: Bearer blink_..." \
  "https://portal.blinklabs.xyz/api/metrics?type=mev_recoveries&chain=ethereum&from=2026-08-01T00:00:00Z&to=2026-08-03T00:00:00Z&period=day"
```

```json
[
  { "timestamp": "2026-08-01T00:00:00.000Z", "value": 1.284917 },
  { "timestamp": "2026-08-02T00:00:00.000Z", "value": 0.938204 },
  { "timestamp": "2026-08-03T00:00:00.000Z", "value": 1.551062 }
]
```

#### Multiple metrics

```bash
curl -H "Authorization: Bearer blink_..." \
  "https://portal.blinklabs.xyz/api/metrics?types=mev_recoveries,transaction_count&chain=ethereum&from=2026-08-01T00:00:00Z&to=2026-08-02T00:00:00Z&period=day"
```

```json
{
  "mev_recoveries": [
    { "timestamp": "2026-08-01T00:00:00.000Z", "value": 1.284917 },
    { "timestamp": "2026-08-02T00:00:00.000Z", "value": 0.938204 }
  ],
  "transaction_count": [
    { "timestamp": "2026-08-01T00:00:00.000Z", "value": 48213 },
    { "timestamp": "2026-08-02T00:00:00.000Z", "value": 51907 }
  ]
}
```

### Errors

| Status | Body                                            | Cause                                          |
| ------ | ----------------------------------------------- | ---------------------------------------------- |
| `400`  | `{ "error": "Missing required parameter ..." }` | `type`/`types`, `from`, `to` or `chain` absent |
| `400`  | `{ "error": "Invalid date format" }`            | `from` or `to` not parseable                   |
| `401`  | `{ "error": "No originator found" }`            | Missing, malformed, revoked or expired token   |
| `500`  | `{ "error": "Failed to fetch data" }`           | Server-side failure                            |