Start here

If you read one section, read this one. There is a single pattern that makes this API fast for your users and free for everyone, and it is three steps:

1. 1

   Ask for the profile once

   Call /api/v1/users/:id and keep two things: the user's ID and avatar.hash.

2. 2

   Store the hash, not the URL

   A hash is stable and lets you rebuild the image at any size later. Comparing hashes also tells you when someone changed their picture.

3. 3

   Point your image tag at Discord

   Render avatar.url directly. Discord's CDN serves the bytes, so this server is never in the path again.

Why it matters: a URL containing the avatar hash can never change contents, so Discord serves it with Cache-Control: public, max-age=31536000 and the visitor's browser keeps it for a year. Your page keeps rendering avatars even if this service is down, and neither of us pays for the image bytes.

That last one is worth spelling out. Discord's CDN sends Access-Control-Allow-Origin: * and applies no hotlink protection, so a browser anywhere can load or read those images with no proxy of your own. If you were planning to pipe avatars through your backend, you do not need to.

Quick start

curl https://pfpgrab.com/api/v1/users/992511112223294201

Every response is JSON. Every failure is JSON in the same shape, with a stable error.code you can branch on. Image bytes always come from Discord's CDN, never from this server.

Which route to use

Two ways to get to an image. They are not equivalent, and picking the right one is most of what separates a fast integration from a slow one.

The redirect exists because it is genuinely convenient when you have an ID and nowhere to put a hash. It is not the route to build a product on.

Endpoints

{
  "id": "992511112223294201",
  "username": "exampleuser",
  "display_name": "Example User",
  "is_bot": false,
  "created_at": "2022-07-01T19:24:49.118Z",
  "accent_color": "#5865f2",
  "avatar": {
    "hash": "a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6",
    "url": "https://cdn.discordapp.com/avatars/992511112223294201/a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6.webp?size=1024",
    "static_url": "https://cdn.discordapp.com/avatars/992511112223294201/a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6.png?size=1024",
    "full_size_url": "https://cdn.discordapp.com/avatars/992511112223294201/a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6.webp?size=4096",
    "size": 1024,
    "animated": false,
    "is_default": false
  },
  "banner": null
}

"avatar": {
  "hash": "a_1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6e",
  "url": "https://cdn.discordapp.com/avatars/.../a_1b2c....webp?size=1024&animated=true",
  "static_url": "https://cdn.discordapp.com/avatars/.../a_1b2c....png?size=1024",
  "full_size_url": "https://cdn.discordapp.com/avatars/.../a_1b2c....webp?size=4096&animated=true",
  "gif_url": "https://cdn.discordapp.com/avatars/.../a_1b2c....gif?size=4096",
  "size": 1024,
  "animated": true,
  "is_default": false
}

{
  "requested": 3,
  "returned": 2,
  "data": [
    { "id": "992511112223294201", "username": "exampleuser" },
    { "id": "80351110224678912", "username": "anotheruser" }
  ],
  "errors": [
    {
      "id": "000000000000000000",
      "error": {
        "code": "user_not_found",
        "message": "No Discord account has that ID."
      }
    }
  ]
}

<img src="https://pfpgrab.com/api/v1/users/992511112223294201/avatar?size=256">

Response fields

Why WebP for animated images: Discord recommends it, because an avatar originally uploaded as WebP or AVIF does not convert cleanly to GIF, while WebP works whatever the source was. It is also far smaller. A typical avatar at 256 pixels is around 40 KB as PNG and around 5 KB as WebP.

This shape is deliberately not Discord's own, so a change on their side does not become a breaking change here. v1 is additive: new fields may appear, so parse defensively and ignore what you do not recognise. Removing or renaming a field would mean v2.

Recipes

Show a Discord avatar next to a username on your site. This is the most common use, and the whole job is four lines. Fetch once when the user links their account, store the pair, and render from your own database from then on.

// Once, when the user gives you their Discord ID
const profile = await getProfile(discordId);
await db.users.update(userId, {
  discordId,
  avatarHash: profile.avatar.hash,
  avatarAnimated: profile.avatar.animated,
});

