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-25 items per call)
Reduce HTTP overhead and improve performance
Minimize credit 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: 25 items per request. More returns a 400 validation error whose error.details say, for example, profile_ids cannot exceed 25 items
Credit cost: 0.01 credit per call, whatever the number of items

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 25 items, split them into batches:

async function fetchManyProfiles(profileIds) {
  const batchSize = 25;
  const batches = [];

  // Split into batches of 25
  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

A bulk call costs 0.01 credit, whatever the number of items it names:

Operation	Credit Cost
Single profile request	0.01 credit
Bulk request (25 profiles)	0.01 credit
25 individual requests	0.25 credit

Bulk operations also:

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 25 items into multiple batches
Monitor quota: Each batch is one call against your credits and your per-minute rate limit
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)
Credit cost	0.01 credit per call	0.01 credit per item
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