Skip to main content

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 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"]
}
or 
{
  "content_ids": ["abc", "def", "ghi"]
}
or 
{
  "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:
OperationQuota Cost
Single profile request1 unit
Bulk request (50 profiles)50 units
50 individual requests50 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

AspectBulkIndividual
HTTP requests1N (one per item)
Quota costSameSame
PerformanceFasterSlower
Error handlingPartial successAll-or-nothing
URL lengthNo limitLimited
Don’t use bulk endpoints for single items. Use the individual GET endpoints instead for better error messages and simpler code.