User Endpoints — Top.gg v0 API

The user endpoints let you look up public profile information for any Top.gg user by their Discord user ID. This is useful for displaying voter profiles, verifying user roles, or surfacing social links within your own application.

GET /users/:user_id

Returns public profile data for the Top.gg user associated with the given Discord user ID.

curl -X GET https://top.gg/api/users/140862798832861184 \
  -H "Content-Type: application/json" \
  -H "Authorization: your-topgg-token"

Path parameters

string

required

The Discord Snowflake ID of the user to look up.

Response fields

string

required

The user’s Discord Snowflake ID.

string

required

The user’s Discord username.

string

required

The user’s Discord discriminator (e.g., "0001").

string

The user’s Discord avatar hash. Absent if the user has no custom avatar.

string

required

The CDN hash for the user’s default (generated) avatar, used as a fallback when avatar is absent.

string

The user’s Top.gg profile bio. Absent if not set.

string

URL of the user’s profile banner image. Absent if not set.

An object containing the user’s linked social accounts. All sub-fields are optional and absent when not set.

Show Social fields

string

YouTube channel URL or handle.

string

Reddit username.

string

Twitter/X handle.

string

Instagram handle.

string

GitHub username.

string

The user’s custom profile color as a hex string (e.g., "#ff6347"). This value is user-supplied and is not guaranteed to be a valid hex color.

boolean

required

Whether the user is a Top.gg supporter.

boolean

required

Whether the user is a Top.gg certified developer.

boolean

required

Whether the user is a Top.gg moderator.

boolean

required

Whether the user is a Top.gg web moderator.

boolean

required

Whether the user is a Top.gg administrator.

Example response

{
  "discriminator": "0001",
  "avatar": "a_1241439d430def25c100dd28add2d42f",
  "id": "140862798832861184",
  "username": "Xetera",
  "defAvatar": "322c936a8c8be1b803cd94861bdfa868",
  "admin": true,
  "webMod": true,
  "mod": true,
  "certifiedDev": false,
  "supporter": false,
  "social": {}
}

Returns 404 Not Found if no Top.gg profile exists for the given Discord user ID.

v1 API

Legacy v0 API

User Endpoints — Top.gg v0 API

GET /users/:user_id

Path parameters

Response fields

Example response