Skip to main content
GET
/
user
/
{id}
/
monthly
Get User Monthly Stats
curl --request GET \
  --url https://server26-dot-royalti-project.uc.r.appspot.com/user/{id}/monthly \
  --header 'Authorization: Bearer <token>'
{
  "data": [
    {
      "Month": "2025-08-01",
      "Count": 903,
      "Royalty": 21.14823258699999,
      "Royalty_Share": 6.344469776099996
    },
    {
      "Month": "2025-07-01",
      "Count": 4997,
      "Royalty": 36.20617996492299,
      "Royalty_Share": 10.861853989476888
    }
  ],
  "meta": {
    "dateRange": {
      "startDate": "2025-01-01",
      "endDate": "2025-08-09"
    },
    "totalMonths": 8,
    "period": "ytd",
    "allTimeData": false,
    "filtersUsed": {
      "period": true,
      "customDates": false,
      "defaultApplied": false
    }
  }
}
/user//monthly Description:
The /user/{userId}/monthly endpoint allows users to retrieve monthly statistics like count and RoyaltyShare related to a specific user identified by their unique userId. By default, returns the last 12 months of data. Use optional query parameters to filter specific date ranges. Method:
GET Path Parameter:
ParameterTypeDescription
userIdstringThe unique identifier of the user.
Query Parameters:
ParameterTypeRequiredDescription
periodstringNoPeriod preset: all, last12months, ytd, or custom. If custom, requires startDate/endDate.
startDatestringNoStart date for filtering (YYYY-MM-DD format). Overrides period parameter.
endDatestringNoEnd date for filtering (YYYY-MM-DD format). Overrides period parameter.
Parameter Priority:
  1. Custom dates (startDate/endDate) override period parameter
  2. Period presets are used if no custom dates provided
  3. Defaults to last 12 months if neither provided
Examples:
  • /user/{id}/monthly - Returns last 12 months (default)
  • /user/{id}/monthly?period=all - Returns all historical data
  • /user/{id}/monthly?period=ytd - Returns year-to-date data
  • /user/{id}/monthly?period=last12months - Same as default
  • /user/{id}/monthly?startDate=2024-01-01&endDate=2024-12-31 - Custom range (ignores period)
  • /user/{id}/monthly?startDate=2024-06-01 - From June 2024 to today
See Sample Response Below

​
Authentication

This endpoint requires authentication. Include your bearer token in the Authorization header.

​
Path Parameters

ParameterTypeInRequiredDescription
idstringpath✅User ID

​
Query Parameters

ParameterTypeInRequiredDescription
periodstringquery❌Period preset for filtering monthly data
startDatestringquery❌Start date for filtering monthly data (YYYY-MM-DD format)
endDatestringquery❌End date for filtering monthly data (YYYY-MM-DD format)

​
Responses

​
✅ 200 - success

​
yearToDate

{
  "data": [
    {
      "Month": "2025-08-01",
      "Count": 903,
      "Royalty": 21.14823258699999,
      "Royalty_Share": 6.344469776099996
    },
    {
      "Month": "2025-07-01",
      "Count": 4997,
      "Royalty": 36.20617996492299,
      "Royalty_Share": 10.861853989476888
    }
  ],
  "meta": {
    "dateRange": {
      "startDate": "2025-01-01",
      "endDate": "2025-08-09"
    },
    "totalMonths": 8,
    "period": "ytd",
    "allTimeData": false,
    "filtersUsed": {
      "period": true,
      "customDates": false,
      "defaultApplied": false
    }
  }
}

​
allTimeData

{
  "data": [
    {
      "Month": "2025-08-01",
      "Count": 1200,
      "Royalty": 45.67,
      "Royalty_Share": 12.34
    },
    {
      "Month": "2024-12-01",
      "Count": 903,
      "Royalty": 21.14823258699999,
      "Royalty_Share": 6.344469776099996
    }
  ],
  "meta": {
    "dateRange": null,
    "totalMonths": 48,
    "period": "all",
    "allTimeData": true,
    "filtersUsed": {
      "period": true,
      "customDates": false,
      "defaultApplied": false
    }
  }
}

​
⚠️ 400 - Bad Request - Invalid date format or date range

​
invalidFormat

{
  "error": "Invalid date format. Use YYYY-MM-DD format."
}

​
invalidRange

{
  "error": "Start date must be before end date."
}

​
invalidPeriod

{
  "error": "Invalid period. Use: all, last12months, ytd, or custom."
}

​
customWithoutDates

{
  "error": "Period \"custom\" requires startDate and endDate parameters."
}

​
⚠️ 401 - Unauthorized

​
⚠️ 404 - Not Found

​
❌ 500 - Internal Server Error

​
Tags

User

Authorizations

​
Authorization
string
header
required

JWT Authorization header using the Bearer scheme. Format: "Bearer {token}"

Path Parameters

​
id
string
required

User ID

Query Parameters

​
period
enum<string>

Period preset for filtering monthly data

Available options:
all,
last12months,
ytd,
custom
Example:

"ytd"

​
startDate
string<date>

Start date for filtering monthly data (YYYY-MM-DD format)

Example:

"2024-01-01"

​
endDate
string<date>

End date for filtering monthly data (YYYY-MM-DD format)

Example:

"2024-12-31"

Response

success

​
data
object[]
​
meta
object
⌘I