Bulk Operations

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:

{
  "profile_ids": ["12345", "67890", "11111"]
}

{
  "content_ids": ["abc", "def", "ghi"]
}

{
  "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:

{
  "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

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:

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

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

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

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

Don’t use bulk endpoints for single items. Use the individual GET endpoints instead for better error messages and simpler code.

Getting started

Core concepts

Workflows

Advanced topics

When to Use Bulk Operations

Bulk Endpoints

Profiles

Content

Games

Request Format

Limits

Response Structure

Handling Partial Failures

Example: Handling Missing Items

Batching Large Requests

Quota Efficiency

Best Practices

Example: Bulk Profile Fetch

Comparison: Bulk vs Individual Requests

​When to Use Bulk Operations

​Bulk Endpoints

​Profiles

​Content

​Games

​Request Format

​Limits

​Response Structure

​Handling Partial Failures

​Example: Handling Missing Items

​Batching Large Requests

​Quota Efficiency

​Best Practices

​Example: Bulk Profile Fetch

​Comparison: Bulk vs Individual Requests

When to Use Bulk Operations

Bulk Endpoints

Profiles

Content

Games

Request Format

Limits

Response Structure

Handling Partial Failures

Example: Handling Missing Items

Batching Large Requests

Quota Efficiency

Best Practices

Example: Bulk Profile Fetch

Comparison: Bulk vs Individual Requests