Credits

How the Filed API credit system works — what credits are, how they're counted, limits by plan, and what happens when you hit your limit.

What Are Credits?

Credits are the unit of measurement for Filed API usage. Every API request you make costs a certain number of credits, depending on the endpoint. Your plan determines how many credits you get each month.

How Credits Are Counted

Different endpoints cost different amounts based on the data they return:

Endpoint	Credits
`/v1/search`	1
`/v1/entity/{id}`	1
`/v1/entity/{id}?include=federal`	3
`/v1/batch` (per query)	1 (+2 with federal)
`/v1/sec/search`	2
`/v1/lobbying/search`	2
`/v1/contracts/search`	2

Batch Credit Calculation

For batch requests, credits are calculated per query in the batch:

Basic query: 1 credit each
Query with include: "federal": 3 credits each
Cross-state query (no state specified): 5 credits each

Example: A batch of 3 queries where 1 has federal enrichment = 1 + 1 + 3 = 5 credits total.

Credit Limits by Plan

Plan	Monthly Credits	Rate Limit	Price
Free	100	10 req/min	$0
Developer	1,000	60 req/min	$29/mo
Business	10,000	120 req/min	$99/mo
Scale	50,000	300 req/min	$299/mo

Need more than 50,000 credits? Contact us for custom enterprise pricing.

When Credits Reset

Credits reset monthly on the anniversary of your account creation. Unused credits do not roll over.

What Happens When You Hit the Limit

When you exceed your monthly credit allowance, the API returns a 429 Too Many Requests response:

{
  "error": "Monthly credit limit exceeded",
  "limit": 100,
  "used": 100,
  "resets_at": "2026-04-01T00:00:00Z"
}

The response includes:

limit — your plan's monthly credit allowance
used — how many credits you've consumed this period
resets_at — when your credits will reset

Per-minute rate limits also return 429 but reset within 60 seconds.

Upgrading

If you consistently hit your credit limit, upgrade your plan for more credits and higher rate limits. See the full rate limits documentation for more details.