PApaddlehq
Metrics

Run an Explore metrics query

Changed on

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.

post/metrics/explore

Request

  • Base URL
    https://sandbox-api.paddle.com
  • Auth
    HTTP bearer

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.

Pagination cursor from the previous response's meta.pagination.next. Omit for the first page. Send the same request body with it: a cursor that doesn't match the body you send is rejected with invalid_cursor.

Request body

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.

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

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

interval'day' | 'week' | 'month'

Interval that a metric query is bucketed by. Buckets are UTC, and weeks start on Monday.

dimensionsstring[]

Dimensions to group results by. Each combination of values returns as a segment. timestamp is implied by interval, so don't include it here.

per_pageinteger

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.

Example request

{
  "from": "2026-01-01",
  "to": "2026-04-01",
  "measures": [
    {
      "field": "gross_revenue"
    }
  ],
  "filters": [
    {
      "field": "country"
    }
  ],
  "order_by": [
    {
      "field": "gross_revenue"
    }
  ]
}

Response

A successful Explore query response: the result set plus pagination metadata.

Example response

{
  "data": {
    "starts_at": "2024-10-12T07:20:50.52Z",
    "ends_at": "2024-10-12T07:20:50.52Z",
    "updated_at": "2024-10-12T07:20:50.52Z",
    "fields": {
      "dimensions": [
        {
          "name": "country"
        }
      ],
      "measures": [
        {
          "name": "sum_gross_revenue",
          "field": "gross_revenue"
        }
      ]
    },
    "series": [
      {
        "timeseries": [
          {
            "timestamp": "2026-02-01"
          }
        ]
      }
    ]
  },
  "meta": {
    "request_id": "b15ec92e-8688-40d4-a04d-f44cbec93355",
    "pagination": {
      "estimated_total": 42
    }
  }
}

Changes