L
@lookups/usernames

Examples

Learn how to check username availability across different platforms

Quick Start

Import the Client and start checking usernames in seconds:

Basic Usagetypescript
import { Client } from "@lookups/usernames";

const client = new Client({
  suggestions: {
    enabled: true,
    amount: 3,
    verification: false
  }
});

const result = await client.github("pqpcara");

console.log(result);
Output
{
  "platform": "github",
  "username": "pqpcara",
  "available": false,
  "suggestions": "pqpcara-dev, pqpcara2, or pqpcara232 are available.",
  "message": "Username pqpcara is not available."
}

Discord

Check if a username is available on Discord:

Discord Exampletypescript
import { Client } from "@lookups/usernames";

const client = new Client({
  suggestions: {
    enabled: true,
    amount: 3,
    verification: false
  }
});
const result = await client.discord("alwayswealthy");

if (result.available === true) {
  console.log(`✓ Username "${result.username}" is available!`);
} else if (result.available === false) {
  console.log(`✗ Username "${result.username}" is taken`);
  if (result.suggestions) {
    console.log(`Suggestions: ${result.suggestions}`);
  }
} else {
  console.log(`? Could not determine: ${result.message}`);
}
Output
✗ Username "alwayswealthy" is taken
Suggestions: alwayswealthy2, alwayswealthy_dev, or alwayswealthy123 are available.

GitHub

Check GitHub username availability and get suggestions:

GitHub Exampletypescript
import { Client } from "@lookups/usernames";

const client = new Client({
  suggestions: {
    enabled: true,
    amount: 3,
    verification: false
  }
});
const result = await client.github("pqpcara");

console.log(`Platform: ${result.platform}`);
console.log(`Username: ${result.username}`);
console.log(`Available: ${result.available}`);
console.log(`Message: ${result.message}`);
Output
Platform: github
Username: pqpcara
Available: false
Message: Username pqpcara is not available.

Instagram

Verify Instagram username availability:

Instagram Exampletypescript
import { Client } from "@lookups/usernames";

const client = new Client({
  suggestions: {
    enabled: true,
    amount: 3,
    verification: false
  }
});
const result = await client.instagram("muitaura");

if (result.available) {
  console.log("Username is available! Claim it now.");
} else {
  console.log("Username is already taken.");
}
Output
Username is already taken.

Minecraft

Check Minecraft (Java Edition) username availability:

Minecraft Exampletypescript
import { Client } from "@lookups/usernames";

const client = new Client({
  suggestions: {
    enabled: true,
    amount: 3,
    verification: false
  }
});
const result = await client.minecraft("Notch");

console.log(result);
Output
{
  "platform": "minecraft",
  "username": "Notch",
  "available": false,
  "message": "Username Notch is not available."
}

Roblox

Check Roblox username availability:

Roblox Exampletypescript
import { Client } from "@lookups/usernames";

const client = new Client({
  suggestions: {
    enabled: true,
    amount: 3,
    verification: false
  }
});
const result = await client.roblox("builderman");

console.log(`Checking: ${result.username}`);
console.log(`Status: ${result.available ? "Available" : "Taken"}`);
Output
Checking: builderman
Status: Taken

Check Multiple Platforms

Check the same username across all supported platforms simultaneously:

Multi-Platform Checktypescript
import { Client } from "@lookups/usernames";

const client = new Client({
  suggestions: {
    enabled: true,
    amount: 3,
    verification: false
  }
});
const username = "myusername";

const [discord, github, instagram, minecraft, roblox] = await Promise.all([
  client.discord(username),
  client.github(username),
  client.instagram(username),
  client.minecraft(username),
  client.roblox(username),
]);

console.log({
  discord: discord.available,
  github: github.available,
  instagram: instagram.available,
  minecraft: minecraft.available,
  roblox: roblox.available,
});
Output
{
  discord: true,
  github: false,
  instagram: true,
  minecraft: false,
  roblox: true
}

Batch Checking with Rate Limiting

Check multiple usernames with proper rate limiting to avoid API restrictions:

Batch Check with Delaystypescript
import { Client } from "@lookups/usernames";

const client = new Client({
  suggestions: {
    enabled: true,
    amount: 3,
    verification: false
  }
});

async function checkUsernames(usernames: string[], platform: string) {
  const results = [];
  
  for (const username of usernames) {
    const result = await client[platform](username);
    results.push(result);
    
    await new Promise(resolve => 
      setTimeout(resolve, 500 + Math.random() * 500)
    );
  }
  
  return results;
}

const usernames = ["user1", "user2", "user3", "user4"];
const githubResults = await checkUsernames(usernames, "github");

githubResults.forEach(result => {
  console.log(`${result.username}: ${result.available ? "✓" : "✗"}`);
});
Output
user1: ✗
user2: ✓
user3: ✗
user4: ✓

Error Handling

Handle errors and undetermined results gracefully:

Robust Error Handlingtypescript
import { Client } from "@lookups/usernames";

const client = new Client({
  suggestions: {
    enabled: true,
    amount: 3,
    verification: false
  }
});

async function safeCheck(username: string) {
  try {
    const result = await client.github(username);
    
    if (result.available === true) {
      return { status: "available", username };
    } else if (result.available === false) {
      return { 
        status: "unavailable", 
        username,
        suggestions: result.suggestions 
      };
    } else {
      return { 
        status: "unknown", 
        username,
        message: result.message 
      };
    }
  } catch (error) {
    return { 
      status: "error", 
      username,
      error: error.message 
    };
  }
}

const result = await safeCheck("testuser");
console.log(result);
Output
{
  status: "available",
  username: "testuser"
}

Next Steps

Explore the full API reference to learn about all available methods, response types, and advanced options.

API ReferenceView Changelog