Documentation
Everything you need to know about using Pomelo
What is Pomelo?
Pomelo is a fast and reliable Discord username availability checker. It helps you find available usernames on Discord's new username system (introduced in 2023) by checking against Discord's API in real-time.
With Discord's transition from discriminators (#1234) to unique usernames (@username), finding an available username has become more challenging. Pomelo solves this by providing instant availability checks and intelligent suggestions.
Getting Started
Using Pomelo is simple:
- Enter your desired username in the search box
- Click "Check" to see if it's available
- Get instant results with suggestions if taken
- Configure settings for personalized experience
API Documentation
Base URL
Check Username Availability
Request Body
{
"username": "your_username",
"publicLookup": true,
"useCache": true,
"includeSuggestions": true,
"includeUser": true
}Request Body Fields
- • Must be 2-32 characters long
- • Only lowercase letters, numbers, underscores, and periods allowed
- • Cannot contain repeating dots (..)
- • Cannot contain blacklisted words
- • Setting to
falserequires Pro Plan - •
trueuses cache when available for faster results
An invalid body will throw an status code 400.
Response
{
"duration": 150,
"data": {
"status": "TAKEN",
"servedFrom": "DISCORD_LIVE",
"suggestions": ["username1", "username2"],
"user": {
"id": "1003363485289283684",
"username": "lixqadev",
"globalName": "Lixqa Development",
"avatar": "431dd648e5a12462775adfa676d59aec"
}
}
}Response Fields
- •
"AVAILABLE": Username is available for registration - •
"TAKEN": Username is already registered by a user - •
"RESERVED": Username is reserved by Discord
- •
"UNKNOWN": Unknown source - •
"MEMORY_CACHE": Served from memory cache - •
"DATABASE_LOOKUPS_CACHE": Served from database cache - •
"DATABASE_USERNAMES_CACHE": Served from username cache - •
"DISCORD_LIVE": Real-time data from Discord
- • User object: Full Discord user information (premium feature)
- •
"REDACTED": User exists but details are hidden (upgrade required) - •
"DISABLED": User lookup was disabled viaincludeUser: false - •
null: No user found or username is available
includeSuggestions: true)Lookup User by Discord ID
Request Body
{
"discordId": "1003363485289283684"
}Request Body Fields
- • Must be a valid Discord snowflake ID (numeric string)
- • Typically 17-19 digits long
An invalid body will throw an status code 400.
Response (User Found)
{
"duration": 150,
"data": {
"servedFrom": "DISCORD_LIVE",
"user": {
"id": "1003363485289283684",
"username": "lixqadev",
"globalName": "Lixqa Development",
"avatar": "431dd648e5a12462775adfa676d59aec",
"banner": "banner_hash",
"accentColor": 5814783,
"discriminator": "0001",
"bot": false,
"flags": ["VERIFIED_BOT"]
}
}
}Response (User Not Found)
{
"duration": 150,
"data": null
}Response Fields
- •
null: User ID not found or doesn't exist - • Object: Contains user information when found
- •
"UNKNOWN": Unknown source - •
"MEMORY_CACHE": Served from memory cache - •
"DATABASE_LOOKUPS_CACHE": Served from database cache - •
"DATABASE_USERNAMES_CACHE": Served from username cache - •
"DISCORD_LIVE": Real-time data from Discord
- • User object: Full Discord user information
- •
null: User not found - • Contains:
id,username,globalName,avatar,banner,accentColor,discriminator,bot,flags
Authentication
For premium features like Discord user information, include your API key in the Authorization header:
Join our Discord server to discuss API access and pricing options.
Rate Limits
Rate limits will throw an status code 429.
The free tier allows 2 requests per 10 seconds. Premium tiers have increased limits and additional features like Discord user information. Join our Discord server to discuss custom rate limits and pricing.
Note: Special or short usernames may have stricter limits or be disabled under certain conditions.
Features
Real-time Checking
Get instant results by checking directly against Discord's servers.
Smart Caching
Cached results for faster responses when real-time isn't needed.
Developer API
RESTful API for integrating username checks into your applications.
Privacy Focused
No personal data stored. Optional analytics can be disabled.
Discord User Info
Premium feature that shows Discord user details when a username is taken.
How We Work & How You Can Help
Pomelo operates as a large-scale database that powers our username availability checking service. When caching is enabled (especially for free users), the cached username database depends on data collected from various sources, including voluntary contributions from our community and partners.
Our database is built through a combination of web scraping, API integrations, and most importantly, voluntary data sharing from users who want to help our mission. This collaborative approach allows us to provide faster, cached results while reducing the load on Discord's servers.
Important: If you're a premium user or have caching disabled, all data is served live directly from Discord's API, ensuring real-time accuracy without relying on our cached database.
Want to Contribute?
If you're interested in sharing user data with us to help improve our database and support our mission, we'd love to hear from you! Contributors may receive premium benefits or other rewards as a token of our appreciation.
We also accept cryptocurrency donations to help support the infrastructure and development of Pomelo. For data sharing partnerships or donation information, please contact us via email or join our Discord server.