> For the complete documentation index, see [llms.txt](https://developer.paddle.com/llms.txt).

# Get metrics data for your account using the API

Build dashboards and analytics pipelines with seven new metrics operations that return timeseries data about your Paddle account.

---

## What's new?

We've added a new set of operations under the `/metrics` path to the Paddle API. They return timeseries data for key business metrics, aggregated by day across a date range you specify.

{% accordion %}
{% accordion-item title="Subscription health" %}

{% api-endpoint method="GET" path="/metrics/monthly-recurring-revenue" /%}
{% api-endpoint method="GET" path="/metrics/monthly-recurring-revenue-change" /%}
{% api-endpoint method="GET" path="/metrics/active-subscribers" /%}

{% /accordion-item %}
{% accordion-item title="Financial health" %}

{% api-endpoint method="GET" path="/metrics/revenue" /%}
{% api-endpoint method="GET" path="/metrics/refunds" /%}
{% api-endpoint method="GET" path="/metrics/chargebacks" /%}

{% /accordion-item %}
{% accordion-item title="Checkout performance" %}

{% api-endpoint method="GET" path="/metrics/checkout-conversion" /%}

{% /accordion-item %}
{% /accordion %}

All operations require the new `metrics.read` [permission](https://developer.paddle.com/api-reference/about/permissions.md).

## How it works

Metrics are a way of querying aggregated data from your Paddle account. Unlike [reports](https://developer.paddle.com/api-reference/reports.md), which export a historical snapshot of your entities as a CSV, metrics return timeseries data directly in the API response.

You can use them to build dashboards, reporting tools, and any integration that needs to track trends over time without pulling and aggregating raw entity data yourself.

When working with metrics, you can use the `from` (inclusive) and `to` (exclusive) query parameters to set the date range. Paddle returns one datapoint per day in that range, each with a `timestamp` and a set of value fields depending on the metric.

The shape of the datapoint depends on the metric:

- **Amount-based**  
  Metrics related to revenue return an `amount` field, expressed as a string representing a non-decimal amount in the smallest currency unit.
- **Count-based**  
  Metrics related to subscriber or event counts return a `count` field.
- **Mixed**  
  Some metrics return both an `amount` and a `count` field, and may include other fields. For example, checkout conversion returns `count`, `completed_count`, and `rate`.

All responses include `starts_at`, `ends_at`, `interval`, and `updated_at` at the top level.

## Next steps

This change is available in version `1` of the Paddle API.

These are new endpoints. There are no breaking changes to existing integrations. Existing API keys don't inherit the new `metrics.read` permission, so you'll need to update them to include it.

To get started, make sure the API key you're using has the `metrics.read` permission, then call any of the [`/metrics` endpoints](https://developer.paddle.com/api-reference/metrics.md) with a `from` and `to` date range.
## Summary of changes

| Name | Type | Change | Entity | Description |
| --- | --- | --- | --- | --- |
| `GET /metrics/monthly-recurring-revenue` | API operation | added | Metrics | Returns daily MRR across active subscriptions. |
| `GET /metrics/monthly-recurring-revenue-change` | API operation | added | Metrics | Returns the daily net change in MRR. |
| `GET /metrics/active-subscribers` | API operation | added | Metrics | Returns the daily count of active subscribers. |
| `GET /metrics/revenue` | API operation | added | Metrics | Returns daily revenue collected and transaction count. |
| `GET /metrics/refunds` | API operation | added | Metrics | Returns the daily refunded amount. |
| `GET /metrics/chargebacks` | API operation | added | Metrics | Returns the daily chargeback count. |
| `GET /metrics/checkout-conversion` | API operation | added | Metrics | Returns daily checkout sessions, completions, and conversion rate. |
| `metrics.read` | Permission | added | API key | New permission required for all `/metrics` endpoints. |