Metrics

Metrics are a way of querying aggregated data from your Paddle account.

Unlike reports, 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 GET /metrics/explore/entities to get the current list of measures and dimensions available for each entity, then send a 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.

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.