Skip to main content
API docs by Redocly

Developer API (2.0.0)

Download OpenAPI specification:Download

Charts & Metrics

Operations about chart metrics.

Get overview metrics for a project

This endpoint requires the following permission(s): charts_metrics:overview:read. This endpoint belongs to the Charts & Metrics domain, which has a default rate limit of 25 requests per minute.

Authorizations:
BearerAuth
path Parameters
project_id
required
string <= 255 characters
Example: proj1ab2c3d4

ID of the project

query Parameters
currency
string
Enum: "USD" "EUR" "GBP" "AUD" "CAD" "JPY" "BRL" "KRW" "CNY" "MXN" … 4 more
Example: currency=EUR

The currency to return metrics data in

Responses

Response samples

Content type
application/json
{
  • "object": "overview_metrics",
  • "metrics": [
    ],
  • "currency": "EUR"
}

Get revenue for a project

Returns the total revenue for the project across all of its apps for the given inclusive date range [start_date, end_date]. The value is expressed in the project's primary currency unless currency is provided.

Use revenue_type to choose which revenue definition the value represents: gross revenue (default), revenue_net_of_taxes, or proceeds (net of both taxes and store commission — the amount the developer keeps).

This endpoint is backed by the same realtime (v3) revenue chart that powers the dashboard. It is intended for cases where an app needs an authoritative revenue total without inferring it from the transaction list.

Note that the most recent day in the range may be partial if it includes today, since transactions for today are still arriving. This endpoint requires the following permission(s): charts_metrics:overview:read. This endpoint belongs to the Charts & Metrics domain, which has a default rate limit of 25 requests per minute.

Authorizations:
BearerAuth
path Parameters
project_id
required
string <= 255 characters
Example: proj1ab2c3d4

ID of the project

query Parameters
start_date
required
string <date>
Example: start_date=2024-01-01

Start date for the data range (ISO 8601 format)

end_date
required
string <date>
Example: end_date=2024-12-31

End date for the data range (ISO 8601 format)

currency
string
Enum: "USD" "EUR" "GBP" "AUD" "CAD" "JPY" "BRL" "KRW" "CNY" "MXN" … 4 more
Example: currency=EUR

The currency to return metrics data in

revenue_type
string
Default: "revenue"
Enum: "revenue" "revenue_net_of_taxes" "proceeds"
Example: revenue_type=proceeds

Which revenue definition to return as the metric value:

  • revenue: gross revenue.
  • revenue_net_of_taxes: revenue with taxes subtracted.
  • proceeds: revenue net of both taxes and store commission (the amount the developer keeps).

Responses

Response samples

Content type
application/json
{
  • "object": "revenue_metric",
  • "start_date": "2026-01-01",
  • "end_date": "2026-01-31",
  • "currency": "USD",
  • "value": 12345.67,
  • "revenue_type": "proceeds"
}

Get chart data

Returns time-series data for a specific chart.

Response Structure

The response includes:

  • Chart metadata (category, display_name, description)
  • Time boundaries (start_date, end_date, last_computed_at)
  • Data values (array of data points)
  • Summary statistics
  • Segment information (when segmented)

Chart Types

Different charts may return data in slightly different formats:

  • Standard charts: values as arrays of data points with timestamps
  • Segmented charts: include segment information in the response
  • Cohort charts: see below

Cohort charts

Cohort-shaped charts (cohort_explorer, prediction_explorer, subscription_retention, ...) return values as {cohort, period, value} objects, where period is the index into the periods array, not a month number. Two things follow from that:

  • periods[0] describes the cohort size — a count of customers or subscriptions, with unit #. It is not the measure at month 0. On cohort_explorer its display_name is named after the cohorting_date selector (e.g. New customers).
  • The measure starts at period: 1, labelled by periods[1].display_name (typically Month 0). So Month N is at period: N + 1.

Always read periods[period].display_name, .unit and .scale to interpret a data point rather than assuming period is the month number. On non-realtime charts (realtime=false) the same metadata is returned in segments instead of periods.

Filtering and Segmentation

Use the /charts/{chart_name}/options endpoint to discover available filters and segments for a specific chart before making requests.

Segments and filters vary per chart and are separate lists — a dimension can be available as a filter but not as a segment. Requesting an unsupported segment or filter (or segmenting/filtering a chart that does not allow it) returns a 400 parameter_error that lists the supported segments. Check get-chart-options-schema first when unsure.

Filter parameters vary by chart and can be passed as additional query parameters.

Aggregation

Use aggregate to request summary-only output for supported charts. When aggregate is provided, values is returned as an empty array and summary includes only the requested aggregate operations.

Incomplete data For the most recent periods, data may be flagged as incomplete, and may not be appropriate to use for analysis. This endpoint requires the following permission(s): charts_metrics:charts:read. This endpoint belongs to the Charts & Metrics domain, which has a default rate limit of 25 requests per minute.

Authorizations:
BearerAuth
path Parameters
project_id
required
string <= 255 characters
Example: proj1ab2c3d4

ID of the project

