For AI agents and LLMs: a structured documentation index is available at /llms.txt. Every page has a Markdown sibling — append .md to any URL.

Skip to content
Paddle Docs home

Run an Explore metrics query

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

POST /metrics/explore

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 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.

Requires metrics.read permission.

Query parameters

afterstring
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

entitystringrequired
Entity name for the metric to query. One metric per request. An unknown value, including subscriptions in sandbox, returns unknown_entity.
Values
  • 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.
fromstringrequired
Example: 2026-01-01
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.
tostringrequired
Example: 2026-04-01
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.
measuresarrayrequired
One or more measures to compute.
Items: min 1
fieldstringrequired
Example: gross_revenue
Measure field. An unknown field returns unknown_field.
aggstring | null
Aggregation to apply. Must be allowed for this field, otherwise invalid_aggregation. Omit for derived measures.
Values
  • count
    Count of rows.
  • count_distinct
    Count of distinct values.
  • sum
    Sum of values.
intervalstring
Default: month
Interval that results are bucketed by. Every query is bucketed, so each entry in timeseries carries a timestamp.
Values
  • day
    Daily buckets.
  • week
    Weekly buckets, starting Monday (UTC).
  • month
    Monthly buckets, starting on the 1st (UTC).
dimensionsarray
Default:
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
filtersarray
Default:
Filters to narrow results by dimension. Multiple filters are combined, so results must match all of them.
fieldstringrequired
Example: country
Dimension field to filter on. An unknown field returns unknown_field.
opstringrequired
Comparison operator. Must be valid for the field, otherwise invalid_operator. Only in is supported for now.
Values
  • in
    In the supplied list of values.
valuearrayrequired
The array of values to match for the in operator.
order_byarray
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.
fieldstringrequired
Example: gross_revenue
Measure or dimension to order by.
dirstringrequired
Sort direction.
Values
  • asc
    Ascending order.
  • desc
    Descending order.
per_pageinteger
Default: 5

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

Response (200)

dataobjectrequired
Result set for an Explore query: a self-describing schema plus one timeseries per segment, with optional totals.
entitystringrequired
Entity name for the metric that was queried.
Values
  • 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.
intervalstringrequired
Time bucketing applied to the result.
Values
  • day
    Daily buckets.
  • week
    Weekly buckets, starting Monday (UTC).
  • month
    Monthly buckets, starting on the 1st (UTC).
currency_codestring
Three-letter ISO 4217 currency code for values in the response. Derived from your balance currency. Omitted when the response has no currency values.
Values
  • USD
    United States Dollar
  • EUR
    Euro
  • GBP
    Pound Sterling
  • JPY
    Japanese Yen
  • AUD
    Australian Dollar
+ Show all values
  • 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_atstring (date-time)required
Example: 2024-10-12T07:20:50.52Z
RFC 3339 datetime string of the start of the queried range, in UTC. Matches the from in your request.
ends_atstring (date-time)required
Example: 2024-10-12T07:20:50.52Z
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_atstring (date-time)required
Example: 2024-10-12T07:20:50.52Z
RFC 3339 datetime string of when the data behind this metric was last refreshed, in UTC. Set automatically by Paddle.
fieldsobjectrequired
Describes the dimension and measure fields in this result.
dimensionsarrayrequired
One entry per requested dimension.
namestringrequired
Example: country
Dimension identifier. Matches the keys in each series' dimensions map.
typestringrequired
Value type for the dimension.
Values
  • 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).
measuresarrayrequired
One entry per requested measure.
namestringrequired
Example: sum_gross_revenue
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.
typestringrequired
Value type for the measure.
Values
  • 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).
fieldstring
Example: gross_revenue
Measure field this column was computed from. Omitted for derived measures.
aggstring
Aggregation applied. Omitted for derived measures (aggs: null in the entity's metadata).
Values
  • count
    Count of rows.
  • count_distinct
    Count of distinct values.
  • sum
    Sum of values.
seriesarrayrequired
One entry per segment (dimension combination), each carrying its full time series. Capped by per_page.
dimensionsobjectrequired
Dimension values for this segment, keyed by a subset of the requested dimensions. Empty for a result with no breakdown applied.
timeseriesarrayrequired
Time series for this segment. One entry per time bucket, ordered chronologically.
timestampstringrequired
Example: 2026-02-01
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.
measuresobjectrequired
Measure values for this bucket, keyed by the measure name from fields.measures. Numeric values are strings to preserve precision.
metaobjectrequired
Information about this response.
request_idstringrequired
Example: b15ec92e-8688-40d4-a04d-f44cbec93355
Unique ID for the request relating to this response. Provide this when contacting Paddle support about a specific request.
paginationobjectrequired
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_pageintegerrequired
Number of series per page for this response. May differ from the number requested if the requested number is greater than the maximum.
nextstring (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_morebooleanrequired
Whether this response has another page.
estimated_totalintegerrequired
Example: 42
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.
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
}
Response
{
  "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
    }
  }
}

Was this page helpful?