---
title: "Charts & Metrics"
permalink: "/docs/api-v2/charts-and-metrics"
original_source: "openapi-spec/api-v2.yaml"
---

> **AI agents:** This is the Markdown version of a RevenueCat documentation page. For the complete documentation index, see [llms.txt](https://www.revenuecat.com/docs/llms.txt).

# Charts & Metrics

## Charts & Metrics

Operations about chart metrics.

### Get overview metrics for a project

`GET /projects/{project_id}/metrics/overview`

Operation ID: `get-overview-metrics`

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

**Parameters**

| Name | In | Required | Description |
| --- | --- | --- | --- |
| `project_id` | path | yes | ID of the project |
| `currency` | query | no | The currency to return metrics data in |

**Responses**

- `200` — Success
- `400` — Bad request
- `401` — Unauthorized
- `403` — Access denied
- `404` — Not found
- `423` — Locked
- `429` — The request could not be completed because the rate limiting domain for this endpoint is currently at its limit for this project.
- `500` — Internal server error
- `503` — Internal server error

**Response `200` body**

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `object` | string | yes | String representing the object's type. Objects of the same type share the same value. One of: `overview_metrics` |
| `metrics` | array of OverviewMetric | yes | Details about each overview metric. |
| `currency` | string | yes | The currency that monetary metric values are expressed in. Defaults to USD. When the request is authenticated with a developer JWT/OAuth token and no `currency` query parameter is provided, this reflects the developer's saved dashboard display currency. One of: `USD`, `EUR`, `GBP`, `AUD`, `CAD`, `JPY`, `BRL`, `KRW`, `CNY`, `MXN`, `SEK`, `PLN`, `NZD`, `CHF` |

<details><summary><code>metrics</code></summary>

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `object` | string | yes | String representing the object's type. Objects of the same type share the same value. One of: `overview_metric` |
| `id` | string | yes | Id of the overview metric |
| `name` | string | yes | Display name of the overview metric |
| `description` | string | yes | Description of the overview metric |
| `unit` | string | yes | Unit of the overview metric |
| `period` | string | yes | Length of time during which metric data is collected in ISO 8601 format. Zero period means metric data was collected now One of: `P0D`, `P28D` |
| `value` | number | yes | Value of the overview metric |
| `last_updated_at` | integer | yes | Last time the overview metric was updated in ms since epoch |
| `last_updated_at_iso8601` | string | yes | Last time the overview metric was updated datetime in ISO 8601 format |

</details>
### Get revenue for a project

`GET /projects/{project_id}/metrics/revenue`

Operation ID: `get-revenue-metric`

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): <code>charts_metrics:overview:read</code>. This endpoint belongs to the <strong>Charts & Metrics</strong> domain, which has a default rate limit of <strong>25 requests per minute</strong>.

**Parameters**

| Name | In | Required | Description |
| --- | --- | --- | --- |
| `project_id` | path | yes | ID of the project |
| `start_date` | query | yes | Start date for the data range (ISO 8601 format) |
| `end_date` | query | yes | End date for the data range (ISO 8601 format) |
| `currency` | query | no | The currency to return metrics data in |
| `revenue_type` | query | no | 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**

- `200` — Success
- `400` — Bad request
- `401` — Unauthorized
- `403` — Access denied
- `404` — Not found
- `423` — Locked
- `429` — The request could not be completed because the rate limiting domain for this endpoint is currently at its limit for this project.
- `500` — Internal server error
- `503` — Internal server error

**Response `200` body**

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `object` | string | yes | String representing the object's type. Objects of the same type share the same value. One of: `revenue_metric` |
| `start_date` | string | yes | Start date of the revenue range, inclusive (ISO 8601 format). |
| `end_date` | string | yes | End date of the revenue range, inclusive (ISO 8601 format). |
| `currency` | string | yes | The ISO 4217 currency code that the revenue value is expressed in. |
| `value` | number | yes | Revenue for the date range, expressed in `currency`, for the revenue definition selected by the `revenue_type` request parameter. Two-decimal precision. |
| `revenue_type` | string | yes | The revenue definition that `value` represents: `revenue` (gross), `revenue_net_of_taxes`, or `proceeds` (net of both taxes and store commission). Matches the `revenue_type` request parameter. One of: `revenue`, `revenue_net_of_taxes`, `proceeds` |

### Get chart data

`GET /projects/{project_id}/charts/{chart_name}`

