haunt.gg | Lookup User

Resolve a haunt.gg user by their username, numeric uid, internal id, or linked discord account id. By default the response is a lean basic payload; opt into additional data (full profile, badges, links, projects, and more) with per-section include flags so you only ever transfer what you need.

GET/api/lookup/user

Authorizations

X-API-Keyheaderstringrequired

API key from your dashboard with the lookup:user permission (granted by staff). Treat it like a password.

Query Parameters

typequerystringrequired

How to interpret value. One of username, uid, id, or discord. Username matching is case-insensitive and falls back to aliases; discord resolves the user via their linked Discord account.

valuequerystringrequired

The lookup value: a username, a numeric uid, an internal user id, or a Discord account id (snowflake) — matching the chosen type. 1–64 characters.

showAliasProfilequeryboolean

Resolution modifier (not an include flag). When value resolves through an alias that points to a custom profile, scope all profile-derived data — profile, links, widgets, audios, backgrounds, projects, gallery, sections, and the user's avatarUrl — to that alias profile instead of the user's active one. No-op for direct username/uid/id/discord matches and for aliases without a custom profile. Pass true. Defaults to false.

profilequeryboolean

Include the active profile (display name, description, theme, fonts, and resolved asset URLs). Pass the literal string true. Defaults to false.

badgesqueryboolean

Include the user's badges — both enabled and disabled, each carrying an enabled flag plus its per-profile display overlay (color, recolor, selected tier, order). Filter on enabled client-side if you only want the visible ones. The profile-wide badge styling (monochrome, glow, border, …) lives separately under profile.settings.badgesSettings (request profile=true). Pass true. Defaults to false.

widgetsqueryboolean

Include the active profile's widgets. Pass true. Defaults to false.

audiosqueryboolean

Include the active profile's audio tracks. Pass true. Defaults to false.

backgroundsqueryboolean

Include the active profile's backgrounds. Pass true. Defaults to false.

linksqueryboolean

Include the active profile's links. Pass true. Defaults to false.

projectsqueryboolean

Include the active profile's projects. Pass true. Defaults to false.

viewsqueryboolean

Include the profile view count. Pass true. Defaults to false.

aliasesqueryboolean

Include the user's aliases. Pass true. Defaults to false.

galleryqueryboolean

Include every gallery image across the profile's Gallery sections (caption, width, and resolved asset URL), in section-then-item order. Pass true. Defaults to false.

sectionsqueryboolean

Include the profile's section layout in render order (About Me, Projects, Custom Text, Gallery, Audio Player). About-Me sections carry the bio content, skills, and widgetIds; Projects sections carry projectIds; Gallery sections carry their media items — resolve id references against the widgets/projects includes. Pass true. Defaults to false.

feedbackqueryboolean

Include the user's profile feedback tally (likes and dislikes counts). Pass true. Defaults to false.

commentsqueryboolean

Include the profile's top-level comments (newest first, pinned bubble up; capped at 100, replies not expanded — use replyCount). Pass true. Defaults to false.

Only the sections you opt into are queried and serialized, so the default payload stays small. Include flags are read as exact strings — pass true (e.g. profile=true); any other value is treated as false. The same exact-string rule applies to showAliasProfile.

Discord lookups — resolve a Discord user straight to their haunt.gg account with their snowflake id: ?type=discord&value=1363890885443452989. Returns 404 when no haunt.gg user has that Discord account linked.

Alias profiles — when a user runs multiple aliases with their own custom profiles, add showAliasProfile=true to a username/alias lookup to scope the returned profile, links, widgets, audios, backgrounds, projects, gallery, sections, and avatarUrl to the alias's profile rather than the active one — e.g. ?type=username&value=john-music&profile=true&showAliasProfile=true.

Example Request

Request

curl -X GET "https://haunt.gg/api/lookup/user?type=username&value=john&profile=true" \
  -H "X-API-Key: YOUR_API_KEY"

Response

User found. The full payload with every include flag enabled (profile, badges, widgets, audios, backgrounds, links, projects, views, aliases, gallery, sections, feedback, comments all set to true). Without any flags only `error` and the basic `user` object are returned; each flag adds its key, so request just the ones you need to keep the payload small.

