> 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"}}}}}}
```