chart_name
required
string <= 255 characters
Enum: "actives" "actives_movement" "actives_new" "arr" "churn" "cohort_explorer" "conversion_to_paying" "customers_new" "initial_conversion" "ltv_per_customer" … 22 more
Example: revenue

Name of the chart to retrieve:

  • actives: Active (paying) subscriptions
  • actives_movement: Period-over-period delta of active (paying) subscriptions
  • actives_new: New paying subscriptions, including trial conversions, resubscriptions, and product changes
  • arr: Annual recurring revenue
  • churn: Churn rate: active and expired subscriptions per period
  • cohort_explorer: allows measuring the performance of various cohort definitions over time for revenue, retained subscriptions, subscriptions that are still set to renew (not cancelled), and cohort LTV
  • conversion_to_paying: Conversion of new customers to paying
  • customers_new: Newly seen customers
  • initial_conversion: Initial conversion of new customers to paying within fixed windows (0, 3, 7, 14, 30 days, and unbounded)
  • ltv_per_customer: Realized LTV per customer, also known as ARPU, cohorted by first seen date
  • ltv_per_paying_customer: Realized LTV per paying customer, also known as ARPPU, cohorted by first seen date
  • mrr: Monthly recurring revenue
  • mrr_movement: Period-over-period delta of monthly recurring revenue
  • prediction_explorer: similar to cohort_explorer but including future predictions
  • refund_rate: transactions per period, refunds, refund rate
  • revenue: revenue (gross, net of taxes, or proceeds net of taxes and commissions) and number of transactions (subscriptions and non-subscriptions) per period
  • subscription_retention: Per-period retention of paying subscriptions by duration
  • subscription_status: Break down paying subscriptions, trials, MRR, ARR, or revenue by whether the subscription is set to renew, cancelled, or in billing recovery
  • trials: Active trials
  • trials_movement: Movement of active trials
  • trials_new: New trials
  • customers_active: Customers seen during the period (also known as DAU/MAU/WAU/etc.)
  • trial_conversion_rate: Number of trials started in a period and ratio of them converting to paying
  • non-subscription_purchases: Number of non-subscription purchases per period
  • ad_revenue: Estimated ad revenue per period (realtime only)
  • ad_impressions: Number of ad impressions per period (realtime only)
  • ad_clicks: Number of ad clicks per period (realtime only)
  • ad_monetized_customers: Customers who saw at least one monetized ad during the period, also known as daily ad-monetized users (realtime only)
  • ad_arpdau: Average ad revenue per daily ad-monetized customer (realtime only)
  • ad_rpm: Effective cost per mille (eCPM): ad revenue per thousand impressions (realtime only)
  • ad_fill_rate: Ratio of ad requests that were filled with an ad (realtime only)
  • ad_ctr: Ad click-through rate: clicks over impressions (realtime only)

Charts marked as realtime only are served exclusively by Charts v3 and require realtime=true (the default).

query Parameters
realtime
boolean
Default: true

Whether to request real-time (v3) charts. Defaults to true. Set to false to request the v2 charts.

filters
string
Example: filters=[{"name":"country","values":["US","UK"]}]

JSON array of chart filters. Each filter is a ChartFilter object.

selectors
string
Example: selectors={"conversion_timeframe":"7_days","revenue_type":"proceeds"}

JSON object of chart selectors.

aggregate
Array of strings non-empty unique
Items Enum: "average" "total"
Example: aggregate=average,total

Comma-separated aggregate operations to return in summary without raw values.

currency
string
Enum: "USD" "EUR" "GBP" "AUD" "CAD" "JPY" "BRL" "KRW" "CNY" "MXN" … 4 more
Example: currency=EUR

The currency to return metrics data in

resolution
string
Example: resolution=0

Time resolution for the chart data. Use the chart options endpoint to discover available resolutions and their IDs.

start_date
string <date>
Example: start_date=2024-01-01

Start date for the data range (ISO 8601 format)

end_date
string <date>
Example: end_date=2024-12-31

End date for the data range (ISO 8601 format)

expand_periods
boolean
Default: false

Whether to expand the date range so the first period is complete (e.g. snap a weekly range back to the start of the week). Defaults to false, which only includes data from the exact start_date provided. Period labels are always aligned to period boundaries: with expand_periods=false and a mid-period start_date, the first period only aggregates data from start_date onwards and is marked as incomplete. Exception: charts of point-in-time (stock) metrics, such as active subscriptions or MRR, ignore this parameter entirely. Their values are snapshots measured exactly at each period boundary, so the first data point is always measured at the start of the period containing start_date (which can fall before start_date) and is not marked as incomplete, since a snapshot cannot be partial.

segment
string
Example: segment=country

Segment the data by this dimension. Must be one of the segments returned by the chart options schema endpoint for this chart; segments vary per chart, and unsupported segments return a 400 parameter_error listing the supported ones.

limit_num_segments
integer >= 1
Example: limit_num_segments=10

If set, limits the number of segments returned to the top N by value. All remaining segments are aggregated into an "Other" segment. Only applies when a segment is specified.