// Every render after that. No call to this API at all.
function avatarSrc(user, size = 64) {
  if (!user.avatarHash) return "https://cdn.discordapp.com/embed/avatars/0.png";

  const extension = user.avatarAnimated ? "webp" : "png";
  const animated = user.avatarAnimated ? "&animated=true" : "";

  return `https://cdn.discordapp.com/avatars/${user.discordId}/${user.avatarHash}.${extension}?size=${size}${animated}`;
}

Ask for the size you display. ?size=64 is about 4 KB and ?size=1024 is about 40 KB, and a room full of 40 pixel avatars at 1024 is a lot of wasted load on your own visitors. Refresh the stored hash occasionally, since people change their picture.

Render a member list. One batch call, not twenty five lookups. Split anything longer than 25 into chunks.

const response = await fetch(
  `${BASE}/api/v1/users?ids=${ids.slice(0, 25).join(",")}&size=64`,
);
const { data, errors } = await response.json();

// data holds the profiles that resolved, errors the ones that did not.
// The status is 200 either way, so check errors rather than response.ok.

Let someone save an avatar. Fetch the CDN URL in the browser and save the blob. Nothing touches this server, so it costs nothing however many people press the button.

async function saveAvatar(profile) {
  // Animated avatars get saved as GIF, which is what people expect from a file.
  // Everything else keeps the format the URL already names.
  const url = profile.avatar.gif_url ?? profile.avatar.full_size_url;
  const extension = new URL(url).pathname.split(".").pop();

  const blob = await (await fetch(url)).blob();
  const objectUrl = URL.createObjectURL(blob);

  const link = document.createElement("a");
  link.href = objectUrl;
  link.download = `${profile.username}.${extension}`;
  link.click();

  setTimeout(() => URL.revokeObjectURL(objectUrl), 30_000);
}

Code examples

const BASE = "https://pfpgrab.com";

class ProfileError extends Error {
  constructor({ code, message, retry_after }) {
    super(message);
    this.code = code;
    this.retryAfter = retry_after ?? 0;
  }
}

async function getProfile(userId, size = 1024) {
  const response = await fetch(`${BASE}/api/v1/users/${userId}?size=${size}`);
  const body = await response.json();

  // Every failure is { "error": { "code", "message" } }.
  // Branch on code, never on the wording of message.
  if (!response.ok) throw new ProfileError(body.error);

  return body;
}

// Codes that mean "busy right now" rather than "you asked for the wrong
// thing". Those are the only ones worth trying again.
const RETRYABLE = new Set([
  "server_busy",
  "upstream_rate_limited",
  "upstream_timeout",
  "upstream_error",
]);

async function getProfileWithRetries(userId, attempts = 3) {
  for (let attempt = 1; ; attempt += 1) {
    try {
      return await getProfile(userId);
    } catch (err) {
      if (attempt >= attempts || !RETRYABLE.has(err.code)) throw err;

      const wait = err.retryAfter || 2 ** (attempt - 1);
      await new Promise((resolve) => setTimeout(resolve, wait * 1000));
    }
  }
}

try {
  const profile = await getProfileWithRetries("992511112223294201");
  console.log(profile.display_name, profile.avatar.hash);
} catch (err) {
  if (err.code === "user_not_found") console.log("No such account.");
  else if (err.code === "rate_limited") console.log("Slow down.");
  else console.error(err.code, err.message);
}

import requests

BASE = "https://pfpgrab.com"


class ProfileError(RuntimeError):
    def __init__(self, code: str, message: str, retry_after: int = 0):
        super().__init__(message)
        self.code = code
        self.retry_after = retry_after


def get_profile(user_id: str, size: int = 1024) -> dict:
    """Fetch one Discord profile."""
    response = requests.get(
        f"{BASE}/api/v1/users/{user_id}",
        params={"size": size},
        timeout=10,
    )

    body = response.json()
    if not response.ok:
        error = body.get("error", {})
        raise ProfileError(
            error.get("code", "unknown"),
            error.get("message", ""),
            error.get("retry_after", 0),
        )

    return body


