--- title: "Run an Explore metrics query" method: POST path: "/metrics/explore" tags: ["Metrics"] --- # Run an Explore metrics query `POST /metrics/explore` ## Request - Base URL: `https://sandbox-api.paddle.com` - URL: `https://sandbox-api.paddle.com/metrics/explore` - Auth: HTTP bearer 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. ## Query parameters - `after` string: 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 - MetricsExploreRequest: A JSON query against a single metric entity. Results are automatically scoped to your account. - `entity` 'transactions.completed' | 'adjustments.refunds' | 'adjustments.chargebacks' | 'checkouts' | 'subscriptions', required: Entity name for a queryable Explore metric. Pass it as the `entity` when you query. `subscriptions` isn't available in sandbox, where it's treated as `unknown_entity`. - `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` MetricsExploreMeasure[], required: One or more measures to compute. - `field` string, required: Measure field. An unknown field returns `unknown_field`. - `agg` 'count' | 'count_distinct' | 'sum': Aggregation applied to a measure field. Each entity defines which aggregations are allowed for each field. An aggregation that isn't allowed returns `invalid_aggregation`. - `interval` 'day' | 'week' | 'month': Interval that a metric query is bucketed by. Buckets are UTC, and weeks start on Monday. - `dimensions` string[]: Dimensions to group results by. Each combination of values returns as a segment. `timestamp` is implied by `interval`, so don't include it here. - `filters` MetricsExploreFilter[]: Filters to narrow results by dimension. Multiple filters are combined, so results must match all of them. - `field` string, required: Dimension field to filter on. An unknown field returns `unknown_field`. - `op` 'in', required: Filter operator for a metric query. Each entity lists the operators valid for each dimension, and an operator that isn't valid for a field returns `invalid_operator`. Only `in` is supported. - `value` string[], required: The array of values to match for the `in` operator. - `order_by` MetricsExploreOrderBy[]: 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` 'asc' | 'desc', required: Sort direction for a metric ordering. - `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`. ## Response `200` A successful Explore query response: the result set plus pagination metadata. - MetricsExploreResponse: A successful Explore query response: the result set plus pagination metadata. - `data` MetricsExploreData, required: Result set for an Explore query: a self-describing schema plus one timeseries per segment, with optional totals. - `entity` 'transactions.completed' | 'adjustments.refunds' | 'adjustments.chargebacks' | 'checkouts' | 'subscriptions', required: Entity name for a queryable Explore metric. Pass it as the `entity` when you query. `subscriptions` isn't available in sandbox, where it's treated as `unknown_entity`. - `interval` 'day' | 'week' | 'month', required: Interval that a metric query is bucketed by. Buckets are UTC, and weeks start on Monday. - `currency_code` 'USD' | 'EUR' | 'GBP' | 'JPY' | 'AUD' | 'CAD' | 'CHF' | 'HKD' | 'SGD' | 'SEK' | 'ARS' | 'BRL' | 'CLP' | 'CNY' | 'COP' | 'CZK' | 'DKK' | 'HUF' | 'ILS' | 'INR' | 'KRW' | 'MXN' | 'NOK' | 'NZD' | 'PEN' | 'PLN' | 'RUB' | 'THB' | 'TRY' | 'TWD' | 'UAH' | 'VND' | 'ZAR': Supported three-letter ISO 4217 currency code. - `starts_at` string, date-time, required: RFC 3339 datetime string. - `ends_at` string, date-time, required: RFC 3339 datetime string. - `updated_at` string, date-time, required: RFC 3339 datetime string. - `fields` MetricsExploreFields, required: Describes the dimension and measure fields in this result, so you can format and parse values without knowing the entity in advance. - `dimensions` MetricsExploreFieldDimension[], required: One entry per requested dimension. - `name` string, required: Dimension identifier. Matches the keys in each series' `dimensions` map. - `type` 'string' | 'integer' | 'decimal' | 'currency', required: Value type of a metrics field, whether a dimension or a measure. Numeric values are returned as strings to preserve precision. - `measures` MetricsExploreFieldMeasure[], 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' | 'integer' | 'decimal' | 'currency', required: Value type of a metrics field, whether a dimension or a measure. Numeric values are returned as strings to preserve precision. - `field` string: Measure field this column was computed from. Omitted for derived measures. - `agg` 'count' | 'count_distinct' | 'sum': Aggregation applied to a measure field. Each entity defines which aggregations are allowed for each field. An aggregation that isn't allowed returns `invalid_aggregation`. - `series` MetricsExploreSeries[], 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` MetricsExploreDataPoint[], 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` MetricsExplorePaginatedMeta, 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` MetricsExplorePagination, 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. ## Other responses - `default`: An unexpected error response. ## Changes - **2026-10-19** (v1) `4f35a8c6ea4d`: 1 info - endpoint added [Operation history](https://skmtc.dev/paddlehq/apis/paddle-api/changes/metrics/explore/post.md) --- [API](https://skmtc.dev/paddlehq/apis/paddle-api.md) - [All operations](https://skmtc.dev/paddlehq/apis/paddle-api/llms.txt) - [OpenAPI document](https://skmtc.dev/paddlehq/apis/paddle-api/revisions/bbc0c72039c8?raw)