PlayerDB Minecraft Profile Lookup

Resolve batches of Minecraft usernames or UUIDs into clean, integration-ready identity records. This Actor uses the public PlayerDB Minecraft API and exports canonical usernames, formatted and raw UUIDs, avatar URLs, skin and cape texture URLs, decoded texture metadata, cache timestamps, name history when available, and a status for each processed input. Ordered results are saved progressively; charge limits or interruption can leave a partial prefix.

Use it when a moderation list, game-server tool, community bot, or data pipeline needs repeatable PlayerDB Minecraft profiles rather than raw API responses.

What this Actor does

For each supplied Minecraft Java Edition username or UUID, the Actor:

1. validates the identifier before making requests;
2. resolves it through PlayerDB;
3. extracts direct skin/cape URLs with decoded texture-property fallback (without verifying its cryptographic signature);
4. normalizes asset URLs to HTTPS;
5. keeps results in the same order as the inputs;
6. emits found, not_found, or error status;
7. emits the configured profile event only for successfully resolved records.

A confirmed missing player therefore remains visible and auditable without a profile event. Invalid input fails validation before any lookups; permanent source failures and malformed profiles become uncharged error rows, not missing-player claims.

Who should use it

• Minecraft server operators enriching ban lists, allowlists, and moderation queues.
• Community-tool developers mapping usernames to stable UUIDs.
• Discord bot developers adding current avatars, skins, or capes to commands.
• Data teams normalizing mixed username and UUID columns before a join.
• Support teams checking whether a submitted Java Edition identity resolves.

Who is it for?

Choose this Actor when your workflow begins with known Minecraft identities and needs canonical UUID and texture enrichment. For broad cross-platform handle discovery instead, use the related Username Checker.

Why use this Minecraft profile lookup

The output is deliberately flatter and more operational than PlayerDB's raw response.

• Mixed usernames and UUIDs work in one batch.
• Input order and inputIndex make joins deterministic.
• Not-found inputs produce rows instead of disappearing.
• Direct and encoded skin/cape URLs are supported, with texture IDs and an explicit skin-model field for CSV grouping.
• Transient failures use bounded retries; invalid-player responses are not retried.
• No browser, account, cookies, or proxy configuration is required.

Data you can extract

Field	Meaning
input	Original trimmed username or UUID
inputIndex	Zero-based position in the processed input
lookupType	username or uuid
status	found, not_found, or error
statusCode	PlayerDB status code or local failure code
message	Human-readable lookup result
username	Canonical current username, when found
uuid	Canonical hyphenated UUID
rawUuid	UUID without hyphens
avatarUrl	Player avatar asset URL
skinTextureUrl	Current skin texture URL
capeTextureUrl	Cape texture URL when the profile exposes one
skinTextureId / capeTextureId	Texture-path IDs from valid textures.minecraft.net URLs; otherwise null
skinModel	Explicit skin model metadata (for example slim); null when unknown
textureMetadata	Texture timestamp, profile identity, signature flag, and skin model
nameHistory	Historical names returned by PlayerDB; often empty
cachedAt	PlayerDB cache timestamp
sourceUrl	Exact public API endpoint requested
lookedUpAt	ISO timestamp when this run performed the lookup

Nullable profile fields are null for missing or failed lookups.

Getting started

1. Open the Actor input page.
2. Add one or more Java Edition usernames or UUIDs to Minecraft usernames or UUIDs.
3. Keep concurrency at 5 for ordinary batches.
4. Optionally use maxItems to test only the beginning of a large list.
5. Click Start.
6. Open the default dataset and select the Minecraft profiles view.
7. Export the rows as JSON, CSV, Excel, XML, or RSS.

Input parameters

players (required)

An array of 1–10,000 identifiers. Usernames must contain 1–16 letters, numbers, or underscores. UUIDs can be hyphenated or raw 32-character hexadecimal values.

{
  "players": [
    "Notch",
    "jeb_",
    "069a79f4-44e9-4726-a5be-fca90e38aaf5"
  ]
}

maxItems (optional)

Processes only the first N identifiers, including missing/error rows; it is not a found-profile limit. The schema default is 100 and the maximum is 10,000. Apify platform input processing and the local SDK apply that default when omitted (a local 101-player omission test processes 100). The entrypoint's existing fallback, if input reaches it without a value, is the supplied list length, up to 10,000. Set an explicit value for predictable API/UI batch size; do not rely on omission to process a full list.

concurrency (optional)

Controls simultaneous PlayerDB requests from 1 to 20. The default is 5. Lower it if PlayerDB is responding slowly.

Example output

A successful lookup returns a record like this (timestamps and texture hashes change as PlayerDB refreshes its cache):

{
  "input": "jeb_",
  "inputIndex": 0,
  "lookupType": "username",
  "status": "found",
  "statusCode": "player.found",
  "message": "Successfully found player by given ID.",
  "username": "jeb_",
  "uuid": "853c80ef-3c37-49fd-aa49-938b674adae6",
  "rawUuid": "853c80ef3c3749fdaa49938b674adae6",
  "avatarUrl": "https://crafthead.net/avatar/853c80ef3c3749fdaa49938b674adae6",
  "skinTextureUrl": "https://textures.minecraft.net/texture/...",
  "capeTextureUrl": "https://textures.minecraft.net/texture/...",
  "skinTextureId": null,
  "capeTextureId": null,
  "skinModel": null,
  "textureMetadata": {
    "timestamp": "2026-08-30T10:06:35.433Z",
    "profileId": "853c80ef3c3749fdaa49938b674adae6",
    "profileName": "jeb_",
    "signatureRequired": true,
    "skinModel": null
  },
  "nameHistory": [],
  "cachedAt": "2026-08-30T10:06:35.000Z",
  "sourceUrl": "https://playerdb.co/api/player/minecraft/jeb_",
  "lookedUpAt": "2026-09-05T14:00:00.000Z"
}

How much does it cost to resolve Minecraft profiles?

Pay-per-event pricing contains a small $0.0001 run start plus successful profile events. Not-found and failed lookups have no profile charge.

Plan	Price per resolved profile
Free	$0.0006762
Bronze	$0.000588
Silver	$0.00045864
Gold / Platinum / Diamond	$0.0003528

At Bronze rates, 10 successful profiles cost about $0.00598, 100 cost about $0.05890, and 1,000 cost about $0.58810, including the start event. Actual total depends on how many inputs resolve successfully, not merely the number supplied.

Moderation and server enrichment workflow

Export a player list from your server plugin, map the relevant column into players, and run this Actor. Join the dataset back to the original list using inputIndex or input. Store uuid as the stable identity key and treat username, avatar, skin, and cape as refreshable attributes.

For recurring checks, schedule the Actor and compare cachedAt, username, skinTextureUrl, and capeTextureUrl between datasets. The Actor returns snapshots; it does not send alerts or calculate diffs itself. cachedAt is PlayerDB's cache time, not a fresh Mojang lookup guarantee; lookedUpAt is this export's lookup time.

For a roster/skin report, export uuid, username, skinTextureId, capeTextureId, and skinModel as CSV. Group non-null skinTextureId values to find shared textures, keeping nulls as unknown rather than treating them as the same skin. A missing model does not establish a classic model or absence of a custom skin. The illustrative ... URLs above have no valid texture hash, so their IDs are shown as null.

Integration patterns

• Add canonical UUIDs to a moderation database.
• Refresh player avatars in a dashboard or community roster.
• Enrich support tickets containing usernames.
• Verify a UUID before calling a downstream Mojang-aware service.
• Feed status rows into Make, Zapier, n8n, Airbyte, or a webhook-based pipeline.
• Schedule periodic identity snapshots with Apify Schedules.

Run through the Apify API

Replace APIFY_TOKEN with your token.

cURL

curl -X POST \
  "https://api.apify.com/v2/acts/automation-lab~minecraft-player-profile-lookup/runs?token=APIFY_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"players":["Notch","jeb_"],"maxItems":2}'

JavaScript

import { ApifyClient } from 'apify-client';

const client = new ApifyClient({ token: process.env.APIFY_TOKEN });
const run = await client.actor('automation-lab/minecraft-player-profile-lookup').call({
  players: ['Notch', 'jeb_'],
  maxItems: 2,
});
const { items } = await client.dataset(run.defaultDatasetId).listItems();
console.log(items);

Python

from apify_client import ApifyClient
import os

client = ApifyClient(os.environ['APIFY_TOKEN'])
run = client.actor('automation-lab/minecraft-player-profile-lookup').call(
    run_input={'players': ['Notch', 'jeb_'], 'maxItems': 2}
)
items = client.dataset(run['defaultDatasetId']).list_items().items
print(items)

Use with Apify MCP

Add this Actor to Claude Code:

claude mcp add --transport http apify \
  "https://mcp.apify.com?tools=automation-lab/minecraft-player-profile-lookup"

Claude Desktop, Cursor, and VS Code setup

Desktop and editor clients can use this same JSON configuration in Claude Desktop, Cursor, or VS Code:

{
  "mcpServers": {
    "apify": {
      "url": "https://mcp.apify.com?tools=automation-lab/minecraft-player-profile-lookup"
    }
  }
}

Example prompts:

• “Resolve Notch, jeb_, and Dinnerbone and return their UUID and cape URL.”
• “Check these moderation-list usernames and separate found from not-found rows.”
• “Convert this list of Minecraft UUIDs into current usernames and avatar URLs.”

Reliability and retry behavior

The Actor makes direct HTTPS calls to PlayerDB. Each request has a 15-second timeout and at most three attempts for network/timeouts, non-JSON responses, rate limits, or temporary server errors. A valid Retry-After is honored with a maximum wait of 5 seconds; otherwise retries wait 300/600 ms. The original whole-lookup timeout/backoff envelope (about 45.9 seconds) is retained by shortening later request timeouts if necessary. Confirmed minecraft.invalid_username responses (PlayerDB uses this code for missing username and UUID lookups) are returned immediately as not_found; other permanent failures are uncharged errors and are not retried.

A temporary failure that remains after retries becomes an error row, preserving the input for later retry. Canonical username and consistent dashed/raw UUIDs are required for a chargeable found row. Review status, statusCode, and message before using a row downstream.

A concurrency-sized window is consumed and saved in input order. Earlier completed prefixes are persisted before a slow tail finishes. Once the profile budget is exhausted, no new window starts; at most the current window is already in flight. Found rows are not stored without available profile budget. Charge exhaustion can end the output before the full list; interruption can leave only already-saved rows, with no automatic resume guarantee.

Limitations

• PlayerDB and its upstream Minecraft data determine availability and freshness.
• Name history may be empty because historical-name coverage is source-dependent; it is not a guaranteed complete Mojang name history.
• Cape and skin-model fields are nullable because not every account exposes them.
• This Actor resolves Java Edition player identities; it does not resolve Bedrock/Xbox identities.
• It does not download image binaries, render skins, inspect servers, monitor continuously, send alerts, or calculate changes.
• maxItems processes the start of the list; it is not pagination state.

Data handling and support

This Actor does not use AI. Player identifiers are sent to PlayerDB's public API; no account or paid third-party API key is required. The run start and stored-profile events above are the only Actor charges. Minecraft, Mojang, and PlayerDB are referenced descriptively; this Actor is not affiliated with or endorsed by them.

Input and exported public profile data remain in your Apify run storage under your account's retention settings; delete runs/datasets/key-value stores through Apify's controls. The Actor creates no separate persistent profile cache. Use the Actor's Issues tab for support.

Private failure diagnostics

Failed operations send sanitized diagnostic input, exceptions, safe work counters, and Actor/build/run IDs to our private GlitchTip service for repair. Secret fields and URL queries are removed, and reports are retained for 30 days. Player identifiers in players are also redacted from diagnostic input snapshots. Normal missing-player results are not reported as incidents; unexpected exhausted lookup errors are bounded to one report per run, plus any fatal error.

Legality

Use public Minecraft identity data only for legitimate administration, moderation, support, research, or integration purposes. You remain responsible for your inputs, retention, and downstream handling.

Responsible use

The Actor accesses public identity and texture metadata exposed by PlayerDB. Follow PlayerDB and Mojang terms, Apify's policies, and applicable privacy or community rules. Use the data for legitimate moderation, administration, support, research, or integration tasks. Do not use it to harass players or misrepresent public profile data as private account information.

Troubleshooting

Why is a valid-looking username not_found?

The account may not exist, may not be a Java Edition account, or PlayerDB may not resolve it. Inspect statusCode and retry later only if source freshness is plausible.

Why is capeTextureUrl null?

Null means neither a usable direct cape URL nor a decoded cape URL was available. It does not prove that the account has no cape.

Why did my run stop before the entire list?

Check explicit maxItems (the platform/local SDK apply the schema default of 100 when omitted), the run's charge limit, and whether it was interrupted. Only the selected input prefix is processed; output can be partial after a charge stop or interruption.

Why do I see error rows?

PlayerDB remained unavailable after bounded retries, rejected access, or returned malformed/inconsistent profile data. The row is not charged as a successful profile. Inspect the code before retrying, preferably with default concurrency.

Related Automation Lab actors

• Username Checker checks whether a handle appears across hundreds of public platforms. Use it for broad cross-platform discovery rather than Minecraft UUID, skin, and cape resolution.

FAQ

Can I mix usernames and UUIDs?

Yes. Each row records its detected lookupType.

Are duplicate inputs removed?

No. Saved results retain duplicates and their original indexes. Charge stops or interruption may leave only a prefix.

Are missing players charged?

No. The run start event applies once, but the configured profile event applies only to successfully resolved, stored profiles.

Does the Actor need a proxy or Minecraft account?

No. It uses PlayerDB's public API directly.

Can I schedule recurring runs?

Yes. Use Apify Schedules and store each run's dataset as a snapshot. Compare snapshots in your own pipeline.

Does the Actor return raw signed texture payloads?

No. It extracts operational fields without exporting the large base64 value or cryptographic signature.