Operation ID: `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): <code>charts_metrics:charts:read</code>. This endpoint belongs to the <strong>Charts & Metrics</strong> domain, which has a default rate limit of <strong>25 requests per minute</strong>.

**Parameters**

| Name | In | Required | Description |
| --- | --- | --- | --- |
| `project_id` | path | yes | ID of the project |
| `chart_name` | path | yes | 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). |
| `realtime` | query | no | Whether to request real-time (v3) charts. Defaults to true. Set to false to request the v2 charts. |
| `filters` | query | no | JSON array of chart filters. Each filter is a ChartFilter object. |
| `selectors` | query | no | JSON object of chart selectors. |
| `aggregate` | query | no | Comma-separated aggregate operations to return in `summary` without raw `values`. |
| `currency` | query | no | The currency to return metrics data in |
| `resolution` | query | no | Time resolution for the chart data. Use the chart options endpoint to discover available resolutions and their IDs. |
| `start_date` | query | no | Start date for the data range (ISO 8601 format) |
| `end_date` | query | no | End date for the data range (ISO 8601 format) |
| `expand_periods` | query | no | 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` | query | no | 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` | query | no | 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` | query | no | When true, includes chart annotations for the project in the response, filtered to the chart's date window. |

**Responses**

- `200` — Chart data retrieved successfully
- `400` — Bad request
- `401` — Unauthorized
- `403` — Access denied
- `404` — Not found
- `423` — Locked
- `429` — The request could not be completed because the rate limiting domain for this endpoint is currently at its limit for this project.
- `500` — Internal server error
- `503` — Internal server error

**Response `200` body**

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `object` | string | yes | String representing the object's type. Objects of the same type share the same value. One of: `chart_data` |
| `category` | string | yes | Category the chart belongs to |
| `display_type` | string | yes | Type of chart visualization |
| `display_name` | string | yes | Human-readable name of the chart |
| `description` | string | yes | Description of what the chart shows |
| `documentation_link` | string | no | Link to documentation for this chart |
| `last_computed_at` | integer | no | Timestamp when the chart data was last computed (ms since epoch) |
| `start_date` | integer | no | Start date of the data range (ms since epoch) |
| `end_date` | integer | no | End date of the data range (ms since epoch) |
| `yaxis_currency` | string | no | Currency used for monetary values |
| `filtering_allowed` | boolean | no | Whether filtering is allowed for this chart |
| `segmenting_allowed` | boolean | no | Whether segmentation is allowed for this chart |
| `resolution` | string | yes | Time resolution of the data points One of: `day`, `week`, `month`, `quarter`, `year` |
| `values` | array of object | yes | Chart data points. Structure varies by chart type - can be arrays of numbers or objects with timestamps and values. Returned as an empty array when aggregate operations are requested. Cohort charts (`cohort_explorer`, `prediction_explorer`, `subscription_retention`, ...) return objects shaped `{cohort, period, value}`, optionally with `confidence`, `scale` and `incomplete`. `period` is the index into the `periods` array, not a month number: `periods[0]` is the cohort size (a customer or subscription count, unit `#`) and the measure starts at `period: 1`, which `periods[1].display_name` labels (typically `Month 0`). Read `periods[period]` for the label, unit and scale of each point instead of assuming `period` is the month number. |
| `summary` | object | no | Summary statistics for the chart data |
| `yaxis` | string | yes | Y-axis configuration including unit |
| `segments` | array of ChartSeries | no | Segment information when data is segmented, one entry per series in `values`. Non-realtime (`realtime=false`) cohort charts return their column metadata here instead of in `periods`. |
| `segments_limit` | integer | no | Maximum number of segments returned |
| `periods` | array of ChartSeries | no | Column metadata for cohort-shaped charts (`cohort_explorer`, `prediction_explorer`, `subscription_retention`, ...) on realtime charts. Positional: entry `i` describes the data points with `period: i` in `values`, so `len(periods)` is one more than the number of measure periods. `periods[0]` always describes the cohort size (unit `#`), and `periods[1]` is the first measure period (typically `Month 0`). |
| `measures` | array of object | no | Measure definitions for the chart (v3 charts) |
| `user_selectors` | object | no | Currently selected values for user-configurable selectors (keyed by selector name) |
| `unsupported_params` | object | no | Deprecated and always `null`. Unsupported parameters are rejected with a 400 error instead of being reported in the response. |
| `annotations` | array of ChartAnnotation | no | Chart annotations for the project, filtered to the chart's date window. Only present when include_annotations=true is passed in the request. |

<details><summary><code>segments</code></summary>

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `display_name` | string | yes | Human-readable label for the series. For cohort `periods`, index 0 is named after the cohorting date (e.g. `New customers`) and later indices after the cohort age (e.g. `Month 0`, `Month 1`). |
| `description` | string | no | Longer explanation of what the series measures. |
| `unit` | string | no | Unit the values of this series are expressed in. `#` means the values are counts, not amounts of the chart's measure. |
| `decimal_precision` | integer | no | Number of decimal places the values of this series should be rendered with. |
| `scale` | string | no | Whether the values of this series are absolute amounts or percentages of a baseline. One of: `absolute`, `relative` |
| `chartable` | boolean | no | Whether the series is meaningful to plot. |
| `tabulable` | boolean | no | Whether the series is meaningful to show as a table column. |
| `is_total` | boolean | no | Whether the series aggregates all the others. |
| `is_other` | boolean | no | Whether the series aggregates the segments beyond `segments_limit`. |
| `nested_measures` | array of ChartSeries | no | Per-measure metadata, when a segmented series carries more than one measure. |

