> ## Documentation Index
> Fetch the complete documentation index at: https://docs.docksys.xyz/llms.txt
> Use this file to discover all available pages before exploring further.

# Bulk Lookups

> Send ordered batches of Discord IDs, Roblox IDs, or alt-detection seeds through v2 bulk endpoints.

Bulk endpoints reduce request count and make large sync jobs easier to manage.

<Info>
  Bulk responses preserve input order, including duplicate input values. Missing records return per-item errors instead of failing the full request.
</Info>

## Endpoints and limits

| Endpoint                | Body field   | Limit |
| ----------------------- | ------------ | ----: |
| `POST /v2/discord/bulk` | `discordIds` |    50 |
| `POST /v2/roblox/bulk`  | `robloxIds`  |    50 |
| `POST /v2/alts/bulk`    | `robloxIds`  |    10 |

All bulk endpoints accept:

<ParamField body="guildId" type="string">
  Required for guild-scoped keys. Optional for global keys.
</ParamField>

<ParamField body="resolved" type="boolean">
  Defaults to `false`. Adds resolved profile data when allowed by the endpoint and plan.
</ParamField>

## Discord bulk

```bash cURL theme={null}
curl --request POST \
  --url "https://api.docksys.xyz/v2/discord/bulk" \
  --header "Authorization: Bearer YOUR_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
    "discordIds": ["123456789012345678", "222222222222222222"],
    "guildId": "987654321098765432",
    "resolved": false
  }'
```

<ParamField body="discordIds" type="string[]" required>
  Discord user IDs to resolve. Maximum `50`.
</ParamField>

## Roblox bulk

```bash cURL theme={null}
curl --request POST \
  --url "https://api.docksys.xyz/v2/roblox/bulk" \
  --header "Authorization: Bearer YOUR_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
    "robloxIds": ["156319135", "4567890123"],
    "guildId": "987654321098765432",
    "resolved": false
  }'
```

<ParamField body="robloxIds" type="string[]" required>
  Roblox user IDs to resolve. Maximum `50`.
</ParamField>

## Alt bulk

```bash cURL theme={null}
curl --request POST \
  --url "https://api.docksys.xyz/v2/alts/bulk" \
  --header "Authorization: Bearer YOUR_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
    "robloxIds": ["156319135", "4567890123"],
    "guildId": "987654321098765432",
    "resolved": false
  }'
```

<ParamField body="robloxIds" type="string[]" required>
  Roblox user IDs to use as alt-detection seeds. Maximum `10`.
</ParamField>

<Warning>
  Alt bulk is Premium-only for normal API keys and has a smaller limit because each lookup performs heavier detection work.
</Warning>

## Response shape

```json 200 OK theme={null}
{
  "status": 200,
  "data": {
    "results": [
      {
        "input": {
          "discordId": "123456789012345678"
        },
        "found": true,
        "data": {
          "discordId": "123456789012345678",
          "robloxId": "156319135",
          "resolved": {
            "roblox": null,
            "discord": null
          }
        },
        "error": null
      },
      {
        "input": {
          "discordId": "222222222222222222"
        },
        "found": false,
        "data": null,
        "error": {
          "code": "LINK_NOT_FOUND",
          "message": "No linked Roblox account was found for that Discord ID.",
          "details": null
        }
      }
    ],
    "count": 2,
    "foundCount": 1,
    "notFoundCount": 1,
    "errorCount": 0,
    "resolved": false
  },
  "meta": {
    "requestId": "req_abc123",
    "version": "2.0.0",
    "bulk": {
      "uniqueInputs": 2,
      "maxInputs": 50
    }
  },
  "timestamp": "2026-05-07T00:00:00.000Z"
}
```

## Result fields

<ResponseField name="results" type="object[]" required>
  Ordered result list matching the input order.
</ResponseField>

<ResponseField name="results[].input" type="object" required>
  Original input value for this item.
</ResponseField>

<ResponseField name="results[].found" type="boolean" required>
  `true` when Dock found a valid result for this item.
</ResponseField>

<ResponseField name="results[].data" type="object | null" required>
  Per-item lookup data when `found` is `true`.
</ResponseField>

<ResponseField name="results[].error" type="object | null" required>
  Per-item error when `found` is `false`.
</ResponseField>

<ResponseField name="foundCount" type="number" required>
  Number of results with data.
</ResponseField>

<ResponseField name="notFoundCount" type="number" required>
  Number of results with `LINK_NOT_FOUND`.
</ResponseField>

<ResponseField name="errorCount" type="number" required>
  Number of results that failed for reasons other than not found.
</ResponseField>

## Best practices

* Use bulk endpoints for sync jobs, dashboard hydration, and moderation queues.
* Keep `resolved=false` unless the UI needs expanded profiles.
* Retry only the items that failed for retryable reasons.
* Respect `Retry-After` if the top-level response is `429`.