Skip to main content
GET
/
user
/
Get Users
curl --request GET \
  --url https://api.royalti.io/user/ \
  --header 'Authorization: Bearer <token>'
{
  "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
}
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:
ParameterTypeDescription
q (Optional)stringSearch query to filter users by name or email
page (Optional)integerPage number for pagination. Default: 1
size (Optional)integerNumber of users per page. Default: 10
accounting (Optional)stringSet to ‘true’ to include fast cached accounting data
attributes (Optional)stringComma-separated list of attributes to include
sort (Optional)stringSort field: ‘createdAt’, ‘updatedAt’, ‘name’, ‘split’
order (Optional)stringSort order: ‘asc’ or ‘desc’
externalId (Optional)stringFilter by external ID
role (Optional)stringFilter 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

const response = await fetch('https://api.royalti.io/user/', {
  method: 'GET',
  headers: {
    'Authorization': `Bearer ${token}`,
  },
});

const data = await response.json();
console.log(data);

Authorizations

​
Authorization
string
header
required

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

Query Parameters

​
q
string

Search query to filter users

​
page
string

Page number for pagination

​
size
string

Number of users per page

​
accounting
enum<string>

Set to 'true' to include fast cached accounting data

Available options:
true,
false
​
attributes
string

Comma-separated list of attributes to include in the response

​
externalId
string

Filter users by external ID

​
role
string

Filter by user role(s), comma-separated for multiple

​
sort
enum<string>

Sort field (using accounting fields like 'gross', 'paid', 'due' requires accounting=true)

Available options:
createdAt,
updatedAt,
name,
split,
gross,
paid,
due
​
order
enum<string>
default:desc

this value determines the order for sorting the result, either ascending or descending

Available options:
asc,
desc

Response

Success

​
message
string
Example:

"success"

​
Users
object[]
​
count
integer

Number of users in current page

​
totalUsers
integer

Total number of users

​
accountingMetadata
object

Metadata about accounting calculations (when accounting=true)