</details>

<details><summary><code>periods</code></summary>

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `display_name` | string | yes | Human-readable label for the series. For cohort `periods`, index 0 is named after the cohorting date (e.g. `New customers`) and later indices after the cohort age (e.g. `Month 0`, `Month 1`). |
| `description` | string | no | Longer explanation of what the series measures. |
| `unit` | string | no | Unit the values of this series are expressed in. `#` means the values are counts, not amounts of the chart's measure. |
| `decimal_precision` | integer | no | Number of decimal places the values of this series should be rendered with. |
| `scale` | string | no | Whether the values of this series are absolute amounts or percentages of a baseline. One of: `absolute`, `relative` |
| `chartable` | boolean | no | Whether the series is meaningful to plot. |
| `tabulable` | boolean | no | Whether the series is meaningful to show as a table column. |
| `is_total` | boolean | no | Whether the series aggregates all the others. |
| `is_other` | boolean | no | Whether the series aggregates the segments beyond `segments_limit`. |
| `nested_measures` | array of ChartSeries | no | Per-measure metadata, when a segmented series carries more than one measure. |

</details>

<details><summary><code>unsupported_params</code></summary>

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `filters` | array of string | no |  |
| `segment` | string | no |  |

</details>

<details><summary><code>annotations</code></summary>

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `object` | string | yes | String representing the object's type. Objects of the same type share the same value. One of: `chart_annotation` |
| `id` | string | yes | The ID of the chart annotation. |
| `description` | string | yes | Human-readable description of the event this annotation represents. |
| `start_date` | string | yes | The start date of the annotated period (ISO 8601 date format). |
| `end_date` | string | yes | The end date of the annotated period (ISO 8601 date format), or null if the annotation is a single-day event. |

</details>
### Get available options for a chart

`GET /projects/{project_id}/charts/{chart_name}/options`

Operation ID: `get-chart-options`

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): <code>charts_metrics:charts:read</code>. This endpoint belongs to the <strong>Charts & Metrics</strong> domain, which has a default rate limit of <strong>25 requests per minute</strong>.

**Parameters**

| Name | In | Required | Description |
| --- | --- | --- | --- |
| `project_id` | path | yes | ID of the project |
| `chart_name` | path | yes | 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). |
| `realtime` | query | no | Whether to request real-time (v3) charts. Defaults to true. Set to false to request the v2 charts. |

**Responses**

- `200` — Chart options retrieved successfully
- `400` — Bad request
- `401` — Unauthorized
- `403` — Access denied
- `404` — Not found
- `423` — Locked
- `429` — The request could not be completed because the rate limiting domain for this endpoint is currently at its limit for this project.
- `500` — Internal server error
- `503` — Internal server error

**Response `200` body**

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `object` | string | yes | String representing the object's type. Objects of the same type share the same value. One of: `chart_options` |
| `resolutions` | array of object | yes | Available time resolutions for the chart |
| `segments` | array of ChartSegmentOption | yes | Available segmentation options |
| `filters` | array of ChartFilterOption | yes | Available filter options |
| `user_selectors` | object | no | User-configurable selectors for the chart (keyed by selector name) |

<details><summary><code>resolutions</code></summary>

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `id` | string | yes | Resolution ID to use in requests |
| `display_name` | string | yes | Human-readable name |

</details>

<details><summary><code>segments</code></summary>

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `object` | string | yes | String representing the object's type. Objects of the same type share the same value. One of: `chart_segment_option` |
| `id` | string | yes | Unique identifier for the segment option |
| `display_name` | string | yes | Human-readable name for the segment option |
| `group_display_name` | string | no | Group name for organizing segment options |

</details>

<details><summary><code>filters</code></summary>

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `object` | string | yes | String representing the object's type. Objects of the same type share the same value. One of: `chart_filter_option` |
| `id` | string | yes | Unique identifier for the filter |
| `display_name` | string | yes | Human-readable name for the filter |
| `group_display_name` | string | no | Group name for organizing filter options |
| `options` | array of object | yes | Available values for this filter |

<details><summary><code>options</code></summary>

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `id` | string | yes | Unique identifier for the option value |
| `display_name` | string | yes | Human-readable name for the option value |

</details>
</details>