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.

Raise a monthly limit with usage packs

If your team needs more than its plan includes, add usage packs. Each pack raises one monthly limit, and you can hold up to 10 packs of each kind.

• Teams on the Core plan buy packs on the team billing page in the app. These teams show business in the X-Plan-Tier header.
• Adding packs is charged when you confirm, and the higher limit applies as soon as the payment goes through. Monthly plans pay a full month for the new packs. Quarterly and annual plans pay for the rest of the term.
• Removing packs takes effect at the end of the time you've paid for. You keep the higher limit until then.
• The new limit shows in X-RateLimit-Limit and X-RateLimit-Remaining from then on.

Core teams aren't blocked at a monthly limit today. Requests over the limit still succeed, and X-RateLimit-Remaining reads 0. Add packs when it gets close, so your usage stays inside what you pay for.

See every plan and pack price on the pricing page.

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. Add packs before you run out - If you regularly need more, raise the limit with usage packs (see above), or contact support to discuss a custom plan