> For the complete documentation index, see [llms.txt](https://docs.discordtop.net/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.discordtop.net/api-reference/api-v7/votes.md).
# Votes
Vérification et consultation des votes utilisateurs.
## Vérifier si un utilisateur est en cooldown de vote
> Vérifie si un utilisateur, via \`discord\_id\` ou \`external\_id\`, a voté pour la guilde associée\
> au token développeur dans la dernière heure.\
> \
> \*\*Important :\*\*\
> \- Un seul identifiant doit être fourni.\
> \- Le cooldown est fixé à \*\*1h\*\*.\
> \- Le token doit être passé en Bearer ou via \`X-Api-Token\`.\
> \- Le paramètre \`api\_token\` reste supporté pour compatibilité, mais son usage est déconseillé.
```json
{"openapi":"3.0.3","info":{"title":"DiscordTop Developer API - Version 7","version":"7.0"},"tags":[{"name":"Votes","description":"Vérification et consultation des votes utilisateurs."}],"servers":[{"url":"https://api.discordtop.net/v7","description":"API Developer - Production (v7)"}],"security":[{"ApiTokenAuth":[]}],"components":{"securitySchemes":{"ApiTokenAuth":{"type":"http","scheme":"bearer","bearerFormat":"DTOP-Dev-Token"}},"parameters":{"DiscordIdQuery":{"name":"discord_id","in":"query","required":false,"description":"ID Discord de l'utilisateur à vérifier.","schema":{"type":"string","maxLength":20,"pattern":"^[0-9]{15,20}$"}},"ExternalIdQuery":{"name":"external_id","in":"query","required":false,"description":"Identifiant externe de l'utilisateur.","schema":{"type":"string","maxLength":191}},"ApiTokenQuery":{"name":"api_token","in":"query","required":false,"description":"Ancienne méthode pour passer le token dans l'URL.\nIl est recommandé d'utiliser `Authorization: Bearer `.\n","schema":{"type":"string"},"deprecated":true},"LocaleQuery":{"name":"locale","in":"query","required":false,"description":"Force la langue de la réponse (`fr`, `en`, etc.).\nSi absent : utilise `X-Locale`, puis `Accept-Language`, sinon fallback `en`.\n","schema":{"type":"string"}},"XLocaleHeader":{"name":"X-Locale","in":"header","required":false,"description":"Locale forcée, surpasse `Accept-Language`.","schema":{"type":"string"}},"AcceptLanguageHeader":{"name":"Accept-Language","in":"header","required":false,"description":"Détection automatique de la langue.","schema":{"type":"string"}},"XApiTokenHeader":{"name":"X-Api-Token","in":"header","required":false,"description":"Token développeur alternatif.","schema":{"type":"string"}}},"schemas":{"VoteCheckSuccess":{"type":"object","required":["ok","guild_id","has_voted","is_doubled","last_vote_at","next_vote_at","cooldown_remaining_seconds"],"properties":{"ok":{"type":"boolean"},"guild_id":{"type":"string"},"has_voted":{"type":"boolean","description":"`true` : l'utilisateur est encore dans le cooldown.\n`false` : aucun vote récent ou cooldown terminé.\n"},"is_doubled":{"type":"boolean","description":"Indique si le vote d'un utilisateur est considéré comme doublé."},"last_vote_at":{"type":"string","format":"date-time","nullable":true},"next_vote_at":{"type":"string","format":"date-time","nullable":true},"cooldown_remaining_seconds":{"type":"integer"}}},"ErrorResponse":{"type":"object","required":["ok","error","message"],"properties":{"ok":{"type":"boolean"},"error":{"type":"string"},"message":{"type":"string"}}},"ValidationError":{"type":"object","properties":{"errors":{"type":"array","items":{"type":"object","properties":{"rule":{"type":"string"},"field":{"type":"string"},"message":{"type":"string"}}}}}},"RateLimitError":{"type":"object","properties":{"message":{"type":"string"}}},"ServerError":{"type":"object","properties":{"message":{"type":"string"}}}},"responses":{"UnauthorizedApiToken":{"description":"Erreurs liées au token développeur.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"ValidationError":{"description":"Erreurs de validation Adonis Validator.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationError"}}}},"RateLimitExceeded":{"description":"Rate limit atteint.","headers":{"Retry-After":{"description":"Nombre de secondes à attendre avant de refaire une requête.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RateLimitError"}}}},"InternalServerError":{"description":"Erreur interne de l'API.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ServerError"}}}}}},"paths":{"/vote-check":{"get":{"tags":["Votes"],"operationId":"voteCheck","summary":"Vérifier si un utilisateur est en cooldown de vote","description":"Vérifie si un utilisateur, via `discord_id` ou `external_id`, a voté pour la guilde associée\nau token développeur dans la dernière heure.\n\n**Important :**\n- Un seul identifiant doit être fourni.\n- Le cooldown est fixé à **1h**.\n- Le token doit être passé en Bearer ou via `X-Api-Token`.\n- Le paramètre `api_token` reste supporté pour compatibilité, mais son usage est déconseillé.\n","parameters":[{"$ref":"#/components/parameters/DiscordIdQuery"},{"$ref":"#/components/parameters/ExternalIdQuery"},{"$ref":"#/components/parameters/ApiTokenQuery"},{"$ref":"#/components/parameters/LocaleQuery"},{"$ref":"#/components/parameters/XLocaleHeader"},{"$ref":"#/components/parameters/AcceptLanguageHeader"},{"$ref":"#/components/parameters/XApiTokenHeader"}],"responses":{"200":{"description":"Résultat de vérification du vote.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/VoteCheckSuccess"}}}},"400":{"description":"Erreurs liées aux identifiants fournis.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"$ref":"#/components/responses/UnauthorizedApiToken"},"422":{"$ref":"#/components/responses/ValidationError"},"429":{"$ref":"#/components/responses/RateLimitExceeded"},"500":{"$ref":"#/components/responses/InternalServerError"}}}}}}
```
## Récupérer les votes récents de sa guilde
> Retourne la liste des votes de la guilde associée au token développeur sur une période donnée.\
> \
> \*\*Important :\*\*\
> \- Cette route est réservée aux serveurs Premium.\
> \- La période demandée ne peut pas dépasser \*\*31 jours\*\*.\
> \- Les votes sont triés par \`timestamp\` croissant.\
> \- La pagination utilise un curseur opaque (\`next\_cursor\`).\
> \- Le champ \`is\_doubled\` indique si le vote est considéré comme doublé.\
> \- Aucune donnée personnelle autre que l'ID Discord de l'utilisateur n'est retournée.
```json
{"openapi":"3.0.3","info":{"title":"DiscordTop Developer API - Version 7","version":"7.0"},"tags":[{"name":"Votes","description":"Vérification et consultation des votes utilisateurs."}],"servers":[{"url":"https://api.discordtop.net/v7","description":"API Developer - Production (v7)"}],"security":[{"ApiTokenAuth":[]}],"components":{"securitySchemes":{"ApiTokenAuth":{"type":"http","scheme":"bearer","bearerFormat":"DTOP-Dev-Token"}},"parameters":{"FromQuery":{"name":"from","in":"query","required":false,"description":"Date de début de la période à récupérer.\n\nFormat recommandé : ISO 8601.\nSi absent, l'API peut utiliser le début du mois courant.\n","schema":{"type":"string","format":"date-time"}},"ToQuery":{"name":"to","in":"query","required":false,"description":"Date de fin de la période à récupérer.\n\nFormat recommandé : ISO 8601.\nSi absent, l'API peut utiliser la date courante.\n","schema":{"type":"string","format":"date-time"}},"CursorQuery":{"name":"cursor","in":"query","required":false,"description":"Curseur opaque retourné par `pagination.next_cursor`.\nÀ réutiliser tel quel pour récupérer la page suivante.\n","schema":{"type":"string"}},"LimitQuery":{"name":"limit","in":"query","required":false,"description":"Nombre maximum d'éléments retournés.\nValeur par défaut : 100.\nValeur maximum : 1000.\n","schema":{"type":"integer","minimum":1,"maximum":1000,"default":100}},"ApiTokenQuery":{"name":"api_token","in":"query","required":false,"description":"Ancienne méthode pour passer le token dans l'URL.\nIl est recommandé d'utiliser `Authorization: Bearer `.\n","schema":{"type":"string"},"deprecated":true},"LocaleQuery":{"name":"locale","in":"query","required":false,"description":"Force la langue de la réponse (`fr`, `en`, etc.).\nSi absent : utilise `X-Locale`, puis `Accept-Language`, sinon fallback `en`.\n","schema":{"type":"string"}},"XLocaleHeader":{"name":"X-Locale","in":"header","required":false,"description":"Locale forcée, surpasse `Accept-Language`.","schema":{"type":"string"}},"AcceptLanguageHeader":{"name":"Accept-Language","in":"header","required":false,"description":"Détection automatique de la langue.","schema":{"type":"string"}},"XApiTokenHeader":{"name":"X-Api-Token","in":"header","required":false,"description":"Token développeur alternatif.","schema":{"type":"string"}}},"schemas":{"GuildVotesSuccess":{"allOf":[{"$ref":"#/components/schemas/VotesListBaseSuccess"},{"type":"object","required":["guild_id"],"properties":{"guild_id":{"type":"string"}}}]},"VotesListBaseSuccess":{"type":"object","required":["ok","votes","total","pagination","period"],"properties":{"ok":{"type":"boolean"},"votes":{"type":"array","description":"Liste des votes logiques retournés pour la page courante.","items":{"$ref":"#/components/schemas/VoteEvent"}},"total":{"type":"integer","description":"Nombre total de votes logiques correspondant aux filtres demandés, sur la période.\nCe total n'est pas limité par `pagination.limit`.\n"},"pagination":{"$ref":"#/components/schemas/CursorPagination"},"period":{"$ref":"#/components/schemas/Period"}}},"VoteEvent":{"type":"object","required":["user_id","timestamp","is_doubled"],"properties":{"user_id":{"type":"string","description":"ID Discord de l'utilisateur ayant voté."},"timestamp":{"type":"string","format":"date-time","description":"Date du vote."},"is_doubled":{"type":"boolean","description":"Indique si ce vote est considéré comme doublé.\n\nTant qu'aucune colonne dédiée n'existe en base de données, cette valeur peut être déduite\npar l'API à partir de deux votes similaires dans un lapse de temps très court.\n"}}},"CursorPagination":{"type":"object","required":["limit","has_more","next_cursor"],"properties":{"limit":{"type":"integer"},"has_more":{"type":"boolean"},"next_cursor":{"type":"string","nullable":true,"description":"Curseur à utiliser pour récupérer la page suivante. Null s'il n'y a plus de page."}}},"Period":{"type":"object","required":["from","to"],"properties":{"from":{"type":"string","format":"date-time"},"to":{"type":"string","format":"date-time"}}},"ErrorResponse":{"type":"object","required":["ok","error","message"],"properties":{"ok":{"type":"boolean"},"error":{"type":"string"},"message":{"type":"string"}}},"ValidationError":{"type":"object","properties":{"errors":{"type":"array","items":{"type":"object","properties":{"rule":{"type":"string"},"field":{"type":"string"},"message":{"type":"string"}}}}}},"RateLimitError":{"type":"object","properties":{"message":{"type":"string"}}},"ServerError":{"type":"object","properties":{"message":{"type":"string"}}}},"responses":{"UnauthorizedApiToken":{"description":"Erreurs liées au token développeur.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"PremiumRequired":{"description":"La guilde associée au token n'a pas accès à cette route.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"ValidationError":{"description":"Erreurs de validation Adonis Validator.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationError"}}}},"RateLimitExceeded":{"description":"Rate limit atteint.","headers":{"Retry-After":{"description":"Nombre de secondes à attendre avant de refaire une requête.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RateLimitError"}}}},"InternalServerError":{"description":"Erreur interne de l'API.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ServerError"}}}}}},"paths":{"/guild/votes":{"get":{"tags":["Votes"],"operationId":"listGuildVotes","summary":"Récupérer les votes récents de sa guilde","description":"Retourne la liste des votes de la guilde associée au token développeur sur une période donnée.\n\n**Important :**\n- Cette route est réservée aux serveurs Premium.\n- La période demandée ne peut pas dépasser **31 jours**.\n- Les votes sont triés par `timestamp` croissant.\n- La pagination utilise un curseur opaque (`next_cursor`).\n- Le champ `is_doubled` indique si le vote est considéré comme doublé.\n- Aucune donnée personnelle autre que l'ID Discord de l'utilisateur n'est retournée.\n","parameters":[{"$ref":"#/components/parameters/FromQuery"},{"$ref":"#/components/parameters/ToQuery"},{"$ref":"#/components/parameters/CursorQuery"},{"$ref":"#/components/parameters/LimitQuery"},{"$ref":"#/components/parameters/ApiTokenQuery"},{"$ref":"#/components/parameters/LocaleQuery"},{"$ref":"#/components/parameters/XLocaleHeader"},{"$ref":"#/components/parameters/AcceptLanguageHeader"},{"$ref":"#/components/parameters/XApiTokenHeader"}],"responses":{"200":{"description":"Liste paginée des votes de la guilde.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GuildVotesSuccess"}}}},"400":{"description":"Erreurs liées aux dates ou au curseur.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"$ref":"#/components/responses/UnauthorizedApiToken"},"403":{"$ref":"#/components/responses/PremiumRequired"},"422":{"$ref":"#/components/responses/ValidationError"},"429":{"$ref":"#/components/responses/RateLimitExceeded"},"500":{"$ref":"#/components/responses/InternalServerError"}}}}}}
```
## Récupérer les votes récents d'un utilisateur sur sa guilde
> Retourne la liste des votes d'un utilisateur précis sur la guilde associée au token développeur.\
> \
> \*\*Important :\*\*\
> \- Cette route est réservée aux serveurs Premium.\
> \- La période demandée ne peut pas dépasser \*\*31 jours\*\*.\
> \- Le \`user\_id\` est l'ID Discord de l'utilisateur.\
> \- Les votes sont triés par \`timestamp\` croissant.\
> \- La pagination utilise un curseur opaque (\`next\_cursor\`).\
> \- Aucune donnée personnelle autre que l'ID Discord de l'utilisateur n'est retournée.
```json
{"openapi":"3.0.3","info":{"title":"DiscordTop Developer API - Version 7","version":"7.0"},"tags":[{"name":"Votes","description":"Vérification et consultation des votes utilisateurs."}],"servers":[{"url":"https://api.discordtop.net/v7","description":"API Developer - Production (v7)"}],"security":[{"ApiTokenAuth":[]}],"components":{"securitySchemes":{"ApiTokenAuth":{"type":"http","scheme":"bearer","bearerFormat":"DTOP-Dev-Token"}},"parameters":{"FromQuery":{"name":"from","in":"query","required":false,"description":"Date de début de la période à récupérer.\n\nFormat recommandé : ISO 8601.\nSi absent, l'API peut utiliser le début du mois courant.\n","schema":{"type":"string","format":"date-time"}},"ToQuery":{"name":"to","in":"query","required":false,"description":"Date de fin de la période à récupérer.\n\nFormat recommandé : ISO 8601.\nSi absent, l'API peut utiliser la date courante.\n","schema":{"type":"string","format":"date-time"}},"CursorQuery":{"name":"cursor","in":"query","required":false,"description":"Curseur opaque retourné par `pagination.next_cursor`.\nÀ réutiliser tel quel pour récupérer la page suivante.\n","schema":{"type":"string"}},"LimitQuery":{"name":"limit","in":"query","required":false,"description":"Nombre maximum d'éléments retournés.\nValeur par défaut : 100.\nValeur maximum : 1000.\n","schema":{"type":"integer","minimum":1,"maximum":1000,"default":100}},"ApiTokenQuery":{"name":"api_token","in":"query","required":false,"description":"Ancienne méthode pour passer le token dans l'URL.\nIl est recommandé d'utiliser `Authorization: Bearer `.\n","schema":{"type":"string"},"deprecated":true},"LocaleQuery":{"name":"locale","in":"query","required":false,"description":"Force la langue de la réponse (`fr`, `en`, etc.).\nSi absent : utilise `X-Locale`, puis `Accept-Language`, sinon fallback `en`.\n","schema":{"type":"string"}},"XLocaleHeader":{"name":"X-Locale","in":"header","required":false,"description":"Locale forcée, surpasse `Accept-Language`.","schema":{"type":"string"}},"AcceptLanguageHeader":{"name":"Accept-Language","in":"header","required":false,"description":"Détection automatique de la langue.","schema":{"type":"string"}},"XApiTokenHeader":{"name":"X-Api-Token","in":"header","required":false,"description":"Token développeur alternatif.","schema":{"type":"string"}}},"schemas":{"GuildUserVotesSuccess":{"allOf":[{"$ref":"#/components/schemas/VotesListBaseSuccess"},{"type":"object","required":["guild_id","user_id"],"properties":{"guild_id":{"type":"string"},"user_id":{"type":"string","description":"ID Discord de l'utilisateur demandé."}}}]},"VotesListBaseSuccess":{"type":"object","required":["ok","votes","total","pagination","period"],"properties":{"ok":{"type":"boolean"},"votes":{"type":"array","description":"Liste des votes logiques retournés pour la page courante.","items":{"$ref":"#/components/schemas/VoteEvent"}},"total":{"type":"integer","description":"Nombre total de votes logiques correspondant aux filtres demandés, sur la période.\nCe total n'est pas limité par `pagination.limit`.\n"},"pagination":{"$ref":"#/components/schemas/CursorPagination"},"period":{"$ref":"#/components/schemas/Period"}}},"VoteEvent":{"type":"object","required":["user_id","timestamp","is_doubled"],"properties":{"user_id":{"type":"string","description":"ID Discord de l'utilisateur ayant voté."},"timestamp":{"type":"string","format":"date-time","description":"Date du vote."},"is_doubled":{"type":"boolean","description":"Indique si ce vote est considéré comme doublé.\n\nTant qu'aucune colonne dédiée n'existe en base de données, cette valeur peut être déduite\npar l'API à partir de deux votes similaires dans un lapse de temps très court.\n"}}},"CursorPagination":{"type":"object","required":["limit","has_more","next_cursor"],"properties":{"limit":{"type":"integer"},"has_more":{"type":"boolean"},"next_cursor":{"type":"string","nullable":true,"description":"Curseur à utiliser pour récupérer la page suivante. Null s'il n'y a plus de page."}}},"Period":{"type":"object","required":["from","to"],"properties":{"from":{"type":"string","format":"date-time"},"to":{"type":"string","format":"date-time"}}},"ErrorResponse":{"type":"object","required":["ok","error","message"],"properties":{"ok":{"type":"boolean"},"error":{"type":"string"},"message":{"type":"string"}}},"ValidationError":{"type":"object","properties":{"errors":{"type":"array","items":{"type":"object","properties":{"rule":{"type":"string"},"field":{"type":"string"},"message":{"type":"string"}}}}}},"RateLimitError":{"type":"object","properties":{"message":{"type":"string"}}},"ServerError":{"type":"object","properties":{"message":{"type":"string"}}}},"responses":{"UnauthorizedApiToken":{"description":"Erreurs liées au token développeur.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"PremiumRequired":{"description":"La guilde associée au token n'a pas accès à cette route.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"ValidationError":{"description":"Erreurs de validation Adonis Validator.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationError"}}}},"RateLimitExceeded":{"description":"Rate limit atteint.","headers":{"Retry-After":{"description":"Nombre de secondes à attendre avant de refaire une requête.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RateLimitError"}}}},"InternalServerError":{"description":"Erreur interne de l'API.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ServerError"}}}}}},"paths":{"/guild/votes/users/{user_id}":{"get":{"tags":["Votes"],"operationId":"listGuildUserVotes","summary":"Récupérer les votes récents d'un utilisateur sur sa guilde","description":"Retourne la liste des votes d'un utilisateur précis sur la guilde associée au token développeur.\n\n**Important :**\n- Cette route est réservée aux serveurs Premium.\n- La période demandée ne peut pas dépasser **31 jours**.\n- Le `user_id` est l'ID Discord de l'utilisateur.\n- Les votes sont triés par `timestamp` croissant.\n- La pagination utilise un curseur opaque (`next_cursor`).\n- Aucune donnée personnelle autre que l'ID Discord de l'utilisateur n'est retournée.\n","parameters":[{"name":"user_id","in":"path","required":true,"description":"ID Discord de l'utilisateur dont les votes doivent être récupérés.","schema":{"type":"string","maxLength":20,"pattern":"^[0-9]{15,20}$"}},{"$ref":"#/components/parameters/FromQuery"},{"$ref":"#/components/parameters/ToQuery"},{"$ref":"#/components/parameters/CursorQuery"},{"$ref":"#/components/parameters/LimitQuery"},{"$ref":"#/components/parameters/ApiTokenQuery"},{"$ref":"#/components/parameters/LocaleQuery"},{"$ref":"#/components/parameters/XLocaleHeader"},{"$ref":"#/components/parameters/AcceptLanguageHeader"},{"$ref":"#/components/parameters/XApiTokenHeader"}],"responses":{"200":{"description":"Liste paginée des votes de l'utilisateur sur la guilde.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GuildUserVotesSuccess"}}}},"400":{"description":"Erreurs liées à l'utilisateur, aux dates ou au curseur.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"$ref":"#/components/responses/UnauthorizedApiToken"},"403":{"$ref":"#/components/responses/PremiumRequired"},"422":{"$ref":"#/components/responses/ValidationError"},"429":{"$ref":"#/components/responses/RateLimitExceeded"},"500":{"$ref":"#/components/responses/InternalServerError"}}}}}}
```
---
# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.
## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.
Perform an HTTP GET request on the current page URL with the `ask` query parameter:
```
GET https://docs.discordtop.net/api-reference/api-v7/votes.md?ask=
```
The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.
Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.