Get user transaction ranking (Admin only)

Request

Returns ranked list of users with full user details and transaction metrics. Data enrichment via efficient SQL JOINs + UNION (handles legacy transactions). Supports filtering by business, token type, date range. Requires admin authentication.

Security

authJWT

Bodyapplication/jsonrequired

User ranking request with filters, sorting, and limit

filtersobject(UserRankingFiltersDTO)

Filters to scope which transactions/users to include

Example:

{
  "businessId": "biz-uuid-123",
  "tokenType": "ERC721"
}

sortBystring

Field to sort results by

Default:"totalTransactions"

Enum:"totalTransactions""tokenSpent""totalClaims""userId""email"

Example:"totalTransactions"

sortOrderstring

Sort direction

Default:"DESC"

Enum:"ASC""DESC"

Example:"DESC"

limitnumber, [ 1 .. 1000 ]

Maximum number of results to return (top N users)

Default:50

Example:50

startDatestring, (date-time)

Start date for filtering transactions (ISO 8601 format). Only transactions within date range are counted.

Example:"2024-01-01T00:00:00Z"

endDatestring, (date-time)

End date for filtering transactions (ISO 8601 format). Only transactions within date range are counted.

Example:"2024-12-31T23:59:59Z"

curl -i -X POST \
  https://docs.pers.ninja/_mock/swagger/analytics/users/ranking \
  -H 'Authorization: Bearer <YOUR_JWT_HERE>' \
  -H 'Content-Type: application/json' \
  -d '{
    "sortBy": "totalTransactions",
    "sortOrder": "DESC",
    "limit": 50
  }'

Responses

User ranking successfully retrieved

Bodyapplication/json

resultsArray of arraysrequired

Ranked list of users with transaction metrics and full user details. Pre-sorted by backend.

totalUsersnumberrequired

Total number of users returned (≤ request.limit)

Example:50

metadataobjectrequired

Metadata about the query execution

Response

{
  "results": [
    []
  ],
  "totalUsers": 50,
  "metadata": {}
}