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

# POST /metrics/explore

**Run an Explore metrics query**

Runs a query against a single Explore metric and returns timeseries data for it.

Pass the `entity` you want to query, a date range using `from` and `to`, an `interval`, and one or more `measures`. Include `dimensions` to break results down, `filters` to narrow them, and `order_by` to control which results are returned first.

Use the [list Explore metric entities](https://developer.paddle.com/api-reference/metrics/list-explore-metric-entities) operation to see the dimensions, measures, and filters available for a metric.

Results are broken down into segments, where a segment is one combination of the dimensions you grouped by. `per_page` limits the number of segments returned, not the number of datapoints. A page can hold up to 10,000 datapoints, calculated as `per_page` multiplied by the number of time buckets in your range. Requests over this limit return `too_many_datapoints`.

If successful, your response includes the query results in `data`, with a self-describing `fields` block and one entry in `series` for each segment.

**Required permissions:** `metrics.read`

## Query parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `after` | string | optional | Base64-encoded pagination cursor returned in `meta.pagination.next`. Send it back unchanged as the `after` query parameter, along with the same request body, to get the next page. A cursor is only valid for the query that produced it. It expires after an hour, extended each time you use it, up to a maximum of 24 hours. |

## Request body

- `entity`: string (required) — Entity name for the metric to query. One metric per request. An unknown value, including `subscriptions` in sandbox, returns `unknown_entity`.
  - `transactions.completed` — Completed transactions and paid invoices. Measures gross revenue and transaction counts.
  - `adjustments.refunds` — Refunds issued to customers, excluding chargebacks. Measures refunded amounts and counts.
  - `adjustments.chargebacks` — Chargebacks raised against completed transactions, excluding warnings and reversals.
  - `checkouts` — Checkout sessions. Measures checkout conversion and completed checkouts.
  - `subscriptions` — Active subscriptions. Measures monthly recurring revenue and MRR growth. Not available in sandbox.
- `from`: string (required) — RFC 3339 datetime string or `YYYY-MM-DD` date for the start of the range, interpreted at 00:00 UTC. Inclusive. Must be within the metric's `max_lookback_days`, otherwise Paddle returns `max_lookback_exceeded`.
- `to`: string (required) — RFC 3339 datetime string or `YYYY-MM-DD` date for the end of the range, interpreted at 00:00 UTC. Exclusive. Clamped to the current time if in the future.
- `measures`: array (required) — One or more measures to compute. (Items: min 1)
  - `field`: string (required) — Measure field. An unknown field returns `unknown_field`.
  - `agg`: string | null — Aggregation to apply. Must be allowed for this field, otherwise `invalid_aggregation`. Omit for derived measures.
    - `count` — Count of rows.
    - `count_distinct` — Count of distinct values.
    - `sum` — Sum of values.
- `interval`: string — Interval that results are bucketed by. Every query is bucketed, so each entry in `timeseries` carries a `timestamp`. (default: `"month"`)
  - `day` — Daily buckets.
  - `week` — Weekly buckets, starting Monday (UTC).
  - `month` — Monthly buckets, starting on the 1st (UTC).
- `dimensions`: array — Dimensions to group results by. Each combination of values returns as a segment. `timestamp` is implied by `interval`, so don't include it here. (Items: unique; default: `[]`)
- `filters`: array — Filters to narrow results by dimension. Multiple filters are combined, so results must match all of them. (default: `[]`)
  - `field`: string (required) — Dimension field to filter on. An unknown field returns `unknown_field`.
  - `op`: string (required) — Comparison operator. Must be valid for the field, otherwise `invalid_operator`. Only `in` is supported for now.
    - `in` — In the supplied list of values.
  - `value`: array (required) — The array of values to match for the `in` operator.
- `order_by`: array — Ordering. Required when you pass `dimensions`, because it decides which segments land on the page. Omitting it on a query with dimensions returns `invalid_field`.
  - `field`: string (required) — Measure or dimension to order by.
  - `dir`: string (required) — Sort direction.
    - `asc` — Ascending order.
    - `desc` — Descending order.
- `per_page`: integer — Number of segments returned per page, not datapoints. Each segment carries its complete timeseries. Paddle returns the maximum if you request more, so check `meta.pagination.per_page` to see how many came back. A page can hold at most 10,000 datapoints (`per_page` multiplied by the time buckets in your range), otherwise Paddle returns `too_many_datapoints`.

Default: `5`; Maximum: `50`. (Range: 1–50; default: `5`)

### Request example

```json
{
  "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
}
```

## Response (200)

- `data`: object (required) — Result set for an Explore query: a self-describing schema plus one timeseries per segment, with optional totals.
  - `entity`: string (required) — Entity name for the metric that was queried.
    - `transactions.completed` — Completed transactions and paid invoices. Measures gross revenue and transaction counts.
    - `adjustments.refunds` — Refunds issued to customers, excluding chargebacks. Measures refunded amounts and counts.
    - `adjustments.chargebacks` — Chargebacks raised against completed transactions, excluding warnings and reversals.
    - `checkouts` — Checkout sessions. Measures checkout conversion and completed checkouts.
    - `subscriptions` — Active subscriptions. Measures monthly recurring revenue and MRR growth. Not available in sandbox.
  - `interval`: string (required) — Time bucketing applied to the result.
    - `day` — Daily buckets.
    - `week` — Weekly buckets, starting Monday (UTC).
    - `month` — Monthly buckets, starting on the 1st (UTC).
  - `currency_code`: string — Three-letter ISO 4217 currency code for values in the response. Derived from your balance currency. Omitted when the response has no currency values.
    - `USD` — United States Dollar
    - `EUR` — Euro
    - `GBP` — Pound Sterling
    - `JPY` — Japanese Yen
    - `AUD` — Australian Dollar
    - `CAD` — Canadian Dollar
    - `CHF` — Swiss Franc
    - `HKD` — Hong Kong Dollar
    - `SGD` — Singapore Dollar
    - `SEK` — Swedish Krona
    - `ARS` — Argentine Peso
    - `BRL` — Brazilian Real
    - `CLP` — Chilean Peso
    - `CNY` — Chinese Yuan
    - `COP` — Colombian Peso
    - `CZK` — Czech Koruna
    - `DKK` — Danish Krone
    - `HUF` — Hungarian Forint
    - `ILS` — Israeli Shekel
    - `INR` — Indian Rupee
    - `KRW` — South Korean Won
    - `MXN` — Mexican Peso
    - `NOK` — Norwegian Krone
    - `NZD` — New Zealand Dollar
    - `PEN` — Peruvian Sol
    - `PLN` — Polish Zloty
    - `RUB` — Russian Ruble
    - `THB` — Thai Baht
    - `TRY` — Turkish Lira
    - `TWD` — New Taiwan Dollar
    - `UAH` — Ukrainian Hryvnia
    - `VND` — Vietnamese Dong
    - `ZAR` — South African Rand
  - `starts_at`: string (date-time) (required) — RFC 3339 datetime string of the start of the queried range, in UTC. Matches the `from` in your request.
  - `ends_at`: string (date-time) (required) — RFC 3339 datetime string of the end of the queried range, in UTC. Matches the `to` in your request, clamped to the current time if it's in the future.
  - `updated_at`: string (date-time) (required) — RFC 3339 datetime string of when the data behind this metric was last refreshed, in UTC. Set automatically by Paddle.
  - `fields`: object (required) — Describes the dimension and measure fields in this result.
    - `dimensions`: array (required) — One entry per requested dimension.
      - `name`: string (required) — Dimension identifier. Matches the keys in each series' `dimensions` map.
      - `type`: string (required) — Value type for the dimension.
        - `string` — String value, such as an identifier or categorical value, e.g. a product ID or country code.
        - `integer` — Integer value.
        - `decimal` — Non-integer numeric value, such as a rate (returned as a string).
        - `currency` — Monetary value, denominated in the response `currency_code` (returned as a string).
    - `measures`: array (required) — One entry per requested measure.
      - `name`: string (required) — Generated measure name: `{agg}_{field}` (e.g. `sum_gross_revenue`), or just `{field}` for derived measures (e.g. `mrr`, `checkout_conversion`). Matches the keys in each datapoint's `measures` map.
      - `type`: string (required) — Value type for the measure.
        - `string` — String value, such as an identifier or categorical value, e.g. a product ID or country code.
        - `integer` — Integer value.
        - `decimal` — Non-integer numeric value, such as a rate (returned as a string).
        - `currency` — Monetary value, denominated in the response `currency_code` (returned as a string).
      - `field`: string — Measure field this column was computed from. Omitted for derived measures.
      - `agg`: string — Aggregation applied. Omitted for derived measures (`aggs: null` in the entity's metadata).
        - `count` — Count of rows.
        - `count_distinct` — Count of distinct values.
        - `sum` — Sum of values.
  - `series`: array (required) — One entry per segment (dimension combination), each carrying its full time series. Capped by `per_page`.
    - `dimensions`: object (required) — Dimension values for this segment, keyed by a subset of the requested dimensions. Empty for a result with no breakdown applied.
    - `timeseries`: array (required) — Time series for this segment. One entry per time bucket, ordered chronologically.
      - `timestamp`: string (required) — RFC 3339 datetime string or `YYYY-MM-DD` date for the start of this time bucket, in UTC. The Monday for weekly intervals, and the 1st for monthly intervals.
      - `measures`: object (required) — Measure values for this bucket, keyed by the measure `name` from `fields.measures`. Numeric values are strings to preserve precision.
- `meta`: object (required) — Information about this response.
  - `request_id`: string (required) — Unique ID for the request relating to this response. Provide this when contacting Paddle support about a specific request.
  - `pagination`: object (required) — Pagination state for the list of segments. Because this operation paginates with `POST`, `next` is a URL carrying an `after` query parameter. Send the same request body to it to get the next page.
    - `per_page`: integer (required) — Number of series per page for this response. May differ from the number requested if the requested number is greater than the maximum.
    - `next`: string (uri) (required) — URL for the next page, including the `after` query parameter. Always returned, even when `has_more` is `false`. Re-POST the unchanged query body to this URL. Use `has_more` to decide whether another page exists.
    - `has_more`: boolean (required) — Whether this response has another page.
    - `estimated_total`: integer (required) — Total number of series for this response. Returns the exact count, even when the query's result set was truncated by its 1,000,000 row cap.

### Response example

```json
{
  "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-01",
            "measures": {
              "sum_gross_revenue": "410500"
            }
          },
          {
            "timestamp": "2026-06-01",
            "measures": {
              "sum_gross_revenue": "455200"
            }
          },
          {
            "timestamp": "2026-07-01",
            "measures": {
              "sum_gross_revenue": "482000"
            }
          }
        ]
      },
      {
        "dimensions": {
          "product": "pro_01gsz4t5hdjse780zja8vvr7jg"
        },
        "timeseries": [
          {
            "timestamp": "2026-05-01",
            "measures": {
              "sum_gross_revenue": "298400"
            }
          },
          {
            "timestamp": "2026-06-01",
            "measures": {
              "sum_gross_revenue": "301250"
            }
          },
          {
            "timestamp": "2026-07-01",
            "measures": {
              "sum_gross_revenue": "355900"
            }
          }
        ]
      }
    ]
  },
  "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
    }
  }
}
```