The Streamforge External API uses a weight-based quota system. Understanding how quota works helps you plan your API consumption.
Quota Costs
| Request Type | Quota Cost |
|---|
| Single item request | 1 unit |
| Bulk request (N items) | N units (1 per item) |
| List request | 1 unit per item returned |
| Analysis endpoint | 100 units |
| Audience endpoint | 100 units |
| Email endpoint | 10 units |
| Socials endpoint | 10 units |
Optimizing Quota Usage
Use Bulk Operations
Instead of making multiple individual requests, use bulk endpoints. Fetching 50 profiles individually costs 50 quota units plus 50 HTTP requests. Fetching them via the bulk endpoint costs 50 quota units but only 1 HTTP request.
Choose Appropriate Limits
List endpoints consume quota equal to items returned. If you only need 10 items, don’t request 50.
Cache Expensive Operations
The /analysis and /audience endpoints cost 100 quota units each. This data is regenerated infrequently (typically monthly), so cache results aggressively.
Filter Before Fetching Advanced Data
Fetch basic profile data first (1 quota per profile), filter to candidates that meet your criteria, then fetch advanced insights only for the filtered set.
Handling Rate Limits
When you exceed a quota limit:
- The API returns
429 Too Many Requests
- The
Retry-After header indicates seconds until the window resets
- Wait the specified time before retrying
Implement exponential backoff for retries. Distribute requests over time rather than sending bursts.
Quota Budget Planning
| Use Case | Typical Quota/Day |
|---|
| Basic profile lookups | 1,000-10,000 |
| Content analysis | 5,000-50,000 |
| Creator discovery with advanced insights | 10,000-100,000 |
Monitor your quota usage via the rate limit headers on each response. Set up alerts when approaching 80% of your limits.
Best Practices
- Use bulk endpoints: Always prefer bulk operations for multiple items
- Cache expensive requests: Cache
/analysis and /audience responses for extended periods
- Request only what you need: Use appropriate
limit values on list endpoints
- Monitor headers: Track
X-RateLimit-* headers to understand usage
- Handle 429 errors: Implement retry logic with backoff
- Distribute load: Stagger requests to avoid quota spikes
Advanced insights cost 100 quota units each. A workflow that fetches analysis and audience data for 100 creators consumes 20,000 quota units.
