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

# Explore your account data and metrics

Filter, break down, and investigate the metrics and data available in your Paddle account, from the dashboard or the API.

---

The overview page in your Paddle dashboard gives you a summary of your business's performance. It presents revenue, subscription, and conversion metrics as charts designed for a fast check-in.

When you want a closer look at that data with flexible filtering and breakdown options, go to the Explore page instead. Explore is built for ad hoc investigations and lets you spot trends or investigate unexpected changes without exporting your data or using a separate analytics tool.

Choose the metric you want to examine, apply filters, and group the results to answer specific questions about your business.

## How it works

The Explore page and metrics operations use the same underlying data as the overview page, with more control and precision over how you view it.

Opening a chart directly from the overview page takes you into Explore with the same filters already applied, so you can continue your investigation without starting over.

### Dimensions

With Explore, you can tailor the page view and the data it displays by making selections across four dimensions: metrics, filters, breakdown, and granularity.

Your view selections are captured in the page URL, so you can share the exact charts with your team by sharing the URL.

#### Metrics

Metrics are the numbers that represent what you want to understand about your business.

{% card-group cols=2 %}
{% card title="Revenue" %}
The total transaction value minus discounts, before deductions like tax, Paddle's fees, refunds, or chargebacks are taken out.
{% /card %}
{% card title="Transactions" %}
The number of completed transactions and paid B2B invoices in the period.
{% /card %}
{% card title="Refunds" %}
The total amount refunded to customers, not including chargebacks.
{% /card %}
{% card title="Chargebacks" %}
The number of chargebacks raised against completed transactions, excluding warnings and reversals.
{% /card %}
{% card title="Checkout conversion" %}
The proportion of checkout sessions that resulted in a completed payment.
{% /card %}
{% card title="MRR" %}
Your total monthly recurring revenue from active subscriptions.
{% /card %}
{% card title="MRR growth" %}
The net change in MRR in a given period (new, expansion, and reactivation revenue) minus contraction and churn.
{% /card %}
{% /card-group %}

#### Filters

Filters help you narrow down the data behind your chosen metric before it's grouped or totaled. Use a single filter for a broad view, or combine multiple filters to narrow the data to a more specific scenario:

- **Date range**: must be a single, continuous period.
- **Frequency**: narrow down to a subscription's billing cycle.
- **Product**: choose one or more products.
- **Country**: choose one or more countries.

{% callout type="info" %}
You can select multiple products, countries, and frequencies to filter your data. You can only select a single date range at a time up to 2 years in the past.
{% /callout %}

#### Breakdown

Breakdown groups your chosen metric into categories so you can compare them, instead of seeing a single total. You can pick one breakdown at a time, or none at all:

- None
- Product
- Country
- Frequency
- Subscription actions (only available for MRR and MRR growth)

{% callout type="info" %}
Choosing **None** as your breakdown displays the data as a single totals line.
{% /callout %}

#### Granularity

Granularity controls how your data is grouped over time in both the chart and the table that follows:

- Daily
- Weekly, starting on Monday
- Monthly

Paddle picks a default based on your selected date range, but you can change it at any time.

### Things to know

{% callout type="info" %}
The data in Explore refreshes on a 24-hour cycle, so it can take up to 24 hours for new activity to appear.
{% /callout %}

- **Total rows aren't always a sum of the preceding rows.**  
  Some breakdowns associate a single record with more than one row, for example a transaction that includes more than one product. The total always matches the figure you'd see with no breakdown applied, so it can be lower than the sum of the individual rows.
- **Other is a total of everything that can't be displayed in a chart.**  
  When a breakdown has more distinct values than can be displayed on the chart, Explore displays the top values on individual lines and rolls up everything else into a single "Other" line.

## View your metrics in Explore

{% tabs sync="interaction-preference" %}
{% tab-item title="Dashboard" %}

{% instruction-steps %}

