> ## 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 Users
> **/user/** - Enhanced with Fast Accounting Data
This endpoint requires authentication. Include your Bearer token in the Authorization header.
## Description
**Description:**\
The `/user/` endpoint retrieves user data with optional accounting information from cached data.
**Enhanced Accounting Support:**
When `accounting=true`, this endpoint now provides:
* **95% faster performance**: 10-50ms response vs previous 500-2000ms BigQuery approach
* **Cached accounting data**: Returns Gross, Paid, Due values from UserAccounting table
* **Background processing**: Automatically queues calculation for users without cached data
* **Transparent operations**: Response includes metadata about cache status and queued calculations
**Method:** `GET`
**Query Parameters:**
| Parameter | Type | Description |
| ----------------------- | ------- | ----------------------------------------------------- |
| q *(Optional)* | string | Search query to filter users by name or email |
| page *(Optional)* | integer | Page number for pagination. Default: 1 |
| size *(Optional)* | integer | Number of users per page. Default: 10 |
| accounting *(Optional)* | string | Set to 'true' to include fast cached accounting data |
| attributes *(Optional)* | string | Comma-separated list of attributes to include |
| sort *(Optional)* | string | Sort field: 'createdAt', 'updatedAt', 'name', 'split' |
| order *(Optional)* | string | Sort order: 'asc' or 'desc' |
| externalId *(Optional)* | string | Filter by external ID |
| role *(Optional)* | string | Filter by user role(s), comma-separated for multiple |
**Performance Notes:**
* Without accounting: Standard user list response
* With accounting=true: Includes cached Gross, Paid, Due values with 95% faster performance
* Users without cache: Return zeros with `pendingCalculation: true` and get queued for background processing
## Code Examples
```javascript Node.js theme={null}
const response = await fetch('https://api.royalti.io/user/', {
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/',
headers={
'Authorization': f'Bearer {token}'
},
)
data = response.json()
print(data)
```
```bash cURL theme={null}
curl -X GET https://api.royalti.io/user/ \
-H "Authorization: Bearer YOUR_TOKEN" \
```
## OpenAPI
````yaml get /user/
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/:
get:
tags:
- User
summary: Get Users
description: >-
**/user/** - Enhanced with Fast Accounting Data
**Description:**
The `/user/` endpoint retrieves user data with optional accounting
information from cached data.
**Enhanced Accounting Support:**
When `accounting=true`, this endpoint now provides:
- **95% faster performance**: 10-50ms response vs previous 500-2000ms
BigQuery approach
- **Cached accounting data**: Returns Gross, Paid, Due values from
UserAccounting table
- **Background processing**: Automatically queues calculation for users
without cached data
- **Transparent operations**: Response includes metadata about cache
status and queued calculations
**Method:** `GET`
**Query Parameters:**
| Parameter | Type | Description |
| --- | --- | --- |
| q _(Optional)_ | string | Search query to filter users by name or
email |
| page _(Optional)_ | integer | Page number for pagination. Default: 1 |
| size _(Optional)_ | integer | Number of users per page. Default: 10 |
| accounting _(Optional)_ | string | Set to 'true' to include fast
cached accounting data |
| attributes _(Optional)_ | string | Comma-separated list of attributes
to include |
| sort _(Optional)_ | string | Sort field: 'createdAt', 'updatedAt',
'name', 'split' |
| order _(Optional)_ | string | Sort order: 'asc' or 'desc' |
| externalId _(Optional)_ | string | Filter by external ID |
| role _(Optional)_ | string | Filter by user role(s), comma-separated
for multiple |
**Performance Notes:**
- Without accounting: Standard user list response
- With accounting=true: Includes cached Gross, Paid, Due values with 95%
faster performance
- Users without cache: Return zeros with `pendingCalculation: true` and
get queued for background processing
parameters:
- name: q
in: query
required: false
description: Search query to filter users
schema:
type: string
- name: page
in: query
required: false
description: Page number for pagination
schema:
type: string
- name: size
in: query
required: false
description: Number of users per page
schema:
type: string
- name: accounting
in: query
required: false
description: Set to 'true' to include fast cached accounting data
schema:
type: string
enum:
- 'true'
- 'false'
example: 'true'
- name: attributes
in: query
required: false
description: Comma-separated list of attributes to include in the response
schema:
type: string
- name: externalId
in: query
required: false
description: Filter users by external ID
schema:
type: string
example: ext-user-12345
- name: role
in: query
required: false
description: Filter by user role(s), comma-separated for multiple
schema:
type: string
example: admin,user
- name: sort
in: query
required: false
description: >-
Sort field (using accounting fields like 'gross', 'paid', 'due'
requires accounting=true)
schema:
type: string
enum:
- createdAt
- updatedAt
- name
- split
- gross
- paid
- due
example: updatedAt
- name: order
in: query
required: false
description: >-
this value determines the order for sorting the result, either
ascending or descending
schema:
type: string
enum:
- asc
- desc
default: desc
responses:
'200':
description: Success
content:
application/json:
schema:
type: object
properties:
message:
type: string
example: success
Users:
type: array
items:
type: object
properties:
id:
type: string
format: uuid
fullName:
type: string
firstName:
type: string
lastName:
type: string
email:
type: string
role:
type: string
Gross:
type: number
format: float
description: Total gross earnings (when accounting=true)
Paid:
type: number
format: float
description: Total amount paid (when accounting=true)
Due:
type: number
format: float
description: Amount currently due (when accounting=true)
calculationMethod:
type: string
nullable: true
description: Method used for calculation (when accounting=true)
lastCalculatedAt:
type: string
format: date-time
nullable: true
description: >-
When accounting was last calculated (when
accounting=true)
pendingCalculation:
type: boolean
description: >-
True if accounting calculation is queued (when
accounting=true)
count:
type: integer
description: Number of users in current page
totalUsers:
type: integer
description: Total number of users
accountingMetadata:
type: object
description: >-
Metadata about accounting calculations (when
accounting=true)
properties:
usersWithCache:
type: integer
description: Number of users with cached accounting data
usersQueuedForCalculation:
type: integer
description: Number of users queued for background calculation
calculationMethod:
type: string
example: cached
description: Overall calculation method used
sortedBy:
type: string
nullable: true
description: Accounting field used for sorting (if applicable)
example: due
sortDirection:
type: string
nullable: true
description: Sort direction when accounting sorting is used
example: desc
examples:
withoutAccounting:
summary: Standard response without accounting
value:
message: success
Users:
- fullName: Royal Records
email: royal@royalti.io
id: eec29e6f-b567-4ca4-befe-658743058098
firstName: Royal
lastName: Records
role: user
externalId: '2892'
country: Åland Islands
createdAt: '2022-02-26T04:38:21.560Z'
updatedAt: '2024-03-22T11:10:53.519Z'
User:
email: royal@royalti.io
Artists:
- id: 2fca1b81-2f97-4b02-92a2-899d17c756b8
artistName: Young Blud
count: 1
totalUsers: 1
withAccounting:
summary: Enhanced response with cached accounting data
value:
message: success
Users:
- id: eec29e6f-b567-4ca4-befe-658743058098
fullName: Royal Records
firstName: Royal
lastName: Records
email: royal@royalti.io
role: user
Gross: 1500.75
Paid: 1000
Due: 500.75
calculationMethod: hybrid
lastCalculatedAt: '2025-01-10T14:30:00.000Z'
Artists:
- id: 2fca1b81-2f97-4b02-92a2-899d17c756b8
artistName: Young Blud
- id: user-456-uuid
fullName: Jane Smith
firstName: Jane
lastName: Smith
email: jane@example.com
role: user
Gross: 0
Paid: 0
Due: 0
calculationMethod: null
lastCalculatedAt: null
pendingCalculation: true
count: 2
totalUsers: 2
accountingMetadata:
usersWithCache: 1
usersQueuedForCalculation: 1
calculationMethod: cached
sortedBy: null
sortDirection: null
accountingSortExample:
summary: Response with accounting sort by due amount (desc)
value:
message: success
Users:
- id: user-highest-due
fullName: Top Earner
firstName: Top
lastName: Earner
email: top@example.com
role: user
Gross: 5000
Paid: 1000
Due: 4000
calculationMethod: hybrid
lastCalculatedAt: '2025-01-10T14:30:00.000Z'
- id: user-medium-due
fullName: Mid Earner
firstName: Mid
lastName: Earner
email: mid@example.com
role: user
Gross: 2000
Paid: 1500
Due: 500
calculationMethod: stats
lastCalculatedAt: '2025-01-09T12:00:00.000Z'
- id: user-no-cache
fullName: No Cache User
firstName: 'No'
lastName: Cache
email: nocache@example.com
role: user
Gross: 0
Paid: 0
Due: 0
calculationMethod: null
lastCalculatedAt: null
pendingCalculation: true
count: 3
totalUsers: 3
accountingMetadata:
usersWithCache: 2
usersQueuedForCalculation: 1
calculationMethod: cached
sortedBy: due
sortDirection: desc
'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}"
````