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 ID
username - User's username
globalName - User's display name
avatarURL - User's avatar image URL
presence - online, offline, idle, or dnd

Activity Types

0 - Playing (game)
1 - Streaming
2 - Listening (Spotify)
3 - Watching
4 - Custom Status
5 - Competing
Code 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

200Success - User data retrieved
400Bad Request - Invalid user ID format
404Not Found - User not found or not tracked
429Too Many Requests - Rate limit exceeded
500Internal Server Error
502Bad Gateway - External service error

Error 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.

Ready to start building?

Try out the API with our interactive search tool