> ## Documentation Index
> Fetch the complete documentation index at: https://apidocs.royalti.io/llms.txt
> Use this file to discover all available pages before exploring further.
# Get User Monthly Stats
> **/user/{userId}/monthly**
This endpoint requires authentication. Include your Bearer token in the Authorization header.
## Description
**/user/{userId}/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:**
| Parameter | Type | Description |
| --------- | ------ | ---------------------------------- |
| userId | string | The unique identifier of the user. |
**Query Parameters:**
| Parameter | Type | Required | Description |
| --------- | ------ | -------- | -------------------------------------------------------------------------------------------------- |
| period | string | No | Period preset: `all`, `last12months`, `ytd`, or `custom`. If `custom`, requires startDate/endDate. |
| startDate | string | No | Start date for filtering (YYYY-MM-DD format). Overrides period parameter. |
| endDate | string | No | End 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**
## Code Examples
```javascript Node.js theme={null}
const response = await fetch('https://api.royalti.io/user/example-id/monthly', {
method: 'GET',
headers: {
'Authorization': `Bearer ${token}`,
},
});
const data = await response.json();
console.log(data);
```
```python Python theme={null}
import requests
response = requests.get(
'https://api.royalti.io/user/example-id/monthly',
headers={
'Authorization': f'Bearer {token}'
},
)
data = response.json()
print(data)
```
```bash cURL theme={null}
curl -X GET https://api.royalti.io/user/example-id/monthly \
-H "Authorization: Bearer YOUR_TOKEN" \
```
## OpenAPI
````yaml get /user/{id}/monthly
openapi: 3.0.0
info:
title: Royalti.io API
description: "# Royalti API\r\n\r\nThis is the Royalti music royalty management platform API server.\r\n\r\n## Overview\r\n\r\nThe Royalti API provides comprehensive music royalty management services including:\r\n- Music publishing and writer management\r\n- Royalty processing and analytics\r\n- DDEX integration for music industry standards\r\n- File processing and pattern recognition\r\n- Payment processing and distribution\r\n\r\n## Authentication\r\n\r\nThe API uses JWT-based authentication with multiple protection levels:\r\n- Public endpoints for basic operations\r\n- Protected endpoints requiring valid JWT tokens\r\n- Admin endpoints for administrative functions\r\n\r\n## Features\r\n\r\n- Multi-dimensional royalty analytics\r\n- CWR (Collective Works Registration) support\r\n- DDEX integration for music metadata\r\n- Advanced file processing with pattern recognition\r\n- Real-time data processing with queue system"
version: 2.6.0
contact:
name: Royalti.io Support
email: support@royalti.io
url: https://royalti.io
license:
name: Proprietary
url: https://royalti.io/terms
servers:
- url: https://api.royalti.io
description: Production server
- url: https://api-dev.royalti.io
description: Development server
- url: http://localhost:8084
description: Local development
security:
- bearerAuth: []
tags:
- name: Accounting
description: Accounting and financial transaction operations
- name: DDEX
description: DDEX operations (ERN/MEAD, messages, delivery, providers)
- name: Label
description: Label management operations
- name: Internal Webhooks
description: Internal system webhooks for royalty processing and downloads
- name: Payment Webhooks
description: Payment processor webhook endpoints
- name: Billing Webhooks
description: Stripe billing and subscription webhooks
- name: Infrastructure Webhooks
description: Cloudflare domain and SSL webhooks
- name: Distribution Webhooks
description: Digital distribution platform webhooks (FUGA)
paths:
/user/{id}/monthly:
get:
tags:
- User
summary: Get User Monthly Stats
description: >-
**/user/{userId}/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:**
| Parameter | Type | Description |
| --- | --- | --- |
| userId | string | The unique identifier of the user. |
**Query Parameters:**
| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| period | string | No | Period preset: `all`, `last12months`, `ytd`, or
`custom`. If `custom`, requires startDate/endDate. |
| startDate | string | No | Start date for filtering (YYYY-MM-DD
format). Overrides period parameter. |
| endDate | string | No | End 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**
parameters:
- name: id
in: path
required: true
description: User ID
schema:
type: string
- name: period
in: query
required: false
description: Period preset for filtering monthly data
schema:
type: string
enum:
- all
- last12months
- ytd
- custom
example: ytd
- name: startDate
in: query
required: false
description: Start date for filtering monthly data (YYYY-MM-DD format)
schema:
type: string
format: date
example: '2024-01-01'
- name: endDate
in: query
required: false
description: End date for filtering monthly data (YYYY-MM-DD format)
schema:
type: string
format: date
example: '2024-12-31'
responses:
'200':
description: success
content:
application/json:
schema:
type: object
properties:
data:
type: array
items:
type: object
properties:
Month:
type: string
format: date
Count:
type: integer
Royalty:
type: number
Royalty_Share:
type: number
meta:
type: object
properties:
dateRange:
type: object
nullable: true
properties:
startDate:
type: string
format: date
endDate:
type: string
format: date
totalMonths:
type: integer
period:
type: string
enum:
- all
- last12months
- ytd
- custom
allTimeData:
type: boolean
description: True if no date filtering was applied
filtersUsed:
type: object
properties:
period:
type: boolean
description: True if period parameter was used
customDates:
type: boolean
description: True if startDate/endDate were used
defaultApplied:
type: boolean
description: True if default 12-month filter was applied
examples:
yearToDate:
summary: Year-to-date response
value:
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:
summary: All-time data response (period=all)
value:
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':
description: Bad Request - Invalid date format or date range
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
examples:
invalidFormat:
summary: Invalid date format
value:
error: Invalid date format. Use YYYY-MM-DD format.
invalidRange:
summary: Invalid date range
value:
error: Start date must be before end date.
invalidPeriod:
summary: Invalid period parameter
value:
error: 'Invalid period. Use: all, last12months, ytd, or custom.'
customWithoutDates:
summary: Custom period without dates
value:
error: Period "custom" requires startDate and endDate parameters.
'401':
description: Unauthorized
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'404':
description: Not Found
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'500':
description: Internal Server Error
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
security:
- bearerAuth: []
components:
schemas:
Error:
type: object
properties:
success:
type: boolean
example: false
error:
type: object
properties:
code:
type: string
message:
type: string
details:
type: array
items:
type: string
securitySchemes:
bearerAuth:
type: http
scheme: bearer
bearerFormat: JWT
description: >-
JWT Authorization header using the Bearer scheme. Format: "Bearer
{token}"
````