Skip to main content
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

​
cursor
string
Pagination cursor returned by a previous response. When provided, the API returns the next page of results. Takes precedence over startDate.
​
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

​
cursor
string
required
Opaque cursor string for fetching the next page. Pass this as the cursor query parameter on your next request.
​
data
object[]
required
Array of vote records.

​
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

​
user_id
string
required
The ID of the user to look up. The expected format depends on the source parameter.

​
Query parameters

​
source
string
default:"topgg"
The ID type being provided. Defaults to topgg. See the table below for valid values.

​
Source enum

ValueDescription
topggThe user’s Top.gg Snowflake ID (default)
discordThe user’s Discord Snowflake ID

​
Response fields

​
created_at
string
required
ISO 8601 timestamp of when the user last voted.
​
expires_at
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.
​
weight
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.