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

# Bulk Operations

> Efficiently fetch multiple items in a single request using bulk endpoints

Bulk endpoints allow you to fetch multiple items (profiles, content, or games) in a single API request. This is more efficient than making individual requests and helps you stay within rate limits.

## When to Use Bulk Operations

Use bulk endpoints when you need to:

* Fetch **multiple items** (2-100 items)
* **Reduce HTTP overhead** and improve performance
* **Minimize quota usage** for multiple items
* **Avoid URL length limits** (POST requests don't have URL length restrictions)

## Bulk Endpoints

The API provides bulk endpoints for three resource types:

### Profiles

```
POST /platforms/{platform}/profiles
```

### Content

```
POST /platforms/{platform}/content
```

### Games

```
POST /platforms/{platform}/games
```

## Request Format

All bulk endpoints use the same request structure:

```json theme={null}
{
  "profile_ids": ["12345", "67890", "11111"]
}
```

or

```json theme={null}
{
  "content_ids": ["abc", "def", "ghi"]
}
```

or

```json theme={null}
{
  "game_ids": ["2011938005", "491487", "490377"]
}
```

## Limits

* **Minimum**: 1 item
* **Maximum**: 100 items per request
* **Quota cost**: 1 quota unit per item requested

## Response Structure

Bulk responses include metadata about which items were found and which were missing:

```json theme={null}
{
  "payload": [
    { "id": "12345", "name": "creator1", ... },
    { "id": "67890", "name": "creator2", ... }
  ],
  "meta": {
    "missing_ids": ["11111"]
  }
}
```

## Handling Partial Failures

Bulk operations are **partial success** operations. If some items are missing:

* The request still succeeds (HTTP 200)
* Found items are returned in `payload`
* Missing items are listed in `meta.missing_ids`
* You can check `meta.found_ids` to verify which items were returned

### Example: Handling Missing Items

```javascript theme={null}
async function fetchProfiles(profileIds) {
  const response = await fetch(
    `/platforms/twitch/profiles`,
    {
      method: 'POST',
      headers: {
        'x-api-key': 'YOUR_API_KEY',
        'Content-Type': 'application/json'
      },
      body: JSON.stringify({ profile_ids: profileIds })
    }
  );

  const data = await response.json();

  // Check for missing items
  if (data.meta.missing_ids.length > 0) {
    console.warn(`Missing profiles: ${data.meta.missing_ids.join(', ')}`);
  }

  return data.payload;
}
```

## Batching Large Requests

If you need to fetch more than 100 items, split them into batches:

```javascript theme={null}
async function fetchManyProfiles(profileIds) {
  const batchSize = 100;
  const batches = [];

  // Split into batches of 100
  for (let i = 0; i < profileIds.length; i += batchSize) {
    batches.push(profileIds.slice(i, i + batchSize));
  }

  // Fetch all batches
  const results = await Promise.all(
    batches.map(batch =>
      fetch('/platforms/twitch/profiles', {
        method: 'POST',
        headers: {
          'x-api-key': 'YOUR_API_KEY',
          'Content-Type': 'application/json'
        },
        body: JSON.stringify({ profile_ids: batch })
      }).then(r => r.json())
    )
  );

  // Combine results
  return results.flatMap(r => r.payload);
}
```

## Quota Efficiency

Bulk operations consume quota equal to the number of items requested:

| Operation                  | Quota Cost |
| -------------------------- | ---------- |
| Single profile request     | 1 unit     |
| Bulk request (50 profiles) | 50 units   |
| 50 individual requests     | 50 units   |

**Note**: Bulk operations don't save quota, but they:

* Reduce HTTP overhead
* Improve performance (single round-trip)
* Avoid rate limit spikes from many concurrent requests

## Best Practices

<Tip>
  Use bulk endpoints whenever you need 2+ items. The performance benefits outweigh the complexity.
</Tip>

* **Deduplicate IDs**: Remove duplicate IDs before sending (the API may dedupe, but it's better to do it client-side)
* **Handle missing items**: Always check `missing_ids` and handle gracefully
* **Batch large requests**: Split requests larger than 100 items into multiple batches
* **Monitor quota**: Bulk requests consume quota quickly; monitor your usage
* **Error handling**: Implement retry logic for failed bulk requests

## Example: Bulk Profile Fetch

```bash theme={null}
curl -X POST \
  -H "x-api-key: YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "profile_ids": [
      "484563826",
      "775305965",
      "116216805"
    ]
  }' \
  https://external-api.streamforge.com/platforms/twitch/profiles
```

## Comparison: Bulk vs Individual Requests

| Aspect         | Bulk            | Individual       |
| -------------- | --------------- | ---------------- |
| HTTP requests  | 1               | N (one per item) |
| Quota cost     | Same            | Same             |
| Performance    | Faster          | Slower           |
| Error handling | Partial success | All-or-nothing   |
| URL length     | No limit        | Limited          |

<Warning>
  Don't use bulk endpoints for single items. Use the individual GET endpoints instead for better error messages and simpler code.
</Warning>