Firmhound API Pricing & Limits
Version: 1.0.0 Last Updated: 2025-12-13 Canonical Source: canonical-variables.yml
This document serves as the master reference for all pricing and limits. All values use canonical tokens and are validated by scripts/validate-canonical-values.py.
Rate Limits by Tier
Rate limits control how fast you can call the API. Limits reset at window boundaries.
| Tier | Per Minute | Per Day | Burst (5s) | Price |
|---|---|---|---|---|
| Free | /min | /day | $0 | |
| Starter | /min | /day | /mo | |
| Growth | /min | /day | Contact sales | |
| Scale | /min | /day | Contact sales |
Implementation: PostgreSQL-backed distributed rate limiting (FS-6016)
Free Tier Limits
Free tier has a lifetime usage limit (not a rate limit):
| Metric | Value | Description |
|---|---|---|
| Total calls | Lifetime API calls before paywall | |
| Warning at 75% | Soft warning displayed | |
| Warning at 90% | Urgent warning displayed |
Note: This is different from rate limits which reset daily.
Per-Record API Pricing
Usage-based pricing for API calls. Charged per record/result returned.
Search & Discovery
| Endpoint Type | Price | Description |
|---|---|---|
| Search results | /record | /v1/gps, /v1/funds, /v1/search |
| GP Profile | /profile | /v1/gps/{crd} |
| Fund Profile | /profile | /v1/funds/{id} |
People Data
| Endpoint Type | Price | Description |
|---|---|---|
| Team roster | /person | /v1/gps/{crd}/team (max 100) |
| Person profile | /person | /v1/people/{id} |
| Career history | /person | /v1/people/{id}/career |
| Alumni data | /person | /v1/gps/{crd}/alumni (max 100) |
Exports & Analytics
| Endpoint Type | Price | Description |
|---|---|---|
| Export GP/Fund | /record | /v1/gps/export, /v1/funds/export |
| Export people | /person | /v1/people/export |
| Historical data | /request | /v1/gps/{crd}/amendments |
| Analytics | /request | /v1/gps/{crd}/metrics |
Free Endpoints
These endpoints are always free:
/v1/auth/*- Authentication/v1/api-keys/*- Key management/v1/usage/*- Usage tracking/v1/billing/*- Billing info/health,/status- Health checks
Volume Discounts
Discounts applied automatically at billing based on monthly usage:
| Threshold | Discount | Description |
|---|---|---|
| Base rate | 0% | Standard pricing |
| + records/month | off | Mid-volume |
| + records/month | off | High-volume |
| + records/month | Contact sales |
Subscription Pricing
For users who prefer predictable monthly billing:
| Plan | Price | Rate Limits |
|---|---|---|
| Free | $0 | |
| Pro | ||
| Premier | Unlimited | |
| Student | Same as Pro |
Annual plans: discount
Trial Limits
| Feature | Limit |
|---|---|
| Exports | |
| Saved searches | |
| Duration | days |
Quick Reference
Short Tokens
Use these in inline text:
| Token | Value |
|---|---|
| |
| |
| |
| |
| |
| |
| |
| |
|
Implementation Files
| Purpose | File |
|---|---|
| Canonical values | canonical-variables.yml |
| Rate limit config | src/api/config/rate_limits.py |
| API pricing config | config/api_pricing.yaml |
| Pricing calculator | src/api/utils/pricing.py |
| Rate limit middleware | src/api/middleware/pg_rate_limiter.py |
| Free tier limiter | src/api/middleware/free_tier_limiter.py |
| Usage tracker | src/api/middleware/usage_tracker.py |
Validation
To check for stale values:
python3 scripts/validate-canonical-values.py --tier1To render docs with actual values:
python3 scripts/render-doc-variables.py --src docs --out docs/.rendered --inject-headers