# PlayerDB Minecraft Profile Lookup (`automation-lab/minecraft-player-profile-lookup`) Actor

Resolve Minecraft usernames and UUIDs through PlayerDB into canonical profiles, avatar, skin and cape URLs, texture metadata, cache timestamps, and lookup statuses.

- **URL**: https://apify.com/automation-lab/minecraft-player-profile-lookup.md
- **Developed by:** [Stas Persiianenko](https://apify.com/automation-lab) (community)
- **Categories:** Developer tools
- **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

from $0.35 / 1,000 profile extracteds

This Actor is paid per event. You are not charged for the Apify platform usage, but only a fixed price for specific events.
Since this Actor supports Apify Store discounts, the price gets lower the higher subscription plan you have.

Learn more: https://docs.apify.com/actors/running/actors-in-store.md#pay-per-event

## What's an Apify Actor?

Actors are web data automations that power AI and operations. They run on the Apify platform to scrape websites, process data, connect APIs, and automate workflows.
In Batch mode, an Actor accepts a well-defined JSON input, performs an action which can take anything from a few seconds to a few hours,
and optionally produces a well-defined JSON output, datasets with results, or files in key-value store.
In Standby mode, an Actor provides a web server which can be used as a website, API, or an MCP server.
Actors are written with capital "A".

## How to integrate an Actor?

If asked about integration, you help developers integrate Actors into their projects.
You adapt to their stack and deliver integrations that are safe, well-documented, and production-ready.
The best way to integrate Actors is as follows.

- **AI agents and MCP clients** — the [Apify MCP server](https://docs.apify.com/integrations/mcp.md) at `https://mcp.apify.com` (remote, streamable HTTP, OAuth on first use).
- **Agentic workflows and local Actor development** — [Agent Skills](https://apify.com/.well-known/agent-skills/index.json) with the [Apify CLI](https://docs.apify.com/cli/docs.md): `npm install -g apify-cli`, then `apify login`.
- **JavaScript/TypeScript projects** — the official [JS/TS client](https://docs.apify.com/api/client/js/docs.md): `npm install apify-client`.
- **Python projects** — the official [Python client](https://docs.apify.com/api/client/python/docs.md): `pip install apify-client`.
- **Any other language** — the [REST API](https://docs.apify.com/api/v2.md).

For usage examples, see the [API](#api) section below.

For more details, see Apify documentation as [Markdown index](https://docs.apify.com/llms.txt) and [Markdown full-text](https://docs.apify.com/llms-full.txt).

# README

## 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.

```json
{
  "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):

```json
{
  "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

```bash
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

```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

```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:

```bash
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:

```json
{
  "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](https://apify.com/automation-lab/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.

# Actor input Schema

## `players` (type: `array`):

One to 10,000 Java Edition usernames (1-16 letters, numbers, or underscores) or UUIDs. Username and UUID inputs may be mixed.

## `maxItems` (type: `integer`):

Maximum number of identifiers to process from the start of the players list.

## `concurrency` (type: `integer`):

Number of simultaneous PlayerDB API requests. Keep the default unless you have a large batch.

## Actor input object example

```json
{
  "players": [
    "Notch",
    "jeb_",
    "069a79f4-44e9-4726-a5be-fca90e38aaf5"
  ],
  "maxItems": 20,
  "concurrency": 5
}
```

# Actor output Schema

## `overview` (type: `string`):

Open the table view containing identities, lookup statuses, skin and cape URLs, and timestamps.

# API

You can run this Actor programmatically using our API. Below are code examples in JavaScript, Python, and CLI, as well as the OpenAPI specification and MCP server setup.

## JavaScript example

```javascript
import { ApifyClient } from 'apify-client';

// Initialize the ApifyClient with your Apify API token
// Replace the '<YOUR_API_TOKEN>' with your token
const client = new ApifyClient({
    token: '<YOUR_API_TOKEN>',
});

// Prepare Actor input
const input = {
    "players": [
        "Notch",
        "jeb_",
        "069a79f4-44e9-4726-a5be-fca90e38aaf5"
    ],
    "maxItems": 20,
    "concurrency": 5
};

// Run the Actor and wait for it to finish
const run = await client.actor("automation-lab/minecraft-player-profile-lookup").call(input);

// Fetch and print Actor results from the run's dataset (if any)
console.log('Results from dataset');
console.log(`💾 Check your data here: https://console.apify.com/storage/datasets/${run.defaultDatasetId}`);
const { items } = await client.dataset(run.defaultDatasetId).listItems();
items.forEach((item) => {
    console.dir(item);
});

// 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/js/docs

```

## Python example

```python
from apify_client import ApifyClient

# Initialize the ApifyClient with your Apify API token
# Replace '<YOUR_API_TOKEN>' with your token.
client = ApifyClient("<YOUR_API_TOKEN>")

# Prepare the Actor input
run_input = {
    "players": [
        "Notch",
        "jeb_",
        "069a79f4-44e9-4726-a5be-fca90e38aaf5",
    ],
    "maxItems": 20,
    "concurrency": 5,
}

# Run the Actor and wait for it to finish
run = client.actor("automation-lab/minecraft-player-profile-lookup").call(run_input=run_input)

# Fetch and print Actor results from the run's dataset (if there are any)
print(f"💾 Check your data here: https://console.apify.com/storage/datasets/{run.default_dataset_id}")
for item in client.dataset(run.default_dataset_id).iterate_items():
    print(item)

# 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/python/docs/quick-start

```

## CLI example

```bash
echo '{
  "players": [
    "Notch",
    "jeb_",
    "069a79f4-44e9-4726-a5be-fca90e38aaf5"
  ],
  "maxItems": 20,
  "concurrency": 5
}' |
apify call automation-lab/minecraft-player-profile-lookup --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "type": "http",
            "url": "https://mcp.apify.com/?tools=fetch-actor-details,automation-lab/minecraft-player-profile-lookup"
        }
    }
}

```

The hosted server signs you in with OAuth on first connect, so no API token belongs in this config. Clients without OAuth support can send an `Authorization: Bearer <APIFY_API_TOKEN>` header instead, using a token from API & Integrations in Apify Console (https://console.apify.com/settings/integrations).

## OpenAPI specification

Download the OpenAPI definition: https://api.apify.com/v2/actors/XkdFuJEL8yJyf6F0K/builds/9bdIEi6SSMZ1tsIVz/openapi.json