Legacy Minecraft UUID proxy Local username history Cache-aware lookup flags Live DB snapshot

Legacy Minecraft - UUID Proxy

This UUID proxy is used by Legacy Minecraft services, RetroMC, and partner servers and services.

Database Snapshot

API Hits Total

18,472

Count of API requests served since this service started.

API Hits (1h)

22

API requests recorded during the last hour.

API Hits (24h)

679

API requests recorded during the last 24 hours.

Unique Users

47,998

Current active UUID -> username records in local cache.

Negative Cache Entries

889

Cached usernames currently recorded as not found.

Stale Cached Users

0

Active cached identities that are expired or already marked stale.

History Records

62,493

Observed username history rows stored locally.

Refreshed In Last 30 Days

47,998

Cached identities with a last check timestamp inside the last 30 days.

Latest Refresh / Check

Jun 3, 2026, 4:07:26 AM UTC

Most recent cache validation timestamp across positive and negative cache entries.

Mojang Error Rate (1h)

0.0%

0 errors across 3 upstream requests in the last hour.

Mojang Error Rate (8h)

0.0%

0 errors across 41 upstream requests in the last 8 hours.

Mojang Error Rate (24h)

0.0%

0 errors across 133 upstream requests in the last 24 hours.

Endpoints

GET /minecraft/profile/lookup/name/:username

Resolve a username to its current UUID, using cache first and upstream fallback when needed.

curl "https://uuid.legacyminecraft.com/minecraft/profile/lookup/name/Notch"

POST /minecraft/profile/lookup/bulk/byname

Resolve one or more usernames in one request, up to the configured bulk limit.

curl -X POST "https://uuid.legacyminecraft.com/minecraft/profile/lookup/bulk/byname"
  -H "Content-Type: application/json"
  -d "["Notch"]"

GET /cache/profile/lookup/uuid/:uuid

Read the currently cached username for a UUID without contacting upstream.

curl "https://uuid.legacyminecraft.com/cache/profile/lookup/uuid/069a79f444e94726a5befca90e38aaf5"

GET /user/profiles/:uuid/names

Return Mojang-shaped username history from names this service has locally observed for that UUID.

curl "https://uuid.legacyminecraft.com/user/profiles/069a79f444e94726a5befca90e38aaf5/names"

Name Lookup Query Flags

cacheOnly=true

Skip upstream requests entirely. Only local cache entries are used.

includeStale=true

Allow expired cached positive records to be returned immediately.

allowHistorical=true

If a current-name lookup misses, return the most recently observed UUID that used that username from local history.

curl "https://uuid.legacyminecraft.com/minecraft/profile/lookup/name/OldName?cacheOnly=true&includeStale=true&allowHistorical=true"

Cache Headers

  • X-Cache-Status reports hit, miss, stale, negative-hit, historical-hit, and related cache outcomes.
  • X-Cache-Checked-At reports when the current cached profile was last confirmed.
  • X-Cache-Expires-At reports when the current cached profile becomes stale.