def get_profiles(user_ids: list[str]) -> dict:
    """Up to 25 profiles in one request."""
    response = requests.get(
        f"{BASE}/api/v1/users",
        params={"ids": ",".join(user_ids[:25])},
        timeout=15,
    )
    response.raise_for_status()
    return response.json()


def save_avatar(profile: dict, path: str) -> None:
    """Download straight from Discord's CDN, not through the API."""
    avatar = profile["avatar"]
    url = avatar.get("gif_url") or avatar["full_size_url"]

    with requests.get(url, stream=True, timeout=30) as response:
        response.raise_for_status()
        with open(path, "wb") as file:
            for chunk in response.iter_content(8192):
                file.write(chunk)


if __name__ == "__main__":
    try:
        profile = get_profile("992511112223294201")
    except ProfileError as err:
        print(f"Lookup failed ({err.code}): {err}")
    else:
        print(profile["display_name"], profile["created_at"])
        save_avatar(profile, "avatar.png")

import { useEffect, useState } from "react";

const BASE = "https://pfpgrab.com";

export function useDiscordProfile(userId, size = 1024) {
  const [profile, setProfile] = useState(null);
  const [error, setError] = useState(null);
  const [loading, setLoading] = useState(false);

  useEffect(() => {
    if (!userId) return;

    // Cancel the request if the component unmounts or userId changes,
    // so a slow response cannot overwrite a newer one.
    const controller = new AbortController();

    setLoading(true);
    setError(null);

    fetch(`${BASE}/api/v1/users/${userId}?size=${size}`, {
      signal: controller.signal,
    })
      .then(async (response) => {
        const body = await response.json();
        if (!response.ok) throw body.error;
        setProfile(body);
      })
      .catch((err) => {
        // { code, message } from the API, or a DOMException on abort.
        if (err.name !== "AbortError") setError(err.code ? err : null);
      })
      .finally(() => setLoading(false));

    return () => controller.abort();
  }, [userId, size]);

  return { profile, error, loading };
}

Errors

Every failure returns the matching HTTP status and a body shaped like this:

{
  "error": {
    "code": "user_not_found",
    "message": "No Discord account has that ID."
  }
}

code is stable and safe to branch on. message is for humans and may be reworded at any time, so do not match on it. Some codes carry extra fields alongside those two, such as retry_after on a rate limit or valid_sizes on a bad size. Anything with a retry_after also sends it as a Retry-After header.

Errors that state a fact about the request, such as user_not_found or invalid_size, are sent Cache-Control: public, max-age=60, because they will say the same thing a second later. Everything else is no-store, so one bad moment at Discord is never frozen into a cache between here and your users.

Limits

• 60 requests per minute per client. A batch call costs one unit per ID, so 25 IDs in one request costs 25.
• Every response carries X-RateLimit-Limit, X-RateLimit-Remaining and X-RateLimit-Reset. Read them and throttle yourself rather than waiting for a 429.
• Treat those three as advisory. Successful responses are cacheable, and a CDN that serves you one from its cache hands you the header values that were current when it was stored, which may be another caller's. A 429 with Retry-After is the authoritative signal.
• Successful lookups are cached for 10 minutes, so repeat calls for the same ID are instant and cost nothing.
• Identical requests arriving at the same moment are merged into a single call to Discord.
• Call from the browser where you can, so the limit applies per visitor. Calling from your own backend means every one of your users shares a single bucket.
• Set a timeout on your side. 10 seconds is plenty.
• The real ceiling is not this server. Discord allows roughly 50 requests per second on a single bot token, which is why caching a hash on your side matters more than any limit here.

Run your own

This project is open source and MIT licensed. If you are building something that needs its own limits, or you would rather not depend on someone else's uptime, run your own copy. It is a single Node process with four dependencies and no build step.

