Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.bags.fm/llms.txt

Use this file to discover all available pages before exploring further.

The Bags API implements rate limiting to ensure fair usage and system stability.

​
Rate Limit Overview

  • Rate limit: 1,000 requests per hour per user and per ip
  • Scope: Rate limits apply across all your API keys
  • System: Sliding hourly windows (not fixed periods)

​
Endpoint-Specific Limits

Certain endpoints may enforce additional, endpoint-specific rate limits. These limits are intentionally not publicly disclosed and apply only to the affected endpoints. Under normal usage patterns you should not encounter these limits. If you do get rate limited, please reach out to us so we can help.

​
Response Headers

Monitor your API usage through response headers included with every request:
  • X-RateLimit-Limit: Total requests allowed per hour (1,000)
  • X-RateLimit-Remaining: Requests remaining in current window
  • X-RateLimit-Reset: Unix timestamp when the limit resets

​
Sliding Window System

Rate limits use sliding hourly windows rather than fixed periods:
  • Window 1: 1:00 PM - 2:00 PM
  • Window 2: 2:00 PM - 3:00 PM
  • And so on…
This means your rate limit resets continuously rather than at fixed times.

​
Monitoring Usage

curl -I -X GET 'https://public-api-v2.bags.fm/ping' \
  -H 'x-api-key: YOUR_API_KEY'

# Response headers include:
# X-RateLimit-Limit: 1000
# X-RateLimit-Remaining: 999
# X-RateLimit-Reset: 1672531200

​
Rate Limit Exceeded

When you exceed your rate limit, the API returns a 429 status with additional information: 
{
  "success": false,
  "error": "Rate limit exceeded",
  "limit": 1000,
  "remaining": 0,
  "resetTime": 1672531200
}

​
Rate Limit Planning

​
Calculate Request Budget

Plan your API usage based on your application’s needs:
  • 1,000 requests/hour = ~16.7 requests/minute = ~0.28 requests/second
  • High-frequency apps: Consider request batching or caching
  • Background jobs: Spread requests across the hour
Rate limits apply across all API keys for your account. Creating multiple API keys does not increase your rate limit.
If you need to increase your rate limit, please contact us.