Track Votes with the Top.gg v1 API

The votes endpoints let you retrieve a full history of votes for your project or check whether a specific user has voted recently. Vote history is returned in cursor-based pages ordered by creation date. You can also look up an individual user’s vote status by their Top.gg or Discord user ID.

GET /projects/@me/votes

Returns a cursor-paginated list of votes for your project, ordered by creation date (oldest first within each page).

curl "https://top.gg/api/v1/projects/@me/votes?startDate=2026-01-01T00:00:00Z" \
  -H "Authorization: Bearer $TOPGG_TOKEN"

You must provide either cursor or startDate on every request. If you provide cursor, startDate is ignored. startDate cannot be more than one year in the past.

Query parameters

string

Pagination cursor returned by a previous response. When provided, the API returns the next page of results. Takes precedence over startDate.

string

ISO 8601 timestamp specifying where to start fetching votes from. Required when cursor is not provided. Cannot be more than one year in the past.

Response fields

string

required

Opaque cursor string for fetching the next page. Pass this as the cursor query parameter on your next request.

object[]

required

Array of vote records.

Show Vote object properties

string

required

The Top.gg user ID of the voter.

string

required

The voter’s platform-specific user ID (e.g., their Discord user ID).

number

required

The number of votes this single action counted for (e.g., 2 on weekends for Discord bots).

string

required

ISO 8601 timestamp of when the user voted.

string

required

ISO 8601 timestamp of when the user is eligible to vote again.

Example response

{
  "cursor": "<cursor-token>",
  "data": [
    {
      "user_id": "1234567890",
      "platform_id": "1234567890",
      "weight": 1,
      "created_at": "2026-01-28T02:19:19.145733Z",
      "expires_at": "2026-01-28T14:19:19.145733Z"
    }
  ]
}

Paginating through all votes

To retrieve all votes from a given point in time, start with startDate and then use the cursor from each response for subsequent requests until you receive an empty data array.

# First request — start from a date
curl "https://top.gg/api/v1/projects/@me/votes?startDate=2026-01-01T00:00:00Z" \
  -H "Authorization: Bearer $TOPGG_TOKEN"

# Subsequent requests — use the returned cursor
curl "https://top.gg/api/v1/projects/@me/votes?cursor=<cursor-token>" \
  -H "Authorization: Bearer $TOPGG_TOKEN"

GET /projects/@me/votes/:user_id

Returns the most recent vote status for a specific user. Use this to check whether a user has voted before granting in-app rewards or unlocking features.

curl "https://top.gg/api/v1/projects/@me/votes/1234567890?source=discord" \
  -H "Authorization: Bearer $TOPGG_TOKEN"

Path parameters

string

required

The ID of the user to look up. The expected format depends on the source parameter.

Query parameters

string

default:"topgg"

The ID type being provided. Defaults to topgg. See the table below for valid values.

Source enum

Value	Description
`topgg`	The user’s Top.gg Snowflake ID (default)
`discord`	The user’s Discord Snowflake ID

Response fields

string

required

ISO 8601 timestamp of when the user last voted.

string

required

ISO 8601 timestamp of when the user can vote again. If the current time is before this value, the user has an active vote.

number

required

The number of votes the user’s last vote counted for.

Example response

{
  "created_at": "2023-10-01T12:34:56.789Z",
  "expires_at": "2023-10-01T18:34:56.789Z",
  "weight": 1
}

If the user has not voted or their vote has expired, the API returns 404 Not Found.

​GET /projects/@me/votes

​Query parameters

​Response fields

​Example response

​Paginating through all votes

​GET /projects/@me/votes/:user_id

​Path parameters

​Query parameters

​Source enum

​Response fields

​Example response

GET /projects/@me/votes

Query parameters

Response fields

Example response

Paginating through all votes

GET /projects/@me/votes/:user_id

Path parameters

Query parameters

Source enum

Response fields

Example response