git clone https://github.com/mohdmahmodi/discord-pfp-api.git
cd discord-pfp-api
npm install
cp .env.example .env    # paste your own bot token in
npm start

You bring your own Discord bot token. Create an application in the developer portal, open the Bot tab, press Reset Token, and put it in .env. The bot needs no permissions, no privileged intents, and no server memberships, because /users/{user_id} reads public profile data only.

Two settings to get right before you expose it. Set TRUST_PROXY_HOPS to match how many proxies sit in front of the process, since it decides which address the rate limiter counts against. And leave TRUST_CLOUDFLARE off until your origin refuses connections that did not arrive through Cloudflare. The README covers both, and the startup banner prints what is in use.

01. What we can see

This service reads public profile data through Discord's official API using a bot token with no permissions, no privileged intents, and no server memberships. The fields in the table above are the entire response. The private fields are not withheld by policy, they are simply not present in the data Discord returns.

Looking someone up sends nothing to that account. They receive no notification and have no way to tell it happened.

A lookup needs a user ID. There is no username search here, and no list of names is kept, because Discord deliberately provides no way to turn a name into an ID and building one would mean assembling a directory of people. Sites advertising username search are querying scraped databases put together without consent.

02. Your data

There is no account system, so there is nothing to sign up for and nothing to delete. Specifically:

• Lookup results are cached in memory for 10 minutes, stay usable for up to 50 minutes more while they refresh, and are dropped after that. Nothing about a looked up profile is written to disk.
• Your recent lookups are stored in your own browser, not on the server. Clearing them removes them completely.
• Avatar and banner images are served to you by Discord's CDN directly. Downloads are assembled in your browser, so no image ever passes through this server.
• No cookies are set. No analytics or advertising scripts run.
• Request logs are kept only as long as needed to operate and secure the service.

03. Acceptable use

Do not use this to harass, impersonate, stalk, or compile records on other people. Doing so breaks Discord's Terms of Service as well as these, and access may be blocked without notice.

Automated use is limited to 60 requests per minute per client. Stay within it and you will never see a problem. Scraping at volume is blocked. If you need more, the project is open source and you can run your own copy on your own bot token.

04. Image rights

Avatars and banners belong to the people who uploaded them, not to this service and not to you. Downloading an image here does not give you a licence to republish it, use it commercially, or pass it off as your own. You are responsible for what you do with anything you save.

05. Legal

This project is not affiliated with, endorsed by, or sponsored by Discord Inc. Discord is a trademark of Discord Inc.

The service is provided as is, with no warranty. It depends on Discord's API, which can change or become unavailable at any time and without notice.

The full privacy policy, including who else your browser talks to while this page is open, is in #privacy.

01. The short version

There are no accounts, no cookies set by this site, no analytics, no advertising, and no tracking of any kind. Nothing about a profile you look up is written to disk. Everything this service holds lives in the memory of one process and is gone within an hour, or immediately if the process restarts.

02. Who runs this

pfpgrab is run by Mohd Mahmodi, an individual, as a free and non-commercial project. There is no company behind it and no revenue attached to it. For anything in this policy, including a deletion request, the contact is [email protected].

The entire server is open source. If you would rather verify a claim in this policy than trust it, the code that makes each one true is at github.com/mohdmahmodi/discord-pfp-api. Every statement below about what is stored and for how long is a line in server.js you can read for yourself.

03. If your profile was looked up

Somebody entering your Discord user ID here causes this server to ask Discord's official API for your public profile. That is the same data Discord shows to anyone who can see your profile in the app. Discord is the source; this service is a reader.

The complete set of fields involved:

Your email address, phone number, messages, servers, friends, IP address, online status, and activity are not in that response. They are not withheld here by policy: Discord simply does not return them to this kind of request, and this service holds no permissions, no privileged intents, and no server memberships that would change that.

You receive no notification, because nothing is sent to your account. A lookup is a read of Discord's public API and is invisible from your side.

There is no way to search by username here, and no list of names is kept. Discord deliberately provides no way to turn a name into an ID, and building one would mean assembling a directory of people. Sites that advertise username search are querying scraped databases put together without consent, and this is not one of them.

