Rate Limits

The API enforces per-key rate limits to ensure fair usage.

Rate limits apply per API key. If you need higher limits, contact api@listenbrief.com.

Limits

Request type	Limit	Window
Read requests (GET)	600	per minute
Write requests (POST / PATCH / DELETE)	60	per minute
Rate limit key	API key (not IP address)

Rate limit headers

Every API response includes the following headers so you can track your current usage without hitting a 429:

Header	Description
`X-RateLimit-Limit`	Maximum requests allowed in the current window
`X-RateLimit-Remaining`	Requests remaining before the limit is reached
`X-RateLimit-Reset`	Unix timestamp (seconds) when the window resets
`Retry-After`	Seconds to wait before retrying (present on 429 responses only)

Handling 429 errors

When you exceed the rate limit the API returns 429 Too Many Requests. Read the Retry-After header and wait that many seconds before retrying:

async function apiFetch(url, options, maxRetries = 3) {
  for (let attempt = 0; attempt < maxRetries; attempt++) {
    const response = await fetch(url, options);

    if (response.status === 429) {
      const retryAfter = parseInt(
        response.headers.get('Retry-After') || '60', 10
      );
      console.log(`Rate limited. Retrying in ${retryAfter}s...`);
      await new Promise(r => setTimeout(r, retryAfter * 1000));
      continue; // retry request
    }

    return response;
  }
  throw new Error('Max retries exceeded');
}

import time
import requests

def api_fetch(url: str, *, max_retries: int = 3, **kwargs):
    for attempt in range(max_retries):
        response = requests.request(url=url, **kwargs)

        if response.status_code == 429:
            retry_after = int(response.headers.get('Retry-After', 60))
            print(f"Rate limited. Retrying in {retry_after}s...")
            time.sleep(retry_after)
            continue  # retry request

        return response

    raise RuntimeError("Max retries exceeded")

Checking current usage

The GET /api/v1/usage endpoint returns your request counts and briefing generation quota for the current billing period. Requires the usage:read scope.

curl https://listenbrief.com/api/v1/usage \
  -H "Authorization: Bearer lb_api_YOUR_KEY"

const res = await fetch('https://listenbrief.com/api/v1/usage', {
  headers: { Authorization: `Bearer ${process.env.LISTENBRIEF_API_KEY}` },
});
const usage = await res.json();
console.log(usage);

Best practices

Cache read responses on your side to reduce redundant GET calls.
Batch write operations where possible — for example, update multiple sources in sequence rather than bursting many requests simultaneously.
Use webhooks instead of polling for briefing completion — polling burns your read quota unnecessarily.
Implement exponential backoff with jitter when retrying after a 429; plain linear waits can cause thundering-herd patterns under load.
Monitor X-RateLimit-Remaining proactively and throttle your client when it approaches zero, rather than waiting for a 429.