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 | 8 min read | Developer Guide | API & Agent Integration Series

Multimedia Learning Hub

Master the US momentum and trader scan endpoints through a complete learning overview and interactive flashcards

What You Will Master

This guide opens the final group in the series — named, composable workflows. Before chaining calls together, it's worth knowing the 3 raw endpoints those workflows are built from: one for a single stock's momentum profile, one free market-wide RS leaderboard, and one precomputed technical scan library with 7 real scan types. This guide covers all 3 in isolation, with the actual scan definitions and the freshness heuristic that decides whether a result is trustworthy.

What This Guide Covers:

Three Endpoints, Three Different Jobs — single stock, market leaderboard, scan library
us_get_momentum in Depth — the single-stock technical profile
us_market_momentum in Depth — the free RS leaderboard
us_market_trader_scan in Depth — 7 real scan types, explained
The Effective Score's VCP Bump — a genuine ranking detail worth knowing
Freshness: is_stale and the Weekend-Aware Heuristic
What's Next — how these 3 endpoints become named workflows

Who This Is For:

Developers building a US technical screener or watchlist tool — these are the raw data sources
Agent builders who want to understand exactly what "Stage 2" or "BRS" means before composing them into a query
Anyone who's used /us/picks/?list=trader on the website and wants the same data programmatically

Test Your Knowledge

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

Three Endpoints, Three Different Jobs

Endpoint	Question it answers	Tier
`us_get_momentum`	"What's this one stock's technical picture right now?"	API Pro
`us_market_momentum`	"Which stocks in the whole US market have the strongest relative strength?"	Free — no tier gate
`us_market_trader_scan`	"Which stocks match a specific precomputed technical pattern right now?"	API Pro

us_market_momentum is genuinely free, with no tier gate at all — not even Free-tier's usual 25-symbol restriction applies conceptually here, since it's a leaderboard, not a per-symbol lookup. The underlying RS data is fully public, so Finmagine doesn't gate it behind a subscription the way it does most other operations.

SINGLE STOCK

us_get_momentum in Depth

GET /api/v1/us/company/momentum?symbol=NVDA

A single stock's full technical momentum profile:

RS rating — IBD-style 1-99 relative strength
1W / 1M / 3M returns
RSI-14
EMA-20, SMA-50, SMA-200 — each with an above/below flag relative to current price
Distance from 52-week high
Latest ECS score (Earnings Catalyst Score)

The above/below flags on the moving averages save you a comparison step. Rather than returning raw SMA-50/SMA-200 values and making you compare them to the current price yourself, the response tells you directly whether price is currently above or below each — useful for a quick trend-alignment check without extra client-side logic.

MARKET LEADERBOARD

us_market_momentum in Depth

GET /api/v1/us/market/momentum?sector=Technology&limit=20

Top US stocks ranked by RS rating (IBD-style 1-99) against the full US universe, sorted descending. An RS rating of 90 or above is considered elite momentum.

Param	Required?	Notes
`sector`	No	Optional filter to one sector
`limit`	No	Results to return — tier-capped (Free tier's normal caps still apply to result count, even though the endpoint itself has no tier gate)

Response includes stocks (the ranked array), plus count and sorted_by metadata.

SCAN LIBRARY

us_market_trader_scan in Depth

GET /api/v1/us/market/trader-scan?scan_type=stage2&limit=25

US stocks matching one of 7 precomputed technical scans — the exact same data source the website's /us/picks/?list=trader page uses (via a shared fetch function, not a duplicated query).

scan_type	Label	What it identifies
`all`	All Signals	Every scan type combined — the default if omitted
`stage2`	Stage 2 Breakout	Weinstein-style Stage 2 uptrend — price above rising SMA-200, confirmed advancing phase
`nearHigh`	Near 52-Week High	Trading close to its 52-week high — a classic momentum continuation signal
`stage2nh`	Stage 2 + Near High	Combined — both conditions true simultaneously, a tighter, higher-conviction filter
`highVol`	High Volume	Trading on unusually high volume relative to its own average — a possible institutional-interest signal
`brs`	Breakout Readiness Score	A composite score assessing how "coiled" a stock is for a potential breakout, before it actually breaks out
`vcp`	Volatility Contraction Pattern	Mark Minervini-style VCP — a tightening series of pullbacks with shrinking volume, a classic pre-breakout base pattern

Requesting an invalid scan_type returns a clean 400, checked locally before any query runs. The 7 valid values are enforced against a whitelist first — the same defensive pattern used for Research Preset ids and Investment Committee lenses elsewhere in this API.

Where the data actually comes from

Results are precomputed by a dedicated cron (not calculated live per request) into the us_trader_scan_results table, running 30 22 * * 1-5 UTC — 10:30 PM UTC, weekdays only. Every response echoes source_table and cron_schedule directly, so you always know exactly where the numbers came from and how often they refresh.

The Effective Score's VCP Bump

Stocks in us_market_trader_scan results are ranked by an "effective score" — not simply the raw per-scan-type score, but one adjusted with a small, deliberate bump when a stock also independently qualifies for the VCP scan:

// Conceptually, from the actual query logic:
$effectiveScore = $rawScore + ($hasVcpPattern ? 1 : 0);

A stock that's both, say, Stage 2 AND showing a VCP pattern ranks slightly higher than an otherwise-identical Stage 2 stock without one. The VCP flag is a genuine additional piece of technical evidence (a tightening, lower-volatility base), so it nudges the ranking rather than requiring you to separately cross-reference the VCP scan's results yourself.

The response's stocks array is sorted by this effective score descending, with rs_rating descending as the tiebreaker.

Freshness: is_stale and the Weekend-Aware Heuristic

Every trader-scan response includes is_stale and stale_after_hours — a way to tell current data from stale data without you having to independently know the cron's schedule.

{
  "last_updated": "2026-07-25T22:30:00Z",
  "is_stale": false,
  "stale_after_hours": 72
}

is_stale value	Meaning
`null`	No data has been computed yet for this scan type
`false`	Data age is within the stale threshold (72 hours by default)
`true`	Data is older than the threshold — something may be wrong with the cron

72 hours is deliberately generous, and the reason is specific: the cron only runs on weekdays. A run that completes Friday evening can legitimately be roughly 65 hours old by Monday morning without anything actually being broken — a naive 24-hour staleness check would incorrectly flag perfectly normal Monday-morning data as stale every single week. The 72-hour default absorbs a normal weekend gap without false-flagging, while still catching a genuinely broken cron within a few days.

This is explicitly documented as a heuristic, not a precise "next scheduled run" calculation — it's a reasonable buffer, not an exact prediction of when fresh data will next arrive.

What's Next

With the raw endpoints covered, the final 2 guides in this series show how they compose into named, purpose-built workflows:

The Momentum Setup Workflow — Breadth → RS Before Price → RS Momentum → Conviction, chaining us_market_momentum with other market-context endpoints
The Trader Workflow — Stage 2 → Near High → BRS combined, chaining specific us_market_trader_scan scan types together for a tighter, higher-conviction shortlist

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