Analytics

Get the revenue timeseries

GET/v1/analytics/revenue/timeseries

Bucketed net revenue for charts, gap-filled (every bucket of the window is present, zero-filled by type). Buckets are timezone-correct across DST. granularity defaults to a sensible value for the window size (≤2d: hour, ≤31d: day, ≤90d: week, else month). Each bucket size caps how wide the window may be (hour ≤ 7 days, day ≤ 31 days, week ≤ 365 days, month ≤ 365 days); a wider window is rejected with 400 rather than silently truncated, so fetch older history with additional requests.

Required scoperead:analytics

Rate limit20 requests per minute

curl 'https://api.fansquare.so/v1/analytics/revenue/timeseries?start=2026-09-01&end=2026-09-30&timezone=Europe%2FParis&granularity=day&breakdown=creator' \
  -H "Authorization: Bearer $API_KEY" \
  -H "Fansquare-Version: Amethyste"

{
  "data": [
    {
      "date": "2026-08-31T22:00:00.000Z",
      "total": 41200,
      "by_type": {
        "tip": 9800,
        "subscription": 14000,
        "subscription_renewal": 7900,
        "booking": 0,
        "push": 6500,
        "mod": 0,
        "fan_to_creator": 3000,
        "creator_to_fan": 0,
        "affiliate": 0,
        "affiliation": 0
      },
      "by_creator": {
        "m81IhLxdhzDGYs54rNp2": 41200
      }
    }
  ],
  "granularity": "day"
}

Parameters

Headers

Fansquare-Versionstringrequired
API version to pin. Accepts the mineral name or the release date of a version.

Query

startstringrequired
First day of the window (inclusive), e.g. 2026-07-01. Interpreted in timezone. A date-time is accepted too and floored to its local day.
endstringrequired
Last day of the window (inclusive: the whole day is covered), e.g. 2026-07-31. Interpreted in timezone. The window cannot exceed 365 days (and less for the finer bucket sizes of the timeseries endpoint); fetch older history with additional requests.
timezonestring
IANA timezone the window and buckets are computed in, canonical Area/Location form (e.g. Europe/Paris). Abbreviations like CET are rejected. Defaults to UTC.
creator_idsstring
Restrict to these creators (Fansquare ids from GET /v1/creators). Omit for every creator the key can see. Comma-separated, 50 max.
granularitystring
Bucket size. Maximum window per bucket size: hour ≤ 7 days, day ≤ 31 days, week ≤ 365 days, month ≤ 365 days.
Valueshourdayweekmonth
breakdown"creator"
Adds a per-creator revenue map to each bucket (by_creator).
user_idsstring
Only count revenue attributed to these employees (Fansquare user ids from GET /v1/employees). Comma-separated, 50 max.

Response

OK, application/json

dataarray of objectsrequired
datestringrequired
Bucket start instant, ISO 8601 UTC. Buckets are aligned on local midnights/hours in timezone.
format date-time
totalintegerrequired
Net revenue of the bucket, EUR cents.
by_typeobjectrequired
Net revenue in EUR cents per order type, every type present and zero-filled (affiliate revenue is grouped under affiliation).
tipintegerrequired
subscriptionintegerrequired
subscription_renewalintegerrequired
bookingintegerrequired
pushintegerrequired
modintegerrequired
fan_to_creatorintegerrequired
creator_to_fanintegerrequired
affiliateintegerrequired
affiliationintegerrequired
by_creatormap of integers
Only with breakdown=creator: net revenue per creator id (sparse, absent creators earned 0).
granularitystringrequired
The bucket size actually used.
Valueshourdayweekmonth

curl 'https://api.fansquare.so/v1/analytics/revenue/timeseries?start=2026-09-01&end=2026-09-30&timezone=Europe%2FParis&granularity=day&breakdown=creator' \
  -H "Authorization: Bearer $API_KEY" \
  -H "Fansquare-Version: Amethyste"

{
  "data": [
    {
      "date": "2026-08-31T22:00:00.000Z",
      "total": 41200,
      "by_type": {
        "tip": 9800,
        "subscription": 14000,
        "subscription_renewal": 7900,
        "booking": 0,
        "push": 6500,
        "mod": 0,
        "fan_to_creator": 3000,
        "creator_to_fan": 0,
        "affiliate": 0,
        "affiliation": 0
      },
      "by_creator": {
        "m81IhLxdhzDGYs54rNp2": 41200
      }
    }
  ],
  "granularity": "day"
}