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
  • Scope: Rate limits apply across all your API keys
  • System: Sliding hourly windows (not fixed periods)

​
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.