{
  "error": null,
  "user": {
    "id": "clz9k2x0a0000s601f8h3d7q2",
    "uid": 1337,
    "username": "john",
    "name": "John",
    "avatarUrl": "https://assets.haunt.gg/avatars/john.png",
    "discordId": "1363890885443452989",
    "premium": true,
    "verified": false,
    "imagehost": false,
    "inactive": false,
    "createdAt": "2026-01-15T10:30:00.000Z"
  },
  "profile": {
    "profileId": "clz9k3p1b0001s601a2b4c5d6",
    "name": "john",
    "displayName": "John",
    "description": "just vibing",
    "location": "Berlin",
    "theme": "default",
    "font": "inter",
    "fontUsername": "inter",
    "soundEffect": "none",
    "createdAt": "2026-01-15T10:30:00.000Z",
    "updatedAt": "2026-05-09T12:34:56.000Z",
    "avatar": {
      "url": "https://assets.haunt.gg/avatars/john.png",
      "mime": "image/png",
      "width": 512,
      "height": 512,
      "duration": null
    },
    "banner": null,
    "cursor": null,
    "cursorPointer": null,
    "fontAsset": null,
    "fontUsernameAsset": null,
    "soundEffectAsset": null,
    "metadataFavicon": null,
    "metadataBanner": null,
    "settings": {
      "customization": {
        "colors": {
          "text": "#ffffff",
          "secondaryText": "#dddddd",
          "accent": "#000000",
          "highlight": "#ffffff",
          "background": "#000000",
          "username": "#ffffff",
          "description": "#a1a1aa",
          "gradient": { "enabled": false, "primary": "#000000", "secondary": "#999a9e", "angle": 100 }
        },
        "opacity": 10,
        "blur": 10,
        "comments": { "enabled": true, "public": true, "writable": true },
        "feedback": { "enabled": true, "public": true },
        "title": { "enabled": true, "animation": "scrolling" },
        "sectionLayout": "snap",
        "scrollIndicator": { "enabled": true, "text": "Scroll for more", "icon": "mingcute:down-fill" }
      },
      "border": { "enabled": true, "color": "#ffffff", "width": 0, "radius": 35, "opacity": 0 },
      "avatarSettings": { "enabled": true, "radius": 100, "decoration": "decorations/angry.png", "useDiscord": false },
      "bannerSettings": { "gradient": true, "gradientIntensity": 50 },
      "backgroundSettings": { "shuffle": false, "duration": 10, "loop": false },
      "parallax": { "enabled": true, "intensity": 20, "inverted": true },
      "backgroundEffects": {
        "enabled": true,
        "order": ["blurred_background", "night_time", "old_tv", "snow", "rain", "particles"],
        "blurred_background": { "enabled": false, "intensity": 5 },
        "night_time": { "enabled": true, "intensity": 75 },
        "old_tv": { "enabled": false, "intensity": 5 },
        "snow": { "enabled": false, "intensity": 50, "color": "#ffffff" },
        "rain": { "enabled": false, "intensity": 50, "color": "#7dd3fc" },
        "particles": { "enabled": false, "intensity": 50, "color": "#ffffff" },
        "shooting_stars": { "enabled": false, "intensity": 50, "color": "#ffffff" }
      },
      "reactBackground": {
        "enabled": true,
        "type": "floatingLines",
        "aurora": { "colors": ["#5227ff", "#000000", "#5227ff"], "amplitude": 100, "blend": 50, "speed": 100 },
        "prism": { "animationType": "rotate", "glow": 100, "noise": 50, "scale": 360, "hueShift": 0, "colorFrequency": 100, "timeScale": 50 },
        "silk": { "color": "#5000b3", "speed": 15, "scale": 100, "noiseIntensity": 150, "rotation": 0 },
        "lightRays": { "color": "#5000b3", "origin": "top-center", "speed": 100, "spread": 100, "rayLength": 200, "followMouse": true },
        "sideRays": { "color1": "#eab308", "color2": "#96c8ff", "origin": "top-right", "speed": 250, "intensity": 200, "spread": 200 },
        "prismaticBurst": { "colors": ["#ff3366", "#4d3dff", "#ffffff"], "intensity": 200, "speed": 50, "animationType": "rotate3d", "distort": 0, "rayCount": 0 },
        "pixelBlast": { "variant": "square", "color": "#b19eef", "pixelSize": 6, "patternDensity": 100, "speed": 50, "edgeFade": 50, "ripples": true, "liquid": false },
        "colorBends": { "colors": ["#5227ff", "#ff9ffc", "#b19eef"], "rotation": 90, "speed": 20, "intensity": 150, "warpStrength": 100, "bandWidth": 6 },
        "floatingLines": { "colors": ["#5227ff", "#b19eef"], "lineCount": 6, "speed": 100, "bendStrength": -50, "interactive": true, "parallax": true }
      },
      "usernameEffects": {
        "enabled": true,
        "order": ["glow", "typewriter", "particles", "rainbow"],
        "glow": { "enabled": true, "strength": 2 },
        "typewriter": { "enabled": false, "speed": 100, "deleteSpeed": 100, "delay": 1500, "cursor": "|" },
        "particles": { "enabled": true, "color": "white" },
        "rainbow": { "enabled": false, "angle": 90 },
        "gradient": { "enabled": false, "color1": "#ff0000", "color2": "#00ff00", "color3": "#0000ff", "angle": 90 }
      },
      "audioSettings": {
        "shuffle": true,
        "loop": false,
        "player": false,
        "playerStyle": "lyrics",
        "lyricsPosition": "right",
        "coverBackground": true,
        "volumeControl": true,
        "volumeDefault": 25
      },
      "cursorSettings": { "enabled": true, "type": "particles", "color": "#ffffff" },
      "linksSettings": { "monochrome": true, "color": "#ffffff", "glow": true, "glowStrength": 3, "size": 100 },
      "badgesSettings": {
        "color": "#ffffff",
        "monochrome": true,
        "glow": true,
        "glowStrength": 2,
        "customization": { "enabled": true, "accentColor": "#ffffff", "opacity": 5 },
        "border": { "enabled": true, "color": "#ffffff", "width": 2, "radius": 25, "opacity": 10 }
      },
      "widgetsSettings": {
        "customization": { "enabled": true, "accentColor": "#ffffff", "textColor": "#ffffff", "secondaryTextColor": "#9ca3af", "opacity": 5 },
        "border": { "enabled": true, "color": "#ffffff", "width": 2, "radius": 25, "opacity": 10 },
        "layouts": {
          "modern": {
            "card": [
              { "widgetId": "clz9kw1c0001s601widget001", "row": 0, "col": 0, "width": "half" },
              { "widgetId": "clz9kw1c0002s601widget002", "row": 0, "col": 1, "width": "half" }
            ],
            "bottom": [
              { "widgetId": "clz9kw1c0003s601widget003", "row": 0, "col": 0, "width": "full" }
            ]
          },
          "default": { "card": [], "bottom": [] }
        }
      },
      "enterScreen": {
        "enabled": false,
        "text": "Enter",
        "textColor": "#ffffff",
        "accentColor": "#000000",
        "accentOpacity": 80,
        "accentBlur": 20,
        "lineDivider": "none",
        "force": false,
        "animation": "horizontal_split",
        "animationDuration": 1500
      },
      "animations": {
        "profile": { "enabled": true, "type": "reveal", "duration": 2500 },
        "border": {
          "enabled": true,
          "scopes": {
            "profile": { "mode": "none", "color": "#ffffff", "speed": 5 },
            "audio": { "mode": "none", "color": "#ffffff", "speed": 5 },
            "volume": { "mode": "none", "color": "#ffffff", "speed": 5 },
            "comments": { "mode": "none", "color": "#ffffff", "speed": 5 },
            "widgetsCard": { "mode": "none", "color": "#ffffff", "speed": 5 },
            "widgetsBottom": { "mode": "none", "color": "#ffffff", "speed": 5 },
            "widgetsSection": { "mode": "none", "color": "#ffffff", "speed": 5 },
            "badges": { "mode": "none", "color": "#ffffff", "speed": 5 },
            "aboutMe": { "mode": "none", "color": "#ffffff", "speed": 5 },
            "projects": { "mode": "none", "color": "#ffffff", "speed": 5 },
            "skills": { "mode": "none", "color": "#ffffff", "speed": 5 }
          }
        },
        "text": {
          "enabled": true,
          "scopes": {
            "aboutMe": { "enabled": false, "mode": "rainbow", "color1": "#ff0000", "color2": "#00ff00", "color3": "#0000ff", "angle": 90 },
            "customText": { "enabled": false, "mode": "rainbow", "color1": "#ff0000", "color2": "#00ff00", "color3": "#0000ff", "angle": 90 },
            "description": { "enabled": false, "mode": "rainbow", "color1": "#ff0000", "color2": "#00ff00", "color3": "#0000ff", "angle": 90 },
            "typewriter": { "enabled": false, "mode": "rainbow", "color1": "#ff0000", "color2": "#00ff00", "color3": "#0000ff", "angle": 90 },
            "enterScreen": { "enabled": false, "mode": "rainbow", "color1": "#ff0000", "color2": "#00ff00", "color3": "#0000ff", "angle": 90 },
            "location": { "enabled": false, "mode": "rainbow", "color1": "#ff0000", "color2": "#00ff00", "color3": "#0000ff", "angle": 90 },
            "views": { "enabled": false, "mode": "rainbow", "color1": "#ff0000", "color2": "#00ff00", "color3": "#0000ff", "angle": 90 },
            "joinDate": { "enabled": false, "mode": "rainbow", "color1": "#ff0000", "color2": "#00ff00", "color3": "#0000ff", "angle": 90 },
            "comments": { "enabled": false, "mode": "rainbow", "color1": "#ff0000", "color2": "#00ff00", "color3": "#0000ff", "angle": 90 },
            "feedback": { "enabled": false, "mode": "rainbow", "color1": "#ff0000", "color2": "#00ff00", "color3": "#0000ff", "angle": 90 },
            "volume": { "enabled": false, "mode": "rainbow", "color1": "#ff0000", "color2": "#00ff00", "color3": "#0000ff", "angle": 90 },
            "links": { "enabled": false, "mode": "rainbow", "color1": "#ff0000", "color2": "#00ff00", "color3": "#0000ff", "angle": 90 },
            "badges": { "enabled": false, "mode": "rainbow", "color1": "#ff0000", "color2": "#00ff00", "color3": "#0000ff", "angle": 90 }
          }
        }
      },
      "typewriter": {
        "enabled": true,
        "descriptions": ["building things", "say hi :)"],
        "speed": 100,
        "deleteSpeed": 100,
        "delay": 1700,
        "cursor": "|",
        "color": "#c1c1c1"
      },
      "metadata": {
        "title": "John",
        "description": "just vibing",
        "color": {
          "overlay": "#000000",
          "overlayOpacity": 50,
          "embed": "#ffffff",
          "username": "#ffffff",
          "url": "#ffffff",
          "feedback": "#ffffff",
          "views": "#ffffff"
        },
        "visibility": { "avatar": true, "username": true, "url": true, "feedback": false, "views": false }
      },
      "joinDate": { "enabled": true, "format": "absolute" },
      "viewsSettings": { "enabled": true, "animation": true, "animationDuration": 1000 }
    }
  },
  "badges": [
    {
      "id": "clz9kb1a0001s601donator00",
      "type": "STANDARD",
      "badgeId": "donator",
      "enabled": true,
      "selectedTier": 2,
      "unlockedTiers": [1, 2],
      "color": null,
      "recolor": false,
      "name": null,
      "order": 0,
      "image": null,
      "tiers": [
        { "tier": 1, "threshold": 5, "title": "Supporter", "description": "Donated €5+", "color": "#cd7f32", "unlocked": true, "selected": false },
        { "tier": 2, "threshold": 25, "title": "Patron", "description": "Donated €25+", "color": "#c0c0c0", "unlocked": true, "selected": true }
      ]
    },
    {
      "id": "clz9kc2b0002s601custom000",
      "type": "CUSTOM",
      "badgeId": null,
      "enabled": false,
      "selectedTier": null,
      "unlockedTiers": [],
      "color": "#ff66cc",
      "recolor": true,
      "name": "Early Bird",
      "order": 1,
      "image": {
        "url": "https://assets.haunt.gg/badges/earlybird.png",
        "mime": "image/png",
        "width": 64,
        "height": 64,
        "duration": null
      },
      "tiers": []
    }
  ],
  "widgets": [
    {
      "id": "clz9kw1c0001s601widget001",
      "platform": "spotify",
      "type": "track",
      "identifier": "3n3Ppam7vgaVa1iaRUc9Lp",
      "order": 0
    }
  ],
  "audios": [
    {
      "id": "clz9ka1d0001s601audio0001",
      "title": "Midnight",
      "artist": "John",
      "externalUrl": "https://open.spotify.com/track/3n3Ppam7vgaVa1iaRUc9Lp",
      "order": 0,
      "audio": {
        "url": "https://assets.haunt.gg/audio/midnight.mp3",
        "mime": "audio/mpeg",
        "width": null,
        "height": null,
        "duration": 213
      },
      "cover": {
        "url": "https://assets.haunt.gg/audio/midnight.png",
        "mime": "image/png",
        "width": 640,
        "height": 640,
        "duration": null
      }
    }
  ],
  "backgrounds": [
    {
      "id": "clz9kbg1e0001s601bg000001",
      "title": "Nebula",
      "order": 0,
      "asset": {
        "url": "https://assets.haunt.gg/backgrounds/nebula.jpg",
        "mime": "image/jpeg",
        "width": 1920,
        "height": 1080,
        "duration": null
      }
    }
  ],
  "links": [
    {
      "id": "clz9kl1a0001s601link00001",
      "title": "GitHub",
      "url": "https://github.com/john",
      "platformId": "github",
      "platformType": "social",
      "isText": false,
      "color": null,
      "recolor": false,
      "order": 0,
      "icon": null
    },
    {
      "id": "clz9kl2b0002s601link00002",
      "title": "My Portfolio",
      "url": "https://john.dev",
      "platformId": null,
      "platformType": null,
      "isText": false,
      "color": "#7c3aed",
      "recolor": true,
      "order": 1,
      "icon": {
        "url": "https://assets.haunt.gg/links/portfolio.png",
        "mime": "image/png",
        "width": 128,
        "height": 128,
        "duration": null
      }
    }
  ],
  "projects": [
    {
      "id": "clz9kj1e0004s601c7d8e9f0",
      "title": "haunt.gg",
      "description": "A bio-link platform.",
      "tags": ["nextjs", "typescript"],
      "url": "https://haunt.gg",
      "order": 0,
      "icon": {
        "url": "https://assets.haunt.gg/projects/haunt.png",
        "mime": "image/png",
        "width": 256,
        "height": 256,
        "duration": null
      }
    }
  ],
  "views": 18234,
  "aliases": [
    { "name": "john-music", "redirect": false, "profileId": "clz9k3p1b0001s601a2b4c5d6" },
    { "name": "j", "redirect": true, "profileId": null }
  ],
  "gallery": [
    {
      "id": "clz9kg1a0000s601m1n2o3p4",
      "caption": "Sunset",
      "width": "half",
      "asset": {
        "url": "https://assets.haunt.gg/gallery/abc.png",
        "mime": "image/png",
        "width": 1200,
        "height": 800,
        "duration": null
      }
    }
  ],
  "sections": [
    {
      "id": "clz9ka1b0001s601q5r6s7t8",
      "type": "ABOUT_ME",
      "order": 0,
      "title": "About Me",
      "description": null,
      "alignment": "left",
      "enabled": true,
      "content": "hey, I build things.",
      "widgetIds": ["clz9kw1c0001s601widget001"],
      "skills": {
        "frontend": ["react", "typescript"],
        "backend": ["node"],
        "database": [],
        "core": [],
        "game": [],
        "tools": [],
        "cloud": [],
        "mobile": [],
        "design": [],
        "music": []
      },
      "skillsEnabled": true
    },
    {
      "id": "clz9kp1d0003s601y3z4a5b6",
      "type": "PROJECTS",
      "order": 1,
      "title": null,
      "description": null,
      "alignment": "center",
      "projectIds": ["clz9kj1e0004s601c7d8e9f0"]
    },
    {
      "id": "clz9kq1f0005s601g1h2i3j4",
      "type": "GALLERY",
      "order": 2,
      "title": "Gallery",
      "description": null,
      "alignment": "left",
      "items": [
        {
          "id": "clz9kg1a0000s601m1n2o3p4",
          "caption": "Sunset",
          "width": "half",
          "asset": {
            "url": "https://assets.haunt.gg/gallery/abc.png",
            "mime": "image/png",
            "width": 1200,
            "height": 800,
            "duration": null
          }
        }
      ]
    },
    {
      "id": "clz9kr1g0006s601k5l6m7n8",
      "type": "AUDIO_PLAYER",
      "order": 3,
      "title": null,
      "description": null,
      "alignment": "left"
    }
  ],
  "feedback": {
    "likes": 42,
    "dislikes": 3
  },
  "comments": [
    {
      "id": "clz9k7c2d0002s601e9f0g1h2",
      "content": "great page!",
      "likeCount": 5,
      "replyCount": 2,
      "pinned": true,
      "createdAt": "2026-05-09T12:34:56.000Z",
      "author": {
        "id": "clz9k8d3e0003s601i2j3k4l5",
        "uid": 99,
        "username": "jane",
        "name": "Jane",
        "avatarUrl": "https://assets.haunt.gg/avatars/jane.png"
      }
    }
  ]
}