> ## Documentation Index
> Fetch the complete documentation index at: https://docksystems.mintlify.site/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.

> [!NOTE]
>
> Bulk responses preserve input order, including duplicate input values. Missing records return per-item errors instead of failing the full request.

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

**guildId** `string`

Required for guild-scoped keys. Optional for global keys.

**resolved** `boolean`

Defaults to `false`. Adds resolved profile data when allowed by the endpoint and plan.

## 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
  }'
```

**discordIds** `string[]` *required*

Discord user IDs to resolve. Maximum `50`.

## 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
  }'
```

**robloxIds** `string[]` *required*

Roblox user IDs to resolve. Maximum `50`.

## 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
  }'
```

**robloxIds** `string[]` *required*

Roblox user IDs to use as alt-detection seeds. Maximum `10`.

> [!WARNING]
>
> Alt bulk is Premium-only for normal API keys and has a smaller limit because each lookup performs heavier detection work.

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

**results** `object[]` *required*

Ordered result list matching the input order.

**results\[].input** `object` *required*

Original input value for this item.

**results\[].found** `boolean` *required*

`true` when Dock found a valid result for this item.

**results\[].data** `object | null` *required*

Per-item lookup data when `found` is `true`.

**results\[].error** `object | null` *required*

Per-item error when `found` is `false`.

**foundCount** `number` *required*

Number of results with data.

**notFoundCount** `number` *required*

Number of results with `LINK_NOT_FOUND`.

**errorCount** `number` *required*

Number of results that failed for reasons other than not found.

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


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.