API Documentation
Learn how to integrate Discord user status data into your applications
Getting Started
Quick start guide to using the Discord Status API
Base URL
https://discordstatus.xyz/api
Authentication
No authentication required. All endpoints are publicly accessible with rate limiting.
Get User Status
Retrieve comprehensive Discord user information and status
GET
/users/{id}
Get real-time status, activities, and profile information for a Discord user
Parameters
Parameter
Type
Description
id
string
Discord user ID (17-19 digits)
Example Request
GET /api/users/1208329627391627284
Example Response
{ "user": { "id": "1208329627391627284", "username": "connector", "globalName": null, "discriminator": "0", "avatar": "d3809e77d1ccac26bb5958e6c1d47802", "avatarURL": "https://cdn.discordapp.com/avatars/...", "displayAvatarURL": "https://cdn.discordapp.com/avatars/...", "banner": null, "bannerURL": null, "accentColor": 1052688, "hexAccentColor": "#101010", "bot": false, "createdTimestamp": 1708158632849 }, "presence": "online", "activities": [ { "name": "Custom Status", "type": 4, "details": null, "state": "pm for dev work.", "timestamps": null, "assets": null, "emoji": { "animated": false, "name": "developer", "id": "1363253738395009154", "imageURL": "https://cdn.discordapp.com/emojis/..." }, "applicationId": null } ], "customStatus": { "text": "pm for dev work.", "emoji": { "name": "developer", "id": "1363253738395009154", "animated": false, "imageURL": "https://cdn.discordapp.com/emojis/..." } }, "timestamp": "2024-01-15T10:30:00.000Z" }
Response Fields
Understanding the API response structure
User Object
id
- Discord user IDusername
- User's usernameglobalName
- User's display nameavatarURL
- User's avatar image URLpresence
- online, offline, idle, or dndActivity Types
0
- Playing (game)1
- Streaming2
- Listening (Spotify)3
- Watching4
- Custom Status5
- CompetingCode Examples
Implementation examples in popular programming languages
JavaScript (Fetch)
async function getDiscordUser(userId) { try { const response = await fetch( `https://discordstatus.xyz/api/users/${userId}` ); if (!response.ok) { throw new Error(`HTTP error! status: ${response.status}`); } const userData = await response.json(); console.log('User Status:', userData.presence); console.log('Custom Status:', userData.customStatus?.text); return userData; } catch (error) { console.error('Error fetching user data:', error); } } getDiscordUser('1208329627391627284');
Python (Requests)
import requests import json def get_discord_user(user_id): try: url = f"https://discordstatus.xyz/api/users/{user_id}" response = requests.get(url) response.raise_for_status() user_data = response.json() print(f"User Status: {user_data['presence']}") if user_data.get('customStatus'): print(f"Custom Status: {user_data['customStatus']['text']}") return user_data except requests.exceptions.RequestException as e: print(f"Error fetching user data: {e}") get_discord_user('1208329627391627284')
Node.js (Axios)
const axios = require('axios'); async function getDiscordUser(userId) { try { const response = await axios.get( `https://discordstatus.xyz/api/users/${userId}` ); const userData = response.data; console.log('User Status:', userData.presence); if (userData.customStatus) { console.log('Custom Status:', userData.customStatus.text); if (userData.customStatus.emoji) { console.log('Emoji:', userData.customStatus.emoji.name); } } return userData; } catch (error) { console.error('Error:', error.response?.data || error.message); } } getDiscordUser('1208329627391627284');
Error Handling
Understanding API errors and how to handle them
HTTP Status Codes
200
Success - User data retrieved400
Bad Request - Invalid user ID format404
Not Found - User not found or not tracked429
Too Many Requests - Rate limit exceeded500
Internal Server Error502
Bad Gateway - External service errorError Response Format
{ "error": "User not found", "message": "The specified Discord user could not be found or is not being tracked" }
Rate Limits
API usage limits and best practices
Rate Limit
60 requests per minute
Cache Duration
30 seconds
Responses are cached for 30 seconds to improve performance. Making multiple requests for the same user within this window will return cached data.