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

# Understand your account data with Explore

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

---

## What's new?

We've added [Explore](https://developer.paddle.com/build/analytics/explore.md), a new page in the Paddle dashboard for filtering and breaking down your revenue, refunds, chargebacks, checkout conversion, and subscription metrics.

Explore is powered by two new metrics operations, so anything you can do in the dashboard you can query directly:

- {% method-badge method="GET" /%} `/metrics/explore/entities` lets you discover what's queryable: entities, their dimensions and measures, allowed aggregations, and permitted intervals.
- {% method-badge method="POST" /%} `/metrics/explore` lets you query one entity over a date range, optionally filtered, broken down by a single dimension, and paginated.

## How it works

With Explore, you can go from noticing something to understanding why it happened without leaving Paddle. Start from a metric, narrow it with filters, then group the results to see what changed and where.

Explore covers seven key metrics:

| Metric | Category |
| --- | --- |
| Revenue | Financial health |
| Transactions | Financial health |
| Refunds | Financial health |
| Chargebacks | Financial health |
| Checkout conversion | Checkout performance |
| MRR | Subscription health |
| MRR growth | Subscription health |

You can use these metrics to filter and break down further to tailor the results to your use case. For example, you can use Explore to:

- Diagnose changes, like understanding why revenue increased or decreased over a period.
- Find where you're underperforming, like breaking down checkout conversion, refunds, and chargebacks by country, product, and billing frequency.
- Understand the shape of your business, like which markets perform best, which products carry your business, and how much of your revenue is monthly vs. annual.
- Get advanced insights by combining queries, like analyzing whether a market is growing because of more sales or higher prices.

The data that powers the metrics refreshes on a 24-hour cycle. You can look back over the last two years using the dashboard, and the last three years using the API.

### API pagination

Pagination for the Explore metrics operation works differently to pagination for list operations:

- Your query lives in a request body that you POST, rather than as query parameters that you GET.
- It paginates by breakdown value rather than datapoint, so breaking revenue down by product with `per_page` set to `5` returns five products, each with its complete timeseries.

To paginate, you re-send your query request body with the `after` cursor rather than following `meta.pagination.next` as a URL.

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

## Next steps

Find Explore under **Paddle > Analytics > Explore**, or open it directly from a chart on the overview page.

Explore metrics endpoints are available in version `1` of the Paddle API. It's a non-breaking change, meaning it doesn't impact existing integrations.

To get started, see the [metrics API reference](https://developer.paddle.com/api-reference/metrics.md) for the full request and response shapes, or the [Explore guide](https://developer.paddle.com/build/analytics/explore.md) for a walkthrough of both the dashboard and the API.

Querying the API endpoints requires the `metrics.read` [permission](https://developer.paddle.com/api-reference/about/permissions.md).
## Summary of changes

| Name | Type | Change | Entity | Description |
| --- | --- | --- | --- | --- |
| GET /metrics/explore/entities | API operation | added | Metrics | Returns the catalog of queryable entities, with each one's dimensions, measures, allowed aggregations, and permitted intervals. |
| POST /metrics/explore | API operation | added | Metrics | Query a single entity's timeseries data with filters, a breakdown dimension, and pagination. |
| `unknown_entity` | Error | added | Metrics | Returned when the `entity` in your query isn't a recognized queryable entity. |
| `unknown_field` | Error | added | Metrics | Returned when a dimension, measure, or filter field isn't available for the entity you're querying. |
| `invalid_aggregation` | Error | added | Metrics | Returned when the aggregation you requested isn't allowed for that measure field. |
| `invalid_operator` | Error | added | Metrics | Returned when a filter operator isn't valid for the field's type. |
| `max_lookback_exceeded` | Error | added | Metrics | Returned when the date range goes further back than the entity's `max_lookback_days` allows. |
| `too_many_datapoints` | Error | added | Metrics | Returned when `per_page` multiplied by the time buckets in your window exceeds 10,000 datapoints on one page. |
| `invalid_cursor` | Error | added | Metrics | Returned when the `after` cursor is malformed, has expired, or no longer matches the query body you sent. |
| `query_timeout` | Error | added | Metrics | Returned when the query takes too long to complete. Narrow the date range or use a coarser interval. |