Building with the API? Open the developer docs

Finmagine API & MCP — free tier to test • Pro/Max for full access • REST + MCP

Open the Docs →

← API & Agent Integration Hub ← All Feature Guides

Published: July 29, 2026 | 10 min read | Developer Guide | API & Agent Integration Series

Multimedia Learning Hub

Master the Investment Committee API through a complete learning overview and interactive flashcards

What You Will Master

The Investment Committee is Finmagine's flagship multi-agent workflow — the one behind india_screen_to_committee, the recipe the Agentic Workflow Explorer guide called "the flagship." This guide covers all 8 operations end to end, with a crucial distinction most people miss on first read: half of them cost real LLM quota, and half are completely free, deterministic computation you can call as often as you want.

What This Guide Covers:

What the Investment Committee Actually Is — the full 4-stage pipeline
The 8 Operations — and which of them are genuinely free
The 3 Deterministic Lenses — real gate thresholds, not vague "quality screening"
Stage 1: Fast Scan — the free pre-screen you should always run first
Stage 2: Start, Poll, Report — the actual LLM-powered committee run
Stage 3: Risk Audit — deterministic portfolio risk metrics, zero LLM tokens
Stage 4: Allocation — turning signals and risk into illustrative position sizes

Who This Is For:

Developers who've saved a BYO LLM key and want to run the full multi-lens analysis programmatically
Agent builders composing a screen-to-committee pipeline, matching the india_screen_to_committee recipe's real 7-step structure
Anyone who wants to minimise real LLM spend by understanding exactly which of the 8 calls are free before running any of them

Test Your Knowledge

Click any card to reveal the answer. Use the search box to find a specific topic.

What the Investment Committee Actually Is

The Investment Committee is a 4-stage pipeline over up to 10 nominated stocks — not a single call, but a sequence you compose yourself from 8 operations:

Stage	What happens	Costs real quota?
1. Fast Scan	Deterministic PHP-only scoring across 3 lenses — no LLM involved	No
2. Deep Dive	Full multi-lens LLM analysis, async, via your BYO provider	Yes — 5/24h quota
3. Risk Audit	Correlation, volatility, drawdown, beta, sector concentration	No
4. Allocation	Illustrative position-sizing from stages 2 + 3 combined	No

Only Stage 2 spends real LLM tokens and shared quota. Stages 1, 3, and 4 are pure deterministic computation over data Finmagine already has — you can run them as many times as you like, on as many candidate lists as you like, without touching your 5-runs/24h Committee quota at all.

The 8 Operations

Operation	REST	Stage	Free?
`fast_scan_committee`	POST /committee/fast-scan	1	Yes
`start_committee`	POST /committee/start	2	No
`check_committee_status`	POST /committee/poll	2	Yes (polling itself)
`get_committee_report`	GET /committee/report	2	Yes
`list_committee_runs`	GET /committee/list	—	Yes
`cancel_committee`	POST /committee/cancel	2	Yes
`compute_committee_risk`	POST /committee/risk-audit/compute	3	Yes
`allocate_committee_risk`	POST /committee/risk-audit/allocate	4	Yes

All 8 require API Pro tier — but tier gating and quota consumption are two different things. Being on API Pro gives you access to the endpoint; only start_committee actually draws down your 5-runs/24h allowance.

THE FOUNDATION

The 3 Deterministic Lenses

Both Fast Scan and the full LLM run evaluate every symbol through the same 3 lenses — real, quantitative gates with actual thresholds, not vague "quality screening":

🇮🇳 India

Lens	Min ROCE	Max D/E	Max Pledge %
`quality_compounder`	15%	1.0	10%
`india_growth`	10%	2.0	10%
`value_safety`	12%	0.75	10%

🇺🇸 US

Lens	Min ROCE	Max D/E
`quality_compounder`	12%	1.5
`us_growth`	5%	3.0
`value_safety`	8%	1.0

The lens set swaps automatically based on market — you don't choose it manually. India runs use quality_compounder + india_growth + value_safety; US runs swap the middle lens for us_growth with its own thresholds and drop the pledge check entirely (share pledging isn't an applicable US risk signal the way it is for Indian promoters).

Each lens produces a gate_passed boolean, a gate_reason, a deterministic score (det_score), and a directional signal — this is exactly what powers Fast Scan's free, instant pre-screen, and is fed into the full LLM analysis as structured context rather than left for the LLM to compute itself.

STAGE 1

Fast Scan — Always Run This First

POST /api/v1/committee/fast-scan
{ "symbols": ["RELIANCE", "TCS", "HDFCBANK"], "market": "india" }

Synchronous, up to 10 symbols, zero LLM tokens, and — critically — does not count against the 5-runs/24h Committee quota. It exists specifically so you can see whether a full LLM run is even worth spending before you spend it.

// Response — mode is always "fast", total_cost is always 0
{
  "ok": true, "mode": "fast", "total_cost": 0,
  "results": {
    "RELIANCE": {
      "company_name": "Reliance Industries",
      "lenses": {
        "quality_compounder": { "gate_passed": true, "det_score": 78, "signal": "bullish" },
        "india_growth": { "gate_passed": true,  "det_score": 71, "signal": "bullish" },
        "value_safety": { "gate_passed": false, "gate_reason": "D/E 1.2 exceeds 0.75 cap", ... }
      },
      "agreement_score": 67, "committee_signal": "lean_bullish"
    }
  }
}