04. If you are visiting the site

Your IP address reaches this server the way it reaches any website, as a property of the connection. It is used for exactly one thing: counting requests so that one client cannot exhaust the service for everyone else. The counter lives in memory, resets every 60 seconds, and is never written anywhere.

• No cookies are set by this site. There is no session, no login, and nothing to consent to.
• No analytics. There is no Google Analytics, no Plausible, no Fathom, no pixel, and no error reporting service.
• Your recent lookups stay in your browser. They are kept in localStorage under the key dpa:recent, never sent to the server, and cleared for good by the Clear button in the sidebar or by clearing site data.
• Downloads never touch this server. When you save an avatar, your browser fetches the image from Discord's CDN and assembles the file locally. No image passes through this machine, which is also why the service costs almost nothing to run.

05. How long anything is kept

Everything below is memory only. This service runs no database and writes no data files. Restarting the process erases all of it, and deployments restart the process.

Operational logs record errors and the fact that the server is running. They do not record user IDs or IP addresses, and they are rotated by the operating system rather than kept.

06. Who else sees you when you use this site

This is the part most privacy policies leave vague, so here it is plainly. Loading this page causes your browser to talk to a few other companies, and each of them sees your IP address because that is how the web works. Nothing is shared with them by this service; they see you because your browser connects to them directly.

Those four are the complete list. There is no fifth. If you want none of them, the project is open source and a self hosted copy can drop the fonts and the icon set entirely.

07. Using the API in your own project

If you build on this API, you become responsible for what you do with what it returns. Two things are worth stating clearly.

The URLs returned point at Discord's CDN, not at this service. When your visitors load one, their browsers talk to Discord directly and Discord sees them. That is the correct design and it is why the images stay fast and free, but it does mean an avatar you embed is a request to Discord made by your visitor.

An avatar URL contains a hash that changes whenever the person changes their picture. If you store one, refresh it periodically rather than keeping it forever, so that somebody who changes or removes their avatar stops being shown the old one by your site.

Do not use this API to compile records on people, to enumerate accounts by walking through IDs, or to build a directory. Those break Discord's Developer Policy as well as these terms, and access can be blocked without notice.

08. Your rights

Under the GDPR, the UK GDPR, the CCPA, and similar laws you have rights of access, correction, deletion, restriction, portability, and objection. This service is unusual in how easy those are to satisfy: there is no account to close, no profile to export, and nothing about you stored for longer than an hour.

• Deletion. Email [email protected] with your Discord user ID and the cached copy will be dropped immediately. In practice it will have expired on its own before the message arrives.
• Blocking future lookups. Ask, and your ID will be refused by this service from then on. You do not have to explain why. It is added to the BLOCKED_USER_IDS list the server reads at startup, after which that ID returns 403 user_blocked and is never sent to Discord again.
• Access. What is held is exactly the table in section 03 and nothing else. There is no additional profile to disclose.
• The source. Changing what this service can see about you is done at Discord, not here. Changing your avatar changes its hash, and the old URL stops describing you.

The lawful basis for processing is legitimate interest: showing a person the public profile picture belonging to an ID they already have, at their own request. No profiling, automated decision making, or advertising is involved. Requests are answered within 30 days and normally within a day.

09. Children

This service is not directed at children under 13, and Discord itself requires users to be at least 13. No age is collected, because no account exists to attach one to. If you believe a child's data is being handled here in a way it should not be, write to [email protected] and it will be dealt with straight away.

10. Changes to this policy

The date at the top changes whenever this document does. Because the policy lives in the repository, every edit is a commit with a diff you can read, so there is no version of it you cannot check. A change that makes this service collect more than it does today will be described here rather than quietly folded in.

11. Contact

This project is not affiliated with, endorsed by, or sponsored by Discord Inc. Discord is a trademark of Discord Inc. Avatars and banners belong to the people who uploaded them, and nothing here grants a licence to republish them.