Dashboard
APIProject Analytics | Subscription Bot API

Subscription Bot Project Analytics

Build reports for your Telegram subscription bot or Discord subscription bot using the project analytics endpoints. Reports return ready-to-display buckets, summaries, or breakdowns.

Analytics API access

Restricted project keys need analytics:charts:read. Unrestricted keys can also read these reports. This scope covers every report in this section; analytics:sales:read does not grant access to them.

Coupon codes additionally require coupons:read. Customer identifiers in rankings and recent sales require an unrestricted project key. The endpoint pages show the corresponding response variants.

Date windows and subscription reports

Send from and to as real UTC calendar days in YYYY-MM-DD format, between 2000-01-01 and 2099-12-31. Both days are included, with a maximum window of 366 days. Defaults cover today and the preceding 29 days.

Series endpoints accept interval=day, week, or month. Weeks begin on Monday; months follow the calendar. Buckets are ordered oldest first and include empty periods. A clipped first bucket can have a bucket key before period.from; its start and end stay within the window. Other reports reject interval.

Analytics calendar labels are date-only strings: period.from, period.to, bucket labels and boundaries, coverage days, and loss days use YYYY-MM-DD. Retention cohort labels use YYYY-MM. These labels differ from timestamps such as generated_at, as_of, and paid_at, which use UTC ISO strings with milliseconds.

Revenue amounts and unknown values

Money maps use lower-case currency keys and decimal-string values, such as {"usd":"29.99","eur":"20"}. Currencies are never converted or added together. An empty map means no matching money. Counts remain integers, and rates are numbers from zero to one, rounded to four decimals.

A null rate or activity value means unknown or undefined, rather than zero. Display a gap or an unavailable state. Individual reports explain when values are nullable.

Freshness and report limits

Reports are cached for 120 seconds. A cached response keeps its original generated_at; poll according to that freshness window.

Each route allows 20 requests per minute per caller and project. A rate-limit outage also refuses requests. A limit response does not ban the caller.

Reports return 413 EXPORT_LIMIT_EXCEEDED when their source-data cap is exceeded, without partial results. Narrow the window where useful; some reports must inspect older history regardless of the selected start date. Invalid or unknown query parameters return 422 VALIDATION_ERROR.

Membership history

Ended memberships are deleted. Reports reading current membership rows cannot reconstruct those deleted memberships. Extensions also rewrite expiry dates, so past counts and retention cells can change and can count a lapse as continuous access.

Use membership changes and retention cohorts with these limits in mind. For paid recurring coverage, the monthly recurring revenue report uses recorded payment evidence and reports exclusions.

Browse the endpoint dropdown for each report's parameters and complete response examples. The project API overview covers authentication, response envelopes, and shared error handling.

Last updated: