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 every input.

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. decodes the signed texture property;
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 missing player therefore remains visible and auditable without a profile event.

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.
• Skin and cape URLs are extracted from the encoded texture property.
• 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
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. The default is 100 and the maximum is 10,000.

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/...",
  "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.

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 up to two retries for network failures, rate limits, or temporary server errors. Stable invalid-player responses are returned immediately as not_found.

A temporary failure that remains after retries becomes an error row, preserving the input for later retry. Review status, statusCode, and message before using a row downstream.

Limitations

• PlayerDB and its upstream Minecraft data determine availability and freshness.
• Name history may be empty because historical-name coverage is source-dependent.
• 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.

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?

Most Minecraft accounts do not have a cape. Null means PlayerDB's decoded texture property did not expose one.

Why did my run stop before the entire list?

Increase maxItems; its default is 100. The Actor intentionally processes only the first N inputs.

Why do I see error rows?

PlayerDB remained unavailable after bounded retries. The row is not charged as a successful profile. Retry those inputs later, 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. Every processed input produces its own row so indexes remain suitable for joins.

Are missing players charged?

No. The run start event applies once, but the configured profile event is emitted only after a profile resolves successfully.

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.