Building with the API? Open the developer docs
Finmagine API & MCP — free tier to test • Pro/Max for full access • REST + MCP
Master the tier system through a complete learning overview and interactive flashcards
Every guide in this series eventually says "requires api_pro" or "api_max only." This is the guide those references point back to — the actual limits, the actual company coverage, and the actual code-level gates behind each tier, not marketing copy.
Click any card to reveal the answer. Use the search box to find a specific topic.
Finmagine's REST + MCP API has three tiers. Free requires no signup beyond an account; API Pro and API Max are paid subscriptions billed monthly and cancellable anytime.
| Tier | Price | Requests / Day | Requests / Hour | Company Universe | Screener Endpoint |
|---|---|---|---|---|---|
| Free | $0 forever | 50 | 10 | 25 NSE blue chips + 25 S&P 500 mega-caps only | No |
| API Pro | $49/mo | 1,000 | 200 | Full 5,000+ Indian / 6,400+ US universe | No |
| API Max | $149/mo | 5,000 | 1,000 | Full 5,000+ Indian / 6,400+ US universe | Yes — exclusive |
Every tier applies to both REST and MCP access equally — there's no separate "MCP-only" price or gate. One API key, one tier, works identically whether you're calling /api/v1/company/RELIANCE over REST or the equivalent get_company_profile tool over MCP.
Free tier exists to let you try the API — and Claude's MCP integration specifically — with zero commitment. No credit card, no expiry.
Free tier isn't a random 25 — it's Nifty-caliber blue chips on the Indian side and S&P 500 mega-caps on the US side, hardcoded into the auth layer:
Calling any profile, ratios, financials, or momentum tool for a symbol outside these two lists returns an error — not a truncated or degraded response. The check happens before any data is fetched.
API Pro removes the company-universe restriction entirely and raises rate limits by 20x over Free — the tier most dashboards, research tools, and single-stock agents actually need.
screen_stocks, screen_natural_language and their US equivalents) — that one capability is reserved for API Max, explained belowAPI Max includes everything API Pro includes, plus one capability that isn't available at any other tier: the screener.
Every other Pro-tier endpoint answers a question about one company you already named. The screener is different — it searches across the entire universe by condition (ROCE, PE, RS rating, D/E, sector, and more, up to 50 results per screen) and is the single most compute-intensive operation the API exposes. Finmagine's auth layer enforces this with a dedicated check, separate from the general Pro-tier gate:
This is a hard 403 — an API Pro key gets rejected exactly the same way a Free key would. There's no partial or throttled access to the screener at Pro tier; it's Max-only, full stop.
There are two completely different failure modes an agent needs to distinguish between, and they map to two different HTTP status codes.
| Status | What it means | What to do |
|---|---|---|
429 | Rate limit reached — you're within your tier's allowed operations but sent too many in the current hour or day | Back off. Daily limits reset at midnight UTC; hourly limits reset on the hour |
403 | Tier gate — the operation itself isn't available at your tier at all, regardless of how many requests you have left | No amount of waiting fixes this — the key needs to be on a higher tier |
Every successful response carries three headers so an agent can self-throttle before hitting a 429 rather than after:
The same numbers are also mirrored inside the JSON response body itself, under a standard meta block present on every call — useful for agents parsing the body rather than headers:
requests_remaining_today before a big batch job. If you're about to fan out 40 calls for a multi-stock screen result, checking this number first avoids burning your last few calls on a job that's guaranteed to 429 partway through.
Beyond Free / API Pro / API Max, there are two more tier names you may see in response metadata: premium_web and professional_web. These aren't API products you subscribe to directly — they're granted automatically to existing Finmagine website Premium and Professional subscribers as a bonus, so paying for the consumer platform also unlocks a slice of API access without a separate purchase.
| Tier | Requests / Day | Requests / Hour | Full Universe | Passes API Pro Gate |
|---|---|---|---|---|
premium_web | 500 | 100 | Yes | No |
professional_web | 2,000 | 400 | Yes | Yes |
Note the asymmetry: professional_web passes every Pro-tier-gated endpoint (it's treated as Pro-or-above internally), while premium_web gets full company-universe access but does not pass Pro-tier-only endpoint gates. Neither web tier unlocks the screener — that remains exclusively api_max.
tier field in any response's meta block to see what you already have.
| Your situation | Tier |
|---|---|
| Testing an agent integration for the first time, or a demo/proof-of-concept | Free |
| Building a dashboard, single-stock research tool, or agent that analyses named stocks across the full universe | API Pro |
| Building anything that needs to discover stocks by condition — a screener UI, a natural-language "find me stocks where..." agent | API Max |
| You already pay for Finmagine Premium or Professional (website subscription) | Check your key's tier first — you may already have premium_web or professional_web access |
Every recipe in agent-recipes.json declares its required tier explicitly, so you never have to guess — read the recipe's tier field before running it.
With llms.txt covered (discovery) and pricing tiers covered (what you're allowed to call), the next guide closes out Wave 1:
See the API & Agent Integration hub for the full 12-guide roadmap.
Finmagine gives you 30+ computed financial ratios, sector benchmarks, FII/DII flows, the Finmagine Score, and AI-powered analysis — all in one place.