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