Use Fast Scan's committee_signal to narrow your shortlist before Stage 2. The india_screen_to_committee agent recipe does exactly this — it screens the full universe, runs Fast Scan on the results, and only spends a real LLM committee run on the survivors that already show a favorable deterministic signal.

STAGE 2

Start, Poll, Report — the Real LLM Run

Start

POST /api/v1/committee/start
{
  "symbols": ["RELIANCE", "TCS"],
  "provider": "anthropic"
}

Field	Required?	Notes
`symbols`	Yes	Up to 10
`provider`	Yes — no auto-resolve	Must be an already-saved BYO provider, same as Research Presets — call `list_byo_keys` first
`lenses`	No	Defaults to all 3 for the detected market
`market`	No	Auto-detected from symbol format if omitted

Returns immediately with job_id, vps_run_id, and status: "running" — the actual multi-lens analysis runs asynchronously on the swarm. On failure, the error code is one of no_symbols, missing_provider, quota_exceeded, no_key, or swarm_unavailable — check the HTTP status alongside this code to distinguish "you made a mistake" from "the quota is exhausted" from "the swarm itself is down."

Quota: 5 runs per 24 hours per account, shared with web usage — same shared-pool pattern as Research Presets' 10/24h. A run started via the API and one started from the Strategy Lab page draw from the same daily allowance.

Poll

POST /api/v1/committee/poll
{ "job_id": "abc123..." }

Same DB-cache-vs-live-swarm-call pattern as Research Preset polling — terminal states are served from a cache, non-terminal polls make a live call. Either job_id or vps_run_id works, but at least one is required.

Report

GET /api/v1/committee/report?job_id=abc123...

Once terminal, fetch the full report — usable while a run is still in progress too, showing whatever has completed so far:

report.committee — per-symbol committee_signal, agreement_score, research_stance, illustrative_weight_range, dissent_summary, verdict
report.signals — per-lens detail: signal, score, confidence, gate result/reason, evidence, and concerns for each lens on each symbol

dissent_summary is worth reading even when the overall verdict is clear. A high agreement_score with unanimous bullish lens signals is a different, stronger signal than the same committee_signal reached with one lens dissenting — the report gives you that nuance directly rather than collapsing it into a single number.

STAGE 3

Risk Audit — Deterministic, Zero LLM Tokens

POST /api/v1/committee/risk-audit/compute
{ "symbols": ["RELIANCE", "TCS"], "days": 252 }

Pure computation over real price history — correlation matrix, annualized volatility, max drawdown, beta versus the market benchmark (Nifty for India, SPY for US), sector concentration, and a composite portfolio risk score.

{
  "ok": true,
  "per_stock": {
    "RELIANCE": { "vol_annual": 28.4, "max_drawdown": -18.2, "beta": 1.12, "rs_rating": 76 }
  },
  "correlation": { ... }, "sector_weights": { ... },
  "portfolio_vol": 24.1, "avg_correlation": 0.42, "risk_score": 58
}

This costs nothing and has no quota — run it on any candidate list, independent of whether you've run a Committee analysis on those symbols at all. It's genuinely useful standalone, not just as an input to Stage 4.

STAGE 4

Allocation — Committee Stances Meet Risk Metrics

POST /api/v1/committee/risk-audit/allocate
{
  "symbols": ["RELIANCE", "TCS"],
  "committee": { /* from get_committee_report */ },
  "risk_metrics": { /* from compute_committee_risk */ }
}

Deterministic position-sizing — turns the committee's stances plus the risk audit's metrics into weight recommendations, capped at a maximum 20% per position:

{
  "ok": true,
  "allocations": { "RELIANCE": 18.5, "TCS": 14.2, "Cash": 67.3 },
  "methodology": ["Weight scaled down for RELIANCE due to 1.12 beta and 0.42 avg correlation", ...]
}

These weights are illustrative only, not investment advice — the API's own response says so explicitly. The 20%-per-position cap and the methodology notes are there to make the reasoning inspectable, but this is a deterministic heuristic over committee output and risk metrics, not a portfolio manager's judgment. Treat it as a structured starting point for your own analysis, not a final answer.

Typically fed the outputs of Stage 2 (get_committee_report) and Stage 3 (compute_committee_risk) for the same symbol set — this is the step that actually closes the loop from "what does the committee think" to "how much of each, if anything."

Cancel and Review History

cancel_committee (needs job_id) stops a running job — free, no quota consumed by the cancellation itself. list_committee_runs returns your most recent 20 runs, any status, the same pattern as Research Presets' history endpoint.

What's Next

This closes out the "Auth & the Flagship LLM Features" group — BYO keys, Research Presets, and now the Investment Committee. The next guide moves into pre-built, composable tool chains:

agent-recipes.json — Pre-Built Workflow Recipes for AI Agents — the file that turns everything covered so far into 10 ready-to-run, verified-executable chains, including india_screen_to_committee, the exact 4-stage pipeline this guide walked through

See the API & Agent Integration hub for the full 12-guide roadmap.

Ready to Analyse Indian Stocks Like a Pro?

Finmagine gives you 30+ computed financial ratios, sector benchmarks, FII/DII flows, the Finmagine Score, and AI-powered analysis — all in one place.

Analyse a Stock → Create Free Account