Free Subscribers

GET https://api.chartmogul.com/v2/metrics/free_subscribers

Retrieves the number of free subscribers for the specified time period.

curl -X GET "https://api.chartmogul.com/v2/metrics/free_subscribers" \
     -u YOUR_API_KEY: \
     -G \
     -d start=2026-08-01 \
     -d end=2026-10-31 \
     -d interval=month \
     -d include_summary=true
{
  "entries": [
    {
      "date": "2026-09-30",
      "value": 0.0,
      "percentage-change": null
    },
    {
      "date": "2026-10-31",
      "value": 0.0,
      "percentage-change": null
    }
  ],
  "summary": {
    "current": 0.0,
    "previous": 0.0,
    "percentage-change": null
  }
}

Query parameters

start date required
The start date of the required period of data. An ISO-8601 formatted date, e.g. 2026-08-01. Must not be later than end.
end date required
The end date of the required period of data. An ISO-8601 formatted date, e.g. 2026-10-31.
interval string required
One of day, week, month, quarter, or year.
filters string optional
A set of filters to limit the results, formatted as CFL. Copy URL-encoded CFL from the app (e.g., filters=currency~ANY~%27USD%27) or write the expression manually and enclose the key-value pair in double quotes (e.g., "filters=currency~ANY~'USD'"). To limit the results to certain countries or plans, use a filter; there are no separate geo and plans parameters.
include_summary boolean optional default: false
Set to true to add the summary key to the response.
include_data_table boolean optional default: false
Set to true to add the data_table key to the response.

Response

In the response, the entries key contains an object for each interval, with the following data:

date
The date of the end of the interval.
value
The number of free subscribers at the end of the interval.
percentage-change
The percentage change from the previous entry. Not present in the first entry.

The summary key is present when include_summary is true. It contains the most recent value and the value it is compared with (current and previous) of the number of free subscribers and the percentage change between the two (percentage-change).

The data_table key is present when include_data_table is true. It contains an object for each interval with the number of free subscribers at its start (previous_subscribers) and end (total_subscribers), and the number of customers behind the change: activations, reactivations, cancellations and conversions from free to paid.