1. Go to **Paddle > Analytics > Explore**.
2. Choose the metric you want to view and make selections for filters, breakdown, and granularity to narrow down the output. See [Dimensions](#dimensions) for what each one does.
3. Review the chart and the table that follows, now updated with your selections.

{% /dashboard-instructions %}

{% callout type="info" %}
You can also open Explore by selecting a chart on the overview page, or from a direct link shared with you. The existing filters are carried across.
{% /callout %}

{% /tab-item %}
{% tab-item title="API" %}

Use the Paddle API to query and explore your account data programmatically using the same filtering and breakdown options available in the dashboard.

Query your data using the API in three steps:

1. **Discover what you can query**  
   Query the relevant entity to see what dimensions, measures, and filters are available.
2. **Query an entity**  
   Send a request with the entity, a date range, and one or more selections to get the data for the relevant metric back.
3. **Paginate through results**  
   Where a request has more results, get the next page by sending another POST request.

Each metric shown in Explore maps to a specific entity in the API:

| Metric | Entity |
| --- | --- |
| Revenue | `transactions.completed` |
| Transactions | `transactions.completed` |
| Refunds | `adjustments.refunds` |
| Chargebacks | `adjustments.chargebacks` |
| Checkout conversion | `checkouts` |
| MRR | `subscriptions` |
| MRR growth | `subscriptions` |

{% callout type="info" %}
The `subscriptions` entity isn't available in sandbox, so MRR and MRR growth return no data there. Use a live account to query them.
{% /callout %}

### Discover entities {% step=true %}

Send a {% method-badge method="GET" /%} request to [`/metrics/explore/entities`](https://developer.paddle.com/api-reference/metrics/list-explore-metric-entities.md) to see what dimensions, measures, and filters are available.

Use the `entity` query parameter to look up a single entity. Omit to list everything available in your account.

This example returns dimensions, measures, and filters for revenue metrics by passing `transactions.completed` as a value to the `entity` query parameter.

{% api-example method="GET" path="/metrics/explore/entities?entity=transactions.completed" href="/api-reference/metrics/list-explore-metric-entities" %}

```json {% title="Response (200 OK)" %}
{
  "data": [
    {
      "entity": "transactions.completed",
      "time_dimension": {
        "intervals": ["day", "week", "month"],
        "max_lookback_days": 1096
      },
      "dimensions": [
        { "name": "product", "type": "string", "filter_ops": ["in"], "multi_valued": false },
        { "name": "country", "type": "string", "filter_ops": ["in"], "multi_valued": false },
        { "name": "billing_cycle", "type": "string", "filter_ops": ["in"], "multi_valued": false }
      ],
      "measures": [
        { "name": "gross_revenue", "type": "currency", "aggs": ["sum"] },
        { "name": "id", "type": "string", "aggs": ["count", "count_distinct"] }
      ]
    }
  ],
  "meta": {
    "request_id": "b93d9c94-c28f-4e5d-af2e-044854d7afe8"
  }
}
```

{% /api-example %}

### Query an entity {% step=true %}

Send a {% method-badge method="POST" /%} request to [`/metrics/explore`](https://developer.paddle.com/api-reference/metrics/run-explore-metrics-query.md) with the `entity`, `from` and `to` dates, an `interval`, and one or more `measures` and `dimensions`.

`from` is inclusive and `to` is exclusive, so a `to` of `2026-08-01` with a monthly interval returns buckets up to and including July. A `to` in the future is clamped to the current time.

{% callout type="info" %}
`order_by` is optional. Leave it out and Explore orders by the entity's default, which you can see in the catalog. Set it when you break results down by a dimension, because it decides which segments land on the page.
{% /callout %}

Each value in the response is named after the aggregation and the field it came from, so `{ "field": "gross_revenue", "agg": "sum" }` comes back as `sum_gross_revenue`. Derived measures have no aggregation, so they keep their field name — `mrr` and `checkout_conversion` come back unchanged.

Dimensions return Paddle IDs rather than display names, so a `product` dimension returns a `pro_` ID that you can look up using the [get a product](https://developer.paddle.com/api-reference/products/get-product.md) operation.

Each combination of the dimensions you break down by is a segment: one product, or one product and country pair. Segments are the API equivalent of the categories a breakdown creates in the dashboard. Explore returns one entry in `series` for every segment, and each one carries its complete timeseries.

{% accordion %}
{% accordion-item title="Query revenue broken down by product" %}

This example returns gross revenue for the five highest-earning products, bucketed by month across three months. `order_by` and `per_page` together narrow 42 products down to the top five, and each series carries one datapoint per bucket so you can see the trend as well as the ranking.

{% api-example method="POST" path="/metrics/explore" href="/api-reference/metrics/run-explore-metrics-query" %}

```json {% title="Request" %}
{
  "entity": "transactions.completed",
  "from": "2026-05-01",
  "to": "2026-08-01",
  "interval": "month",
  "dimensions": ["product"],
  "measures": [
    { "field": "gross_revenue", "agg": "sum" }
  ],
  "order_by": [
    { "field": "gross_revenue", "dir": "desc" }
  ],
  "per_page": 5
}
```

```json {% title="Response (200 OK)" collapse=true %}
{
  "data": {
    "entity": "transactions.completed",
    "interval": "month",
    "currency_code": "USD",
    "starts_at": "2026-05-01T00:00:00Z",
    "ends_at": "2026-08-01T00:00:00Z",
    "updated_at": "2026-08-01T06:00:00Z",
    "fields": {
      "dimensions": [{ "name": "product", "type": "string" }],
      "measures": [{ "name": "sum_gross_revenue", "type": "currency", "field": "gross_revenue", "agg": "sum" }]
    },
    "series": [
      {
        "dimensions": { "product": "pro_01h1vjfevh5etwq3rb416a23h2" },
        "timeseries": [
          { "timestamp": "2026-05-01T00:00:00Z", "measures": { "sum_gross_revenue": "410500" } },
          { "timestamp": "2026-06-01T00:00:00Z", "measures": { "sum_gross_revenue": "455200" } },
          { "timestamp": "2026-07-01T00:00:00Z", "measures": { "sum_gross_revenue": "482000" } }
        ]
      }
    ]
  },
  "meta": {
    "request_id": "b93d9c94-c28f-4e5d-af2e-044854d7afe8",
    "pagination": {
      "per_page": 5,
      "next": "https://api.paddle.com/metrics/explore?after=eyJ2IjoxLCJxaWQiOiIwMWpuOHg0azJwN3E5ciIsIm9mZiI6NSwicWgiOiJzaGEyNTY6OWYyYzRkMWUiLCJleHAiOjE3ODU1Njc2MDB9",
      "has_more": true,
      "estimated_total": 42
    }
  }
}
```

{% /api-example %}

{% /accordion-item %}
{% accordion-item title="Query refunds with no breakdown" %}

This example returns the total refunded across July 2026, with no breakdown applied. Omit `dimensions` and `order_by` when you want a single figure rather than a set of segments. The response holds one series with an empty `dimensions` object.

{% api-example method="POST" path="/metrics/explore" href="/api-reference/metrics/run-explore-metrics-query" %}

```json {% title="Request" %}
{
  "entity": "adjustments.refunds",
  "from": "2026-07-01",
  "to": "2026-08-01",
  "interval": "month",
  "measures": [
    { "field": "amount", "agg": "sum" }
  ]
}
```

```json {% title="Response (200 OK)" collapse=true %}
{
  "data": {
    "entity": "adjustments.refunds",
    "interval": "month",
    "currency_code": "USD",
    "starts_at": "2026-07-01T00:00:00Z",
    "ends_at": "2026-08-01T00:00:00Z",
    "updated_at": "2026-08-01T06:00:00Z",
    "fields": {
      "dimensions": [],
      "measures": [{ "name": "sum_amount", "type": "currency", "field": "amount", "agg": "sum" }]
    },
    "series": [
      {
        "dimensions": {},
        "timeseries": [
          { "timestamp": "2026-07-01T00:00:00Z", "measures": { "sum_amount": "15400" } }
        ]
      }
    ]
  },
  "meta": {
    "request_id": "b93d9c94-c28f-4e5d-af2e-044854d7afe8",
    "pagination": {
      "per_page": 5,
      "has_more": false,
      "estimated_total": 1
    }
  }
}
```

{% /api-example %}

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

{% callout type="info" %}
One page can return up to 10,000 datapoints: `per_page` multiplied by the number of time buckets in your date range. To stay under it, narrow the range between `from` and `to`, use a coarser `interval`, or lower `per_page`.
{% /callout %}

### Paginate through results {% step=true %}

Pagination for the Explore metrics operation works differently to [pagination for list operations](https://developer.paddle.com/api-reference/about/pagination.md).

Explore returns five segments per page by default, up to a maximum of 50. Set `per_page` in the request body to change it.

When `meta.pagination.has_more` is `true`, take the `after` value from `meta.pagination.next` and send it as an `after` query parameter, resending the same request body to get the next page.

Repeat until `has_more` is `false`. Paddle returns `next` on the last page too, so check `has_more` rather than the presence of `next` to decide whether to request another page.

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

{% /tab-item %}
{% /tabs %}