Skip to main content
Every request must include a valid API key. This key also determines your quota allocation for the rolling minute/hour/day windows.

​
Supplying the API key

Use the x-api-key header: 
GET /platforms/twitch/profiles/12345 HTTP/1.1
Host: external-api.streamforge.com
x-api-key: YOUR_API_KEY
Requests without the header return 401 Unauthorized. Unknown keys return 403 Forbidden.

​
Rate limits

Each key is provisioned with per-window quotas (defaults shown below; your allocations may differ):
WindowDefault allowanceHeader for limitHeader for remainingReset header
Minute1,000 requestsX-RateLimit-minute-limitX-RateLimit-minute-remainingX-RateLimit-minute-reset
Hour60,000 requestsX-RateLimit-hour-limitX-RateLimit-hour-remainingX-RateLimit-hour-reset
Day1,500,000 requestsX-RateLimit-day-limitX-RateLimit-day-remainingX-RateLimit-day-reset

​
Weight-based quota system

Quota consumption varies by request type:
  • Single item requests: 1 quota unit (e.g., fetching one profile or one content item)
  • Bulk requests: 1 quota unit per item requested (e.g., fetching 100 profiles costs 100 quota units)
  • List requests: 1 quota unit per item returned (e.g., limit=25 costs 25 quota units)
  • Analysis/Audience endpoints: 100 quota units per request
  • Email/Socials endpoints: 10 quota units per request
Examples:
  • GET /platforms/twitch/profiles/12345 → 1 quota unit
  • POST /platforms/twitch/profiles with 50 profile IDs → 50 quota units
  • GET /platforms/twitch/content?limit=25 → 25 quota units
  • GET /platforms/twitch/profiles/12345/analysis → 100 quota units
  • GET /platforms/twitch/profiles/12345/email → 10 quota units
  • GET /platforms/twitch/profiles/12345/socials → 10 quota units
This ensures fair usage: bulk operations consume quota proportional to the data retrieved. When a limit is hit:
  • The API returns 429 Too Many Requests.
  • Response headers still include the remaining quotas (often 0) and a Retry-After header indicating seconds until the smallest exceeded window resets.
  • You should back off and retry after the specified time to avoid throttling loops.

​
Interpreting headers

Example response headers: 
X-RateLimit-minute-limit: 1000
X-RateLimit-minute-remaining: 428
X-RateLimit-minute-reset: 1731001800
X-RateLimit-hour-limit: 60000
X-RateLimit-hour-remaining: 54210
X-RateLimit-hour-reset: 1731005400
X-RateLimit-day-limit: 1500000
X-RateLimit-day-remaining: 1487320
X-RateLimit-day-reset: 1731086400
  • *-limit: Your total allocation for the window.
  • *-remaining: How many requests you can still make before the window is exhausted.
  • *-reset: UNIX timestamp (seconds) when that window resets.

​
Usage logging

We log every request to an internal usage stream (Valkey). If you need exports for billing/reconciliation, contact support.

​
Key rotation & revocation

  • Keys can be rotated by the Streamforge team on request. Rotate keys used in production carefully; old keys are immediately invalid.
  • If a key is compromised, we can revoke it (sets is_active=false) and cache entries are invalidated within seconds. Expect 403 responses once revoked.

​
Best practices

  • Distribute load: If you run high-concurrency jobs, stagger requests to avoid spikes at window boundaries.
  • Handle 429: Implement an exponential backoff and respect Retry-After.
  • Monitor usage: Build dashboards using the rate-limit headers so you know when you’re close to limits.
  • Regional routing: The API is fronted in multiple regions. Use the closest region for lower latency (see the Reference section).