# Lookup User

Look up a user by username, uid, or id — optionally with full profile data.

Resolve a haunt.gg user by their `username`, numeric `uid`, or internal `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

| Name | Type | In | Required | Description |
| --- | --- | --- | --- | --- |
| `X-API-Key` | string | header | yes | API key from your dashboard with the `lookup:user` permission (granted by staff). Treat it like a password. |

## Query Parameters

| Name | Type | In | Required | Description |
| --- | --- | --- | --- | --- |
| `type` | string | query | yes | How to interpret `value`. One of `username`, `uid`, or `id`. Username matching is case-insensitive and falls back to aliases. |
| `value` | string | query | yes | The lookup value: a username, a numeric uid, or an internal user id. 1–64 characters. |
| `profile` | boolean | query | no | Include the active profile (display name, description, theme, fonts, and resolved asset URLs). Pass the literal string `true`. Defaults to `false`. |
| `badges` | boolean | query | no | Include the user's enabled badges. Pass `true`. Defaults to `false`. |
| `widgets` | boolean | query | no | Include the active profile's widgets. Pass `true`. Defaults to `false`. |
| `audios` | boolean | query | no | Include the active profile's audio tracks. Pass `true`. Defaults to `false`. |
| `backgrounds` | boolean | query | no | Include the active profile's backgrounds. Pass `true`. Defaults to `false`. |
| `links` | boolean | query | no | Include the active profile's links. Pass `true`. Defaults to `false`. |
| `projects` | boolean | query | no | Include the active profile's projects. Pass `true`. Defaults to `false`. |
| `views` | boolean | query | no | Include the profile view count. Pass `true`. Defaults to `false`. |
| `aliases` | boolean | query | no | Include the user's aliases. Pass `true`. Defaults to `false`. |
| `skills` | boolean | query | no | Include the active profile's skills. Pass `true`. Defaults to `false`. |

> [!NOTE]
> 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`.

## Example Request

  #### cURL

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

```ts
const params = new URLSearchParams({
  type: "username",
  value: "john",
  profile: "true",
});

const res = await fetch(`https://haunt.gg/api/lookup/user?${params}`, {
  method: "GET",
  headers: { "X-API-Key": apiKey },
});
const data = await res.json();
```
  #### Python

```python
import requests

res = requests.get(
    "https://haunt.gg/api/lookup/user",
    params={"type": "username", "value": "john", "profile": "true"},
    headers={"X-API-Key": api_key},
)
data = res.json()
```

## Response

  #### 200 — User found. Basic payload (no include flags).

```json
{
  "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,
    "createdAt": "2026-01-15T10:30:00.000Z"
  }
}
```
  #### 200 — With profile=true — the active profile is added alongside the basic user.

```json
{
  "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,
    "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,
    "settings": {}
  }
}
```
  #### 400 — Invalid query parameters (e.g. a bad `type`, an empty `value`, or a non-integer `uid`).

```json
{
  "error": "type must be one of: username, uid, id."
}
```
  #### 401 — The API key is missing, invalid, or lacks the lookup:user permission.

```json
{
  "error": "Missing x-api-key header.",
  "code": "UNAUTHORIZED"
}
```
  #### 403 — The matched user is banned. No data is returned.

```json
{
  "error": "User john is banned."
}
```
  #### 404 — No user matched the lookup value.

```json
{
  "error": "No user found."
}
```
  #### 429 — Too many requests — the API key's rate limit was exceeded.

```json
{
  "error": "Rate limit exceeded.",
  "code": "RATE_LIMITED"
}
```