include_annotations
boolean
Default: false
Example: include_annotations=true

When true, includes chart annotations for the project in the response, filtered to the chart's date window.

Responses

Response samples

Content type
application/json
{
  • "object": "chart_data",
  • "category": "revenue",
  • "display_type": "line",
  • "display_name": "Revenue",
  • "description": "string",
  • "documentation_link": "string",
  • "last_computed_at": 0,
  • "start_date": 0,
  • "end_date": 0,
  • "yaxis_currency": "USD",
  • "filtering_allowed": true,
  • "segmenting_allowed": true,
  • "resolution": "day",
  • "values": [
    ],
  • "summary": { },
  • "yaxis": "$",
  • "segments": [
    ],
  • "segments_limit": 0,
  • "periods": [
    ],
  • "measures": [
    ],
  • "user_selectors": {
    },
  • "unsupported_params": {
    },
  • "annotations": [
    ]
}

Get available options for a chart

Returns configuration options for a specific chart.

Use this endpoint to discover:

  • Resolutions: Available time granularities (day, week, month, etc.)
  • Segments: Dimensions you can segment the data by (country, store, product, etc.)
  • Filters: Available filters and their possible values

The options returned are specific to the chart and may vary based on your project's data and configuration.

Usage

Call this endpoint before requesting chart data to:

  1. Build dynamic filter UIs
  2. Validate parameters before making chart data requests
  3. Discover available dimensions for analysis . This endpoint requires the following permission(s): charts_metrics:charts:read. This endpoint belongs to the Charts & Metrics domain, which has a default rate limit of 25 requests per minute.
Authorizations:
BearerAuth
path Parameters
project_id
required
string <= 255 characters
Example: proj1ab2c3d4

ID of the project

chart_name
required
string <= 255 characters
Enum: "actives" "actives_movement" "actives_new" "arr" "churn" "cohort_explorer" "conversion_to_paying" "customers_new" "initial_conversion" "ltv_per_customer" … 22 more
Example: revenue

Name of the chart to retrieve:

  • actives: Active (paying) subscriptions
  • actives_movement: Period-over-period delta of active (paying) subscriptions
  • actives_new: New paying subscriptions, including trial conversions, resubscriptions, and product changes
  • arr: Annual recurring revenue
  • churn: Churn rate: active and expired subscriptions per period
  • cohort_explorer: allows measuring the performance of various cohort definitions over time for revenue, retained subscriptions, subscriptions that are still set to renew (not cancelled), and cohort LTV
  • conversion_to_paying: Conversion of new customers to paying
  • customers_new: Newly seen customers
  • initial_conversion: Initial conversion of new customers to paying within fixed windows (0, 3, 7, 14, 30 days, and unbounded)
  • ltv_per_customer: Realized LTV per customer, also known as ARPU, cohorted by first seen date
  • ltv_per_paying_customer: Realized LTV per paying customer, also known as ARPPU, cohorted by first seen date
  • mrr: Monthly recurring revenue
  • mrr_movement: Period-over-period delta of monthly recurring revenue
  • prediction_explorer: similar to cohort_explorer but including future predictions
  • refund_rate: transactions per period, refunds, refund rate
  • revenue: revenue (gross, net of taxes, or proceeds net of taxes and commissions) and number of transactions (subscriptions and non-subscriptions) per period
  • subscription_retention: Per-period retention of paying subscriptions by duration
  • subscription_status: Break down paying subscriptions, trials, MRR, ARR, or revenue by whether the subscription is set to renew, cancelled, or in billing recovery
  • trials: Active trials
  • trials_movement: Movement of active trials
  • trials_new: New trials
  • customers_active: Customers seen during the period (also known as DAU/MAU/WAU/etc.)
  • trial_conversion_rate: Number of trials started in a period and ratio of them converting to paying
  • non-subscription_purchases: Number of non-subscription purchases per period
  • ad_revenue: Estimated ad revenue per period (realtime only)
  • ad_impressions: Number of ad impressions per period (realtime only)
  • ad_clicks: Number of ad clicks per period (realtime only)
  • ad_monetized_customers: Customers who saw at least one monetized ad during the period, also known as daily ad-monetized users (realtime only)
  • ad_arpdau: Average ad revenue per daily ad-monetized customer (realtime only)
  • ad_rpm: Effective cost per mille (eCPM): ad revenue per thousand impressions (realtime only)
  • ad_fill_rate: Ratio of ad requests that were filled with an ad (realtime only)
  • ad_ctr: Ad click-through rate: clicks over impressions (realtime only)

Charts marked as realtime only are served exclusively by Charts v3 and require realtime=true (the default).

query Parameters
realtime
boolean
Default: true

Whether to request real-time (v3) charts. Defaults to true. Set to false to request the v2 charts.

Responses

Response samples

Content type
application/json
{
  • "object": "chart_options",
  • "resolutions": [
    ],
  • "segments": [
    ],
  • "filters": [
    ],
  • "user_selectors": {
    }
}