Usage & Rate Limits

Response Headers

Every API response includes these headers to help you monitor your usage:

What counts against a lookup allowance

Podcast and episode lookups are counted once per resource per usage period. The first time you fetch a given podcast, it uses one podcast lookup. Every later request for that same podcast in the same usage period is free, however many times you make it.

• Counting is by resource, not by request — fetching the same podcast by Pod Engine id, slug or Apple id all resolve to the same podcast and are counted once.
• Episode lookups work the same way, so polling an episode while you wait for a transcript costs a single lookup.
• Requests that fail are never counted. A 404 for a podcast that does not exist uses none of your allowance.
• Allowances reset at the start of each usage period, so the first lookup of a resource in a new period counts again.

Searches and transcript downloads are counted per request — distinct searches are distinct work, so the once-per-period rule does not apply to them.

Per-IP rate limit

On top of the per-plan monthly limits, all API traffic is throttled per IP at the edge:

• 3 requests/second sustained
• Short bursts up to 10 requests are allowed before throttling kicks in

Exceeding the per-IP limit returns 429 Too Many Requests. Spread load across requests or implement exponential backoff (see below).

Rate Limit Errors

{
  "success": false,
  "error": {
    "code": "RATE_LIMIT_EXCEEDED",
    "message": "Monthly limit of 100 search requests exceeded"
  }
}

Use the X-RateLimit-Reset header to determine when you can retry:

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

    if (response.status === 429) {
      const resetTime = response.headers.get('X-RateLimit-Reset');
      const waitMs = resetTime
        ? (parseInt(resetTime) * 1000) - Date.now()
        : Math.pow(2, attempt) * 1000; // Exponential backoff

      console.log(`Rate limited. Waiting ${waitMs}ms before retry...`);
      await new Promise(resolve => setTimeout(resolve, Math.max(waitMs, 1000)));
      continue;
    }

    return response;
  }

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

Best Practices

• 1. Monitor remaining requests - Check the X-RateLimit-Remaining header to avoid hitting limits
• 2. Implement retry logic - Use exponential backoff when you receive a 429 response
• 3. Cache responses - Store and reuse API responses where appropriate to reduce unnecessary requests
• 4. Batch requests efficiently - Use bulk endpoints where available instead of making many individual requests
• 5. Contact support for increases - If you consistently need higher limits, reach out to discuss your needs