Members

Member endpoints return Discord guild members enriched with bot-tracked stats (messages, XP, level, warnings). All endpoints require admin-level permissions (ADMINISTRATOR). Requests are rate-limited to 120 requests per 15 minutes per IP.

GET /guilds/:id/members

Returns the enriched member list with stats, XP, and warning counts. Supports search, sort, and cursor-based pagination. Authentication: API key or JWT Bearer token required.

Path parameters

string

required

The Discord guild ID.

Query parameters

limit

integer

Members per page. Default: 25. Range: 1–100.

after

string

Cursor for Discord pagination — the member ID to start after. Use the nextAfter value from the previous response.

string

Search members by username or display name prefix.

sort

string

Sort field. Options: messages, xp, warnings, joined. Default: joined.

order

string

Sort direction. Options: asc, desc. Default: desc.

Response fields

members

array

List of enriched member objects.

Show Member object fields

string

Discord user ID.

username

string

Discord username.

displayName

string

Guild display name (nickname or username).

avatar

string

Avatar URL.

roles

array

List of { id, name } role objects.

joinedAt

string

ISO 8601 timestamp when the member joined.

messages_sent

integer

Total messages tracked by the bot.

days_active

integer

Number of days the member has been active.

last_active

string | null

ISO 8601 timestamp of last activity.

integer

Total XP earned.

level

integer

Current level.

warning_count

integer

Number of active warnings.

nextAfter

string | null

Cursor for the next page. Pass as after in the next request. null when no more pages exist.

total

integer

Total guild member count.

filteredTotal

integer

Only present when search is active. Number of members matching the search query.

Example

curl -H "x-api-secret: YOUR_SECRET" \
  "https://volvox.bot/api/v1/guilds/987654321098765432/members?sort=xp&limit=10"

{
  "members": [
    {
      "id": "111000111",
      "username": "alice",
      "displayName": "Alice",
      "avatar": "https://cdn.discordapp.com/avatars/111000111/abc.png",
      "roles": [{ "id": "123123123", "name": "Moderator" }],
      "joinedAt": "2025-01-15T00:00:00.000Z",
      "messages_sent": 2400,
      "days_active": 45,
      "last_active": "2026-03-21T08:00:00.000Z",
      "xp": 15200,
      "level": 8,
      "warning_count": 0
    }
  ],
  "nextAfter": "111000222",
  "total": 512
}

GET /guilds/:id/members/:userId

Returns the full profile for a specific member, including stats, XP/level progression, roles, and recent warnings. Authentication: API key or JWT Bearer token required.

Path parameters

string

required

The Discord guild ID.

userId

string

required

The Discord user ID.

Response fields

string

Discord user ID.

username

string

Discord username.

displayName

string

Guild display name.

avatar

string

Avatar URL.

roles

array

List of role objects with id, name, and color (hex string).

joinedAt

string

ISO 8601 join timestamp.

stats

object | null

Activity stats from the bot database. null if no data has been tracked yet.

Show Stats fields

messages_sent

integer

Total messages sent.

reactions_given

integer

Total reactions given.

reactions_received

integer

Total reactions received.

days_active

integer

Days with at least one message.

first_seen

string

ISO 8601 timestamp of first tracked activity.

last_active

string

ISO 8601 timestamp of last tracked activity.

reputation

object

XP and level information.

Show Reputation fields

integer

Total XP earned.

level

integer

Current level.

messages_count

integer

Messages counted toward XP.

voice_minutes

integer

Voice minutes counted toward XP.

helps_given

integer

Help actions counted toward XP.

last_xp_gain

string | null

ISO 8601 timestamp of the most recent XP gain.

next_level_xp

integer | null

XP required to reach the next level.

warnings

object

Warning summary.

Show Warnings fields

count

integer

Total warning count.

recent

array

Up to 5 most recent warnings with case_number, action, reason, moderator_tag, and created_at.

Example

curl -H "x-api-secret: YOUR_SECRET" \
  https://volvox.bot/api/v1/guilds/987654321098765432/members/111000111

{
  "id": "111000111",
  "username": "alice",
  "displayName": "Alice",
  "avatar": "https://cdn.discordapp.com/avatars/111000111/abc.png",
  "roles": [{ "id": "123123123", "name": "Moderator", "color": "#3498db" }],
  "joinedAt": "2025-01-15T00:00:00.000Z",
  "stats": {
    "messages_sent": 2400,
    "reactions_given": 310,
    "reactions_received": 180,
    "days_active": 45,
    "first_seen": "2025-01-15T00:00:00.000Z",
    "last_active": "2026-03-21T08:00:00.000Z"
  },
  "reputation": {
    "xp": 15200,
    "level": 8,
    "messages_count": 2200,
    "voice_minutes": 480,
    "helps_given": 12,
    "last_xp_gain": "2026-03-21T08:00:00.000Z",
    "next_level_xp": 20000
  },
  "warnings": {
    "count": 0,
    "recent": []
  }
}

GET /guilds/:id/members/:userId/cases

Returns paginated moderation case history for a specific member. Authentication: API key or JWT Bearer token required.

Path parameters

string

required

The Discord guild ID.

userId

string

required

The Discord user ID.

Query parameters

page

integer

Page number. Default: 1.

limit

integer

Items per page. Default: 25. Maximum: 100.

Response fields

userId

string

The queried Discord user ID.

cases

array

Paginated list of mod cases.

total

integer

Total cases for this member.

page

integer

Current page.

pages

integer

Total pages.

Example

curl -H "x-api-secret: YOUR_SECRET" \
  https://volvox.bot/api/v1/guilds/987654321098765432/members/111000111/cases

{
  "userId": "111000111",
  "cases": [
    {
      "case_number": 5,
      "action": "warn",
      "reason": "Spam",
      "moderator_id": "222000222",
      "moderator_tag": "mod#1234",
      "duration": null,
      "expires_at": null,
      "created_at": "2026-01-10T09:00:00.000Z"
    }
  ],
  "total": 1,
  "page": 1,
  "pages": 1
}

POST /guilds/:id/members/:userId/xp

Adds or removes XP for a member. XP cannot go below 0. The member’s level is automatically recomputed after the adjustment. Authentication: API key or JWT Bearer token required.

Path parameters

string

required

The Discord guild ID.

userId

string

required

The Discord user ID.

Request body

amount

integer

required

XP adjustment. Positive to add, negative to remove. Must be non-zero and within ±1,000,000.

reason

string

Optional reason for the adjustment, logged for audit purposes.

Response fields

userId

string

The adjusted user’s Discord ID.

integer

New total XP after the adjustment.

level

integer

New level after the adjustment.

adjustment

integer

The XP amount that was applied.

reason

string | null

The provided reason, or null.

Example

curl -X POST \
  -H "x-api-secret: YOUR_SECRET" \
  -H "Content-Type: application/json" \
  -d '{"amount": 500, "reason": "Contest winner"}' \
  https://volvox.bot/api/v1/guilds/987654321098765432/members/111000111/xp

{
  "userId": "111000111",
  "xp": 15700,
  "level": 8,
  "adjustment": 500,
  "reason": "Contest winner"
}

GET /guilds/:id/members/export

Streams a CSV file containing enriched member data (stats, XP, warnings) for all guild members. Authentication: API key or JWT Bearer token required.

This endpoint may take significant time for large guilds. The response streams in batches of 1,000 members. Do not set a short timeout on the client.

Path parameters

string

required

The Discord guild ID.

Response

Returns a text/csv file with Content-Disposition: attachment; filename="members.csv". Columns: userId, username, displayName, joinedAt, messages, xp, level, daysActive, warnings.

Example

curl -H "x-api-secret: YOUR_SECRET" \
  https://volvox.bot/api/v1/guilds/987654321098765432/members/export \
  -o members.csv

Overview

Endpoints

GET /guilds/:id/members

Path parameters

Query parameters

Response fields

Example

GET /guilds/:id/members/:userId

Path parameters

Response fields

Example

GET /guilds/:id/members/:userId/cases

Path parameters

Query parameters

Response fields

Example

POST /guilds/:id/members/:userId/xp

Path parameters

Request body

Response fields

Example

GET /guilds/:id/members/export

Path parameters

Response

Example

Build docs developers (and LLMs) love

Overview

Endpoints

​GET /guilds/:id/members

​Path parameters

​Query parameters

​Response fields

​Example

​GET /guilds/:id/members/:userId

​Path parameters

​Response fields

​Example

​GET /guilds/:id/members/:userId/cases

​Path parameters

​Query parameters

​Response fields

​Example

​POST /guilds/:id/members/:userId/xp

​Path parameters

​Request body

​Response fields

​Example

​GET /guilds/:id/members/export

​Path parameters

​Response

​Example

Build docs developers (and LLMs) love

GET /guilds/:id/members

Path parameters

Query parameters

Response fields

Example

GET /guilds/:id/members/:userId

Path parameters

Response fields

Example

GET /guilds/:id/members/:userId/cases

Path parameters

Query parameters

Response fields

Example

POST /guilds/:id/members/:userId/xp

Path parameters

Request body

Response fields

Example

GET /guilds/:id/members/export

Path parameters

Response

Example