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

# Metrics

Metrics return timeseries data about the information in your Paddle account, either as fixed values or as a flexible, filterable query.

---

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. They're typically used for powering dashboards and analytics.

There are two ways to get metrics data from Paddle:

- **Fixed metrics**: a dedicated endpoint per metric (for example, `GET /metrics/revenue`) returns one datapoint per interval over a date range you specify.
- **Explore metrics**: a single, flexible endpoint that queries one entity at a time, with optional filters, a breakdown dimension, and pagination.

Use a fixed metric endpoint if you need one well-known number over time. Use Explore metrics if you need flexible filtering and breakdown options across the available data, useful for displaying chart data in dashboards.

## Fixed metrics

Fixed metrics return information like:

- An array of timestamped datapoints for a period of time
- The date range covered
- The granularity of the data
- The currency amounts are expressed in, where relevant

You pass a date range using the `from` and `to` query parameters, and Paddle returns one datapoint per interval in that range.

### Response format

Datapoints include different value fields depending 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 other actions 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`.

## Explore metrics

An Explore query targets one entity with a measure applied to it. An entity is the dataset you're querying, such as `transactions.completed`. It determines the measures you can calculate from it, like `gross_revenue`, and the dimensions you can use to filter or break down the results, like `country`.

Call {% method-badge method="GET" /%} `/metrics/explore/entities` to get the current list of measures and dimensions available for each entity, then send a {% method-badge method="POST" /%} request to `/metrics/explore` with an `entity`, a date range, and one or more `measures` to get the data. Optionally add `dimensions` to break the results down, `filters` to narrow them, and `order_by` to control which segments appear first.

{% callout type="info" %}
The Explore metrics endpoints let you query up to 3 years in the past.
{% /callout %}

### Pagination

The Explore metrics operation paginates differently to list operations. It returns five segments per page by default and a maximum of 50, set with `per_page`. A segment is one combination of the dimensions you broke down by, such as a single product, and each one carries its own complete timeseries. This means `per_page` counts segments, not datapoints.

The `after` cursor is tied to the exact query body you sent, so send that same body again when you request the next page rather than fetching `meta.pagination.next` directly.

A cursor lasts an hour from when it's issued, extended each time you use it, up to 24 hours. Don't store cursors to resume later, request the first page again instead.

For more details, see [Pagination](https://developer.paddle.com/api-reference/about/pagination.md).