{"recommended_starting_workflow":{"workflow_id":"portfolio_build","reason":"Recommended first workflow for autonomous portfolio agents because it starts with symbol discovery, constructs a bounded portfolio, and produces reusable symbol_exchange values for downstream evaluation and comparison."},"agent_guidance":{"ordered_planning_steps":["Fetch /v1/ai/tools for tool metadata and parameter locations.","Fetch /v1/pricing/catalog to resolve current STC costs by pricing_rule_id.","Choose a workflow here, then execute steps in order.","Reuse symbol_exchange values from screeners, selections, or portfolio_construct outputs.","Skip duplicate paid symbol calls when a symbol_exchange was already resolved in the workflow."],"payment_rails":["subscription","x402","mpp"],"pricing_note":"STC is the pricing source of truth across all rails."},"data_provenance":{"historical_coverage_start_year":1980,"approximate_observation_count":"16M+","update_frequency":"weekly","classification_framework":"Stock Trends trend classification methodology","semantic_continuity":"Stock Trends indicators use a consistent classification doctrine across decades of observations.","native_signal_domains":["trend classification","relative performance","relative performance direction","volume activity","market breadth","sector leadership","regime structure"],"research_value":["long-horizon signal validation","regime analysis","sector rotation research","portfolio construction research","causal and probabilistic market analysis","agentic market-intelligence workflows"],"important_limits":["Historical depth supports research and probabilistic interpretation but does not guarantee future performance.","Stock Trends outputs are not investment advice, price targets, or direct buy/sell commands.","Externally named market events are not native Stock Trends labels unless separately curated."]},"workflows":[{"workflow_id":"regime_analysis","name":"Market Regime Analysis","description":"Full market regime intelligence pipeline: current regime classification, historical regime sequence for context, and probabilistic forward forecast.","tags":["agent","research","regime"],"supported_rails":["subscription","x402","mpp"],"total_stc_cost":0.75,"total_estimated_usd_cost":0.75,"pricing_note":"STC is the pricing source of truth. The estimated USD value uses the current operational policy of 1 STC approximately 1 USD and is for planning only.","decision_guidance":"Use when the agent needs market-level context before selecting bullish, bearish, or mixed symbol and portfolio workflows.","best_for":"Market context before symbol selection, screening, or portfolio construction.","agent_goal_examples":["Decide whether a portfolio agent should use bullish, bearish, or mixed candidate filters.","Summarize current regime and recent regime direction before selecting symbols."],"symbol_selection_guidance":"This workflow does not select symbols directly; use its regime result to choose bias filters for /v1/agent/screener/top or /v1/portfolio/construct.","interpretation_guidance":null,"required_interpretation_steps":[],"stock_trends_supplies":[],"researcher_supplied_steps":[],"not_provided_by_this_api":[],"success_condition":null,"next_step_guidance":["Use /v1/agent/screener/top to discover candidates.","Use /v1/decision/evaluate-symbol for a known symbol.","Use /v1/portfolio/construct when the goal is an allocation proposal."],"steps":[{"step_id":"regime_latest","endpoint":"GET /v1/market/regime/latest","method":"GET","path":"/v1/market/regime/latest","pricing_rule_id":"market_regime_latest","stc_cost":0.15,"estimated_usd_cost":0.15,"supported_rails":["subscription","x402","mpp"],"pricing_note":"STC is the source of truth; payment rails translate this STC cost.","description":"Retrieve the current market regime classification.","purpose":"Classify current market regime.","workflow_role":"Market context.","required_inputs":{},"optional_inputs":{},"safe_example_request":{"method":"GET","path":"/v1/market/regime/latest","query":{}},"output_summary":"Current regime classification and aggregate signal distribution.","related_endpoints":["/v1/market/regime/history","/v1/market/regime/forecast"],"optional":false},{"step_id":"regime_history","endpoint":"GET /v1/market/regime/history","method":"GET","path":"/v1/market/regime/history","pricing_rule_id":"market_regime_history","stc_cost":0.25,"estimated_usd_cost":0.25,"supported_rails":["subscription","x402","mpp"],"pricing_note":"STC is the source of truth; payment rails translate this STC cost.","description":"Retrieve historical regime sequence for context.","purpose":"Review recent market regime transitions.","workflow_role":"Historical market context.","required_inputs":{},"optional_inputs":{"limit":{"type":"integer","required":false,"safe_default":12,"minimum":1,"maximum":52,"example":12,"description":"Maximum number of rows returned. This endpoint applies no default date window. The applied_bounds block on the response reports the limit that was actually used."},"start_date":{"type":"string","required":false,"format":"date","example":"2025-01-03","description":"Optional earliest weekdate to include, in YYYY-MM-DD format. This filters which weeks are eligible; the endpoint still returns at most `limit` weeks and returns the most recent eligible weeks, so it does not select an arbitrary historical window."}},"safe_example_request":{"method":"GET","path":"/v1/market/regime/history","query":{"limit":12}},"output_summary":"Recent weekly market regime sequence.","related_endpoints":["/v1/market/regime/latest","/v1/market/regime/forecast"],"optional":true},{"step_id":"regime_forecast","endpoint":"GET /v1/market/regime/forecast","method":"GET","path":"/v1/market/regime/forecast","pricing_rule_id":"market_regime_forecast","stc_cost":0.35,"estimated_usd_cost":0.35,"supported_rails":["subscription","x402","mpp"],"pricing_note":"STC is the source of truth; payment rails translate this STC cost.","description":"Retrieve probabilistic forward regime forecast.","purpose":"Estimate near-term regime direction using deterministic recent-score logic.","workflow_role":"Regime decision guidance.","required_inputs":{},"optional_inputs":{"lookback":{"type":"integer","required":false,"safe_default":5,"minimum":2,"maximum":13}},"safe_example_request":{"method":"GET","path":"/v1/market/regime/forecast","query":{"lookback":5}},"output_summary":"Deterministic regime outlook and confidence fields.","related_endpoints":["/v1/market/regime/latest","/v1/market/regime/history"],"optional":false}]},{"workflow_id":"symbol_decision","name":"Regime-Aware Symbol Decision","description":"Classify the current market regime then evaluate a single symbol for a directional research bias in that regime context.","tags":["agent","research","decision"],"supported_rails":["subscription","x402","mpp"],"total_stc_cost":0.65,"total_estimated_usd_cost":0.65,"pricing_note":"STC is the pricing source of truth. The estimated USD value uses the current operational policy of 1 STC approximately 1 USD and is for planning only.","decision_guidance":"Use when the agent has a target symbol and needs deterministic Stock Trends signal and regime context before deeper history or portfolio calls.","best_for":"Evaluating a known symbol in current market-regime context.","agent_goal_examples":["Evaluate IBM-N after resolving it from /v1/instruments/resolve.","Score a symbol carried forward from a screener, STWR report, or portfolio position."],"symbol_selection_guidance":"Provide symbol_exchange directly when available. If only a ticker is known, first call /v1/instruments/lookup or /v1/instruments/resolve and reuse the returned symbol_exchange.","interpretation_guidance":null,"required_interpretation_steps":[],"stock_trends_supplies":[],"researcher_supplied_steps":[],"not_provided_by_this_api":[],"success_condition":null,"next_step_guidance":["Use /v1/indicators/latest or /v1/stim/latest for deeper single-symbol context.","Use /v1/portfolio/evaluate when comparing the symbol inside an allocation."],"steps":[{"step_id":"regime_latest","endpoint":"GET /v1/market/regime/latest","method":"GET","path":"/v1/market/regime/latest","pricing_rule_id":"market_regime_latest","stc_cost":0.15,"estimated_usd_cost":0.15,"supported_rails":["subscription","x402","mpp"],"pricing_note":"STC is the source of truth; payment rails translate this STC cost.","description":"Retrieve the current market regime classification.","purpose":"Classify current market regime.","workflow_role":"Market context.","required_inputs":{},"optional_inputs":{},"safe_example_request":{"method":"GET","path":"/v1/market/regime/latest","query":{}},"output_summary":"Current regime classification and aggregate signal distribution.","related_endpoints":["/v1/market/regime/history","/v1/market/regime/forecast"],"optional":false},{"step_id":"evaluate_symbol","endpoint":"POST /v1/decision/evaluate-symbol","method":"POST","path":"/v1/decision/evaluate-symbol","pricing_rule_id":"evaluate_symbol","stc_cost":0.5,"estimated_usd_cost":0.5,"supported_rails":["subscription","x402","mpp"],"pricing_note":"STC is the source of truth; payment rails translate this STC cost.","description":"Evaluate a symbol directional research bias given the current regime.","purpose":"Evaluate one symbol for directional decision-support bias in regime context.","workflow_role":"Symbol-level decision step.","required_inputs":{"symbol_exchange":{"type":"string","required":true,"example":"IBM-N","safe_default_for_demo":"IBM-N","pattern":"^[A-Z0-9.]+-[A-Z]$","description":"Stock Trends symbol plus exchange suffix."}},"optional_inputs":{"symbol":{"type":"string","required":false,"example":"IBM","description":"Ticker symbol. Use with exchange when symbol_exchange is not supplied."},"exchange":{"type":"string","required":false,"enum":["N","Q","A","B","T","I"],"example":"N","description":"Stock Trends exchange suffix. Common examples: N=NYSE, Q=NASDAQ, A=AMEX, T=TSX."}},"safe_example_request":{"method":"POST","path":"/v1/decision/evaluate-symbol","json":{"symbol_exchange":"IBM-N"}},"output_summary":"Deterministic symbol decision with Stock Trends signal and regime context.","related_endpoints":["/v1/market/regime/latest","/v1/indicators/latest","/v1/stim/latest"],"optional":false}]},{"workflow_id":"stim_forecast_review","name":"ST-IM Forecast Review","description":"Review ST-IM forward-return expectations for one symbol across the 4, 13, and 40 week horizons, with indicator and price context.","tags":["agent","research","stim","forecast"],"supported_rails":["subscription","x402","mpp"],"total_stc_cost":0.0335,"total_estimated_usd_cost":0.0335,"pricing_note":"STC is the pricing source of truth. The estimated USD value uses the current operational policy of 1 STC approximately 1 USD and is for planning only.","decision_guidance":"Use when an agent needs to interpret ST-IM expected return distributions for one resolved symbol before making a ranking, review, or portfolio decision.","best_for":"Single-symbol probabilistic forward-return review.","agent_goal_examples":["Review IBM-N ST-IM expectations across 4, 13, and 40 week horizons.","Estimate whether a symbol's ST-IM mean returns exceed base-period means with adequate probability."],"symbol_selection_guidance":"Use symbol_exchange directly when known. If only a ticker is known, first call /v1/instruments/lookup or /v1/instruments/resolve and reuse the returned symbol_exchange.","interpretation_guidance":"/v1/meta/inference and /v1/meta/stim must be consulted before interpreting ST-IM results. Raw x4wk/x13wk/x40wk means are not sufficient alone; compare them to base_period_mean_returns_pct and use x4wksd/x13wksd/x40wksd to estimate the probability of exceeding base means. Preserve provider identity, forecast horizon, distribution, confidence, evidence, uncertainty, explanation, signal source, and auditability. STIM Select-style logic should emphasize 13-week probability of exceeding the base mean >= 55% and lower confidence bounds relative to base-period means where applicable.","required_interpretation_steps":["Call GET /v1/meta/inference before interpreting provider-specific inference outputs.","Call GET /v1/meta/stim before interpreting ST-IM results.","Compare x4wk, x13wk, and x40wk to base_period_mean_returns_pct.","Use x4wksd, x13wksd, and x40wksd to estimate probability of exceeding base means.","Interpret ST-IM probabilities as conditional historical tendencies, not guarantees or buy/sell commands.","Disclose stale or fallback data when is_stale=true or missing_reason is present."],"stock_trends_supplies":[],"researcher_supplied_steps":[],"not_provided_by_this_api":[],"success_condition":null,"next_step_guidance":["Use /v1/decision/evaluate-symbol after interpreting ST-IM probability context.","Use /v1/portfolio/evaluate when reviewing the symbol inside an existing allocation."],"steps":[{"step_id":"meta_inference","endpoint":"GET /v1/meta/inference","method":"GET","path":"/v1/meta/inference","pricing_rule_id":null,"stc_cost":0.0,"estimated_usd_cost":0.0,"supported_rails":[],"pricing_note":"Public non-metered planning helper; no STC charge applies.","description":"Retrieve provider-agnostic inference and cognition contract before provider-specific interpretation.","purpose":"Retrieve provider-agnostic inference and cognition contract before provider-specific interpretation.","workflow_role":null,"required_inputs":{},"optional_inputs":{},"safe_example_request":{"method":"GET","path":"/v1/meta/inference","query":{}},"output_summary":null,"related_endpoints":[],"optional":false},{"step_id":"meta_stim","endpoint":"GET /v1/meta/stim","method":"GET","path":"/v1/meta/stim","pricing_rule_id":null,"stc_cost":0.0,"estimated_usd_cost":0.0,"supported_rails":[],"pricing_note":"Public non-metered planning helper; no STC charge applies.","description":"Retrieve ST-IM field definitions and base-period mean returns before interpretation.","purpose":"Retrieve ST-IM field definitions and base-period mean returns before interpretation.","workflow_role":null,"required_inputs":{},"optional_inputs":{},"safe_example_request":{"method":"GET","path":"/v1/meta/stim","query":{}},"output_summary":null,"related_endpoints":[],"optional":false},{"step_id":"stim_latest","endpoint":"GET /v1/stim/latest","method":"GET","path":"/v1/stim/latest","pricing_rule_id":"stim_latest_paid","stc_cost":0.0025,"estimated_usd_cost":0.0025,"supported_rails":["subscription","x402","mpp"],"pricing_note":"STC is the source of truth; payment rails translate this STC cost.","description":"Retrieve latest ST-IM forward return distributions for IBM-N or another resolved symbol.","purpose":"Retrieve latest ST-IM forward return distribution outputs for one instrument.","workflow_role":"Forward distribution enrichment.","required_inputs":{"symbol_exchange":{"type":"string","required":true,"example":"IBM-N","safe_default_for_demo":"IBM-N","pattern":"^[A-Z0-9.]+-[A-Z]$","description":"Stock Trends symbol plus exchange suffix."}},"optional_inputs":{"symbol":{"type":"string","required":false,"example":"IBM","description":"Ticker symbol. Use with exchange when symbol_exchange is not supplied."},"exchange":{"type":"string","required":false,"enum":["N","Q","A","B","T","I"],"example":"N","description":"Stock Trends exchange suffix. Common examples: N=NYSE, Q=NASDAQ, A=AMEX, T=TSX."}},"safe_example_request":{"method":"GET","path":"/v1/stim/latest","query":{"symbol_exchange":"IBM-N"}},"output_summary":"ST-IM forward return expectations and statistical distributions across 4, 13, and 40 weeks.","related_endpoints":["/v1/meta/inference","/v1/meta/stim","/v1/indicators/latest","/v1/stim/history","/v1/selections/published/latest"],"optional":false},{"step_id":"indicators_latest","endpoint":"GET /v1/indicators/latest","method":"GET","path":"/v1/indicators/latest","pricing_rule_id":"indicators_latest_paid","stc_cost":0.0035,"estimated_usd_cost":0.0035,"supported_rails":["subscription","x402","mpp"],"pricing_note":"STC is the source of truth; payment rails translate this STC cost.","description":"Retrieve latest Stock Trends indicator context for the same symbol.","purpose":"Retrieve the latest weekly Stock Trends indicator row for one instrument.","workflow_role":"Single-symbol signal confirmation.","required_inputs":{"symbol_exchange":{"type":"string","required":true,"example":"IBM-N","safe_default_for_demo":"IBM-N","pattern":"^[A-Z0-9.]+-[A-Z]$","description":"Stock Trends symbol plus exchange suffix."}},"optional_inputs":{"symbol":{"type":"string","required":false,"example":"IBM","description":"Ticker symbol. Use with exchange when symbol_exchange is not supplied."},"exchange":{"type":"string","required":false,"enum":["N","Q","A","B","T","I"],"example":"N","description":"Stock Trends exchange suffix. Common examples: N=NYSE, Q=NASDAQ, A=AMEX, T=TSX."},"cs_only":{"type":"boolean","required":false,"safe_default":true,"example":true,"description":"Filter to Common Stocks only where the endpoint supports instrument type filtering."}},"safe_example_request":{"method":"GET","path":"/v1/indicators/latest","query":{"symbol_exchange":"IBM-N","cs_only":true}},"output_summary":"Latest indicator snapshot with trend classification, trend_cnt, mt_cnt, rsi, rsi_updn, vol_tag, price-change fields, moving averages, and weekly high/low context.","related_endpoints":["/v1/indicators/history","/v1/stim/latest","/v1/selections/history"],"optional":false},{"step_id":"prices_latest","endpoint":"GET /v1/prices/latest","method":"GET","path":"/v1/prices/latest","pricing_rule_id":"prices_latest_paid","stc_cost":0.0025,"estimated_usd_cost":0.0025,"supported_rails":["subscription","x402","mpp"],"pricing_note":"STC is the source of truth; payment rails translate this STC cost.","description":"Retrieve latest weekly price context for the same symbol.","purpose":"Retrieve latest weekly price context for one instrument.","workflow_role":"Price context enrichment.","required_inputs":{"symbol_exchange":{"type":"string","required":true,"example":"IBM-N","safe_default_for_demo":"IBM-N","pattern":"^[A-Z0-9.]+-[A-Z]$","description":"Stock Trends symbol plus exchange suffix."}},"optional_inputs":{"symbol":{"type":"string","required":false,"example":"IBM","description":"Ticker symbol. Use with exchange when symbol_exchange is not supplied."},"exchange":{"type":"string","required":false,"enum":["N","Q","A","B","T","I"],"example":"N","description":"Stock Trends exchange suffix. Common examples: N=NYSE, Q=NASDAQ, A=AMEX, T=TSX."},"cs_only":{"type":"boolean","required":false,"safe_default":true,"example":true,"description":"Filter to Common Stocks only where the endpoint supports instrument type filtering."}},"safe_example_request":{"method":"GET","path":"/v1/prices/latest","query":{"symbol_exchange":"IBM-N","cs_only":true}},"output_summary":"Latest weekly price, adjusted close, high/low, volume (actual shares traded), trades, split factor, and price change.","related_endpoints":["/v1/indicators/latest","/v1/prices/history"],"optional":false},{"step_id":"stim_history","endpoint":"GET /v1/stim/history","method":"GET","path":"/v1/stim/history","pricing_rule_id":"stim_history_paid","stc_cost":0.0075,"estimated_usd_cost":0.0075,"supported_rails":["subscription","x402","mpp"],"pricing_note":"STC is the source of truth; payment rails translate this STC cost.","description":"Optionally retrieve bounded historical ST-IM distributions using query metadata.","purpose":"Retrieve a symbol-level history of ST-IM distribution records.","workflow_role":"Historical forward-distribution context.","required_inputs":{"symbol_exchange":{"type":"string","required":true,"example":"IBM-N","safe_default_for_demo":"IBM-N","pattern":"^[A-Z0-9.]+-[A-Z]$","description":"Stock Trends symbol plus exchange suffix."}},"optional_inputs":{"symbol":{"type":"string","required":false,"example":"IBM","description":"Ticker symbol. Use with exchange when symbol_exchange is not supplied."},"exchange":{"type":"string","required":false,"enum":["N","Q","A","B","T","I"],"example":"N","description":"Stock Trends exchange suffix. Common examples: N=NYSE, Q=NASDAQ, A=AMEX, T=TSX."},"start":{"type":"string","required":false,"format":"date","example":"2025-01-03","description":"Inclusive start weekdate in YYYY-MM-DD format."},"end":{"type":"string","required":false,"format":"date","example":"2025-12-26","description":"Inclusive end weekdate in YYYY-MM-DD format."},"limit":{"type":"integer","required":false,"safe_default":260,"minimum":1,"maximum":2600,"example":260,"description":"Maximum number of rows returned. This endpoint applies no default date window. The applied_bounds block on the response reports the limit that was actually used."},"include_gaps":{"type":"boolean","required":false,"safe_default":false}},"safe_example_request":{"method":"GET","path":"/v1/stim/history","query":{"symbol_exchange":"IBM-N","limit":52}},"output_summary":"Historical ST-IM distributions across 4, 13, and 40 week horizons.","related_endpoints":["/v1/meta/inference","/v1/meta/stim","/v1/stim/latest","/v1/indicators/history"],"optional":true},{"step_id":"indicators_history","endpoint":"GET /v1/indicators/history","method":"GET","path":"/v1/indicators/history","pricing_rule_id":"indicators_history_paid","stc_cost":0.01,"estimated_usd_cost":0.01,"supported_rails":["subscription","x402","mpp"],"pricing_note":"STC is the source of truth; payment rails translate this STC cost.","description":"Optionally retrieve bounded historical indicator context using query metadata.","purpose":"Retrieve a bounded weekly history of Stock Trends indicator rows for one instrument.","workflow_role":"Historical signal context and trend persistence review.","required_inputs":{"symbol_exchange":{"type":"string","required":true,"example":"IBM-N","safe_default_for_demo":"IBM-N","pattern":"^[A-Z0-9.]+-[A-Z]$","description":"Stock Trends symbol plus exchange suffix."}},"optional_inputs":{"symbol":{"type":"string","required":false,"example":"IBM","description":"Ticker symbol. Use with exchange when symbol_exchange is not supplied."},"exchange":{"type":"string","required":false,"enum":["N","Q","A","B","T","I"],"example":"N","description":"Stock Trends exchange suffix. Common examples: N=NYSE, Q=NASDAQ, A=AMEX, T=TSX."},"cs_only":{"type":"boolean","required":false,"safe_default":true,"example":true,"description":"Filter to Common Stocks only where the endpoint supports instrument type filtering."},"start":{"type":"string","required":false,"format":"date","example":"2025-01-03","description":"Inclusive start weekdate in YYYY-MM-DD format."},"end":{"type":"string","required":false,"format":"date","example":"2025-12-26","description":"Inclusive end weekdate in YYYY-MM-DD format."},"limit":{"type":"integer","required":false,"safe_default":260,"minimum":1,"maximum":2600,"example":260,"description":"Maximum number of rows returned. This endpoint applies no default date window. The applied_bounds block on the response reports the limit that was actually used."}},"safe_example_request":{"method":"GET","path":"/v1/indicators/history","query":{"symbol_exchange":"IBM-N","limit":52,"cs_only":true}},"output_summary":"Weekly indicator history with trend classification, trend_cnt, mt_cnt, rsi, rsi_updn, vol_tag, price-change fields, moving averages, and high/low context.","related_endpoints":["/v1/indicators/latest","/v1/stim/history","/v1/prices/history"],"optional":true},{"step_id":"prices_history","endpoint":"GET /v1/prices/history","method":"GET","path":"/v1/prices/history","pricing_rule_id":"prices_history_paid","stc_cost":0.0075,"estimated_usd_cost":0.0075,"supported_rails":["subscription","x402","mpp"],"pricing_note":"STC is the source of truth; payment rails translate this STC cost.","description":"Optionally retrieve bounded historical price context using query metadata.","purpose":"Retrieve weekly price history for one instrument.","workflow_role":"Historical price context.","required_inputs":{"symbol_exchange":{"type":"string","required":true,"example":"IBM-N","safe_default_for_demo":"IBM-N","pattern":"^[A-Z0-9.]+-[A-Z]$","description":"Stock Trends symbol plus exchange suffix."}},"optional_inputs":{"symbol":{"type":"string","required":false,"example":"IBM","description":"Ticker symbol. Use with exchange when symbol_exchange is not supplied."},"exchange":{"type":"string","required":false,"enum":["N","Q","A","B","T","I"],"example":"N","description":"Stock Trends exchange suffix. Common examples: N=NYSE, Q=NASDAQ, A=AMEX, T=TSX."},"cs_only":{"type":"boolean","required":false,"safe_default":true,"example":true,"description":"Filter to Common Stocks only where the endpoint supports instrument type filtering."},"start":{"type":"string","required":false,"format":"date","example":"2025-01-03","description":"Inclusive start weekdate in YYYY-MM-DD format."},"end":{"type":"string","required":false,"format":"date","example":"2025-12-26","description":"Inclusive end weekdate in YYYY-MM-DD format."},"limit":{"type":"integer","required":false,"safe_default":260,"minimum":1,"maximum":2600,"example":260,"description":"Maximum number of rows returned. This endpoint applies no default date window. The applied_bounds block on the response reports the limit that was actually used."}},"safe_example_request":{"method":"GET","path":"/v1/prices/history","query":{"symbol_exchange":"IBM-N","limit":52,"cs_only":true}},"output_summary":"Weekly price history for one symbol.","related_endpoints":["/v1/prices/latest","/v1/indicators/history"],"optional":true}]},{"workflow_id":"portfolio_build","name":"Screener → Portfolio Build","description":"Screen for qualifying tickers, construct a portfolio from candidates, then evaluate the constructed portfolio's risk and return profile.","tags":["agent","portfolio","research"],"supported_rails":["subscription","x402","mpp"],"total_stc_cost":2.25,"total_estimated_usd_cost":2.25,"pricing_note":"STC is the pricing source of truth. The estimated USD value uses the current operational policy of 1 STC approximately 1 USD and is for planning only.","decision_guidance":"Use when the agent wants a fresh candidate list and a bounded equal-weight portfolio proposal.","best_for":"First portfolio workflow for agents that need to discover symbols and build an allocation.","agent_goal_examples":["Build a 5-stock equal-weight candidate portfolio from fresh Stock Trends signals.","Use screener output symbols as the candidate context for a portfolio construction run."],"symbol_selection_guidance":"Start with /v1/agent/screener/top. Reuse results[].symbol_exchange from the screener when calling /v1/decision/evaluate-symbol, /v1/stim/latest, /v1/portfolio/evaluate, or /v1/portfolio/compare. Skip duplicate paid symbol calls for repeated symbol_exchange values.","interpretation_guidance":null,"required_interpretation_steps":[],"stock_trends_supplies":[],"researcher_supplied_steps":[],"not_provided_by_this_api":[],"success_condition":null,"next_step_guidance":["Use /v1/portfolio/compare to compare the constructed portfolio against an existing allocation.","Use /v1/stim/latest for selected symbols when forward-return distributions are needed."],"steps":[{"step_id":"screener_top","endpoint":"GET /v1/agent/screener/top","method":"GET","path":"/v1/agent/screener/top","pricing_rule_id":"agent_screener_top","stc_cost":0.5,"estimated_usd_cost":0.5,"supported_rails":["subscription","x402","mpp"],"pricing_note":"STC is the source of truth; payment rails translate this STC cost.","description":"Screen for top qualifying tickers.","purpose":"Find a ranked candidate set from the latest Stock Trends signal data.","workflow_role":"Candidate discovery and ranking.","required_inputs":{},"optional_inputs":{"limit":{"type":"integer","required":false,"safe_default":25,"minimum":1,"maximum":100},"min_rsi":{"type":"integer","required":false,"safe_default":40,"example":40,"description":"Minimum Stock Trends RSI threshold. RSI baseline is 100."},"exchange":{"type":"string","required":false,"enum":["N","Q","A","B","T","I"]}},"safe_example_request":{"method":"GET","path":"/v1/agent/screener/top","query":{"limit":10,"min_rsi":40}},"output_summary":"Ranked instruments with Stock Trends signal fields and filter summary.","related_endpoints":["/v1/decision/evaluate-symbol","/v1/portfolio/construct","/v1/stim/latest"],"optional":false},{"step_id":"portfolio_construct","endpoint":"POST /v1/portfolio/construct","method":"POST","path":"/v1/portfolio/construct","pricing_rule_id":"portfolio_construct","stc_cost":1.0,"estimated_usd_cost":1.0,"supported_rails":["subscription","x402","mpp"],"pricing_note":"STC is the source of truth; payment rails translate this STC cost.","description":"Construct a portfolio from screened candidates.","purpose":"Build an equal-weight candidate portfolio from Stock Trends signals.","workflow_role":"Portfolio construction.","required_inputs":{},"optional_inputs":{"universe":{"type":"string","required":false,"enum":["top"],"safe_default":"top","example":"top","description":"Candidate universe selector. Currently supports top-ranked signal candidates."},"count":{"type":"integer","required":false,"minimum":1,"maximum":10,"safe_default":5,"example":5,"description":"Number of equal-weight positions to construct."},"bias":{"type":"string","required":false,"enum":["auto","bullish","bearish"],"safe_default":"auto","example":"auto","description":"Portfolio orientation selector. auto derives context from market regime signals."},"exchange":{"type":"string","required":false,"enum":["N","Q","A","T"],"example":"N","description":"Optional exchange filter for candidate selection."}},"safe_example_request":{"method":"POST","path":"/v1/portfolio/construct","json":{"universe":"top","count":5,"bias":"auto"}},"output_summary":"Constructed equal-weight portfolio with signal, decision, ST-IM tiebreaker, and regime fields.","related_endpoints":["/v1/agent/screener/top","/v1/portfolio/evaluate","/v1/portfolio/compare"],"optional":false},{"step_id":"portfolio_evaluate","endpoint":"POST /v1/portfolio/evaluate","method":"POST","path":"/v1/portfolio/evaluate","pricing_rule_id":"portfolio_evaluate","stc_cost":0.75,"estimated_usd_cost":0.75,"supported_rails":["subscription","x402","mpp"],"pricing_note":"STC is the source of truth; payment rails translate this STC cost.","description":"Evaluate risk and return profile of the constructed portfolio.","purpose":"Evaluate an existing or proposed portfolio.","workflow_role":"Portfolio review.","required_inputs":{"positions":{"type":"array","required":true,"description":"List of symbol/weight positions.","example":[{"symbol_exchange":"IBM-N","weight":1.0}],"items":{"type":"object","properties":{"symbol_exchange":{"type":"string","example":"IBM-N","pattern":"^[A-Z0-9.]+-[A-Z]$","description":"Stock Trends symbol plus exchange suffix."},"weight":{"type":"number","minimum":0,"maximum":1,"example":1.0,"description":"Portfolio weight for this position."}},"required":["symbol_exchange","weight"],"additionalProperties":false}}},"optional_inputs":{},"safe_example_request":{"method":"POST","path":"/v1/portfolio/evaluate","json":{"positions":[{"symbol_exchange":"IBM-N","weight":1.0}]}},"output_summary":"Portfolio-level and position-level Stock Trends evaluation.","related_endpoints":["/v1/portfolio/construct","/v1/portfolio/compare"],"optional":false}]},{"workflow_id":"portfolio_compare_review","name":"Portfolio Compare Review","description":"Evaluate an existing portfolio, construct a proposed alternative, then compare the two portfolios to quantify the difference.","tags":["agent","portfolio"],"supported_rails":["subscription","x402","mpp"],"total_stc_cost":3.0,"total_estimated_usd_cost":3.0,"pricing_note":"STC is the pricing source of truth. The estimated USD value uses the current operational policy of 1 STC approximately 1 USD and is for planning only.","decision_guidance":"Use when the agent needs to evaluate an existing allocation, construct an alternative, and compare both under the same Stock Trends decision framework.","best_for":"Comparing a current allocation against a proposed Stock Trends-informed alternative.","agent_goal_examples":["Evaluate a user portfolio, construct a proposed alternative, then compare score and alignment.","Review whether a newly constructed portfolio improves regime alignment versus a baseline."],"symbol_selection_guidance":"The compare endpoint expects left and right as direct arrays of positions, not wrapper objects. Reuse portfolio arrays returned by /v1/portfolio/construct or positions supplied to /v1/portfolio/evaluate.","interpretation_guidance":null,"required_interpretation_steps":[],"stock_trends_supplies":[],"researcher_supplied_steps":[],"not_provided_by_this_api":[],"success_condition":null,"next_step_guidance":["Use comparison.winner, score_delta, and alignment_advantage to summarize differences.","Reuse any symbol_exchange values in losing positions for deeper /v1/decision/evaluate-symbol review."],"steps":[{"step_id":"evaluate_current","endpoint":"POST /v1/portfolio/evaluate","method":"POST","path":"/v1/portfolio/evaluate","pricing_rule_id":"portfolio_evaluate","stc_cost":0.75,"estimated_usd_cost":0.75,"supported_rails":["subscription","x402","mpp"],"pricing_note":"STC is the source of truth; payment rails translate this STC cost.","description":"Evaluate current portfolio risk and return profile.","purpose":"Evaluate an existing or proposed portfolio.","workflow_role":"Portfolio review.","required_inputs":{"positions":{"type":"array","required":true,"description":"List of symbol/weight positions.","example":[{"symbol_exchange":"IBM-N","weight":1.0}],"items":{"type":"object","properties":{"symbol_exchange":{"type":"string","example":"IBM-N","pattern":"^[A-Z0-9.]+-[A-Z]$","description":"Stock Trends symbol plus exchange suffix."},"weight":{"type":"number","minimum":0,"maximum":1,"example":1.0,"description":"Portfolio weight for this position."}},"required":["symbol_exchange","weight"],"additionalProperties":false}}},"optional_inputs":{},"safe_example_request":{"method":"POST","path":"/v1/portfolio/evaluate","json":{"positions":[{"symbol_exchange":"IBM-N","weight":1.0}]}},"output_summary":"Portfolio-level and position-level Stock Trends evaluation.","related_endpoints":["/v1/portfolio/construct","/v1/portfolio/compare"],"optional":false},{"step_id":"construct_proposed","endpoint":"POST /v1/portfolio/construct","method":"POST","path":"/v1/portfolio/construct","pricing_rule_id":"portfolio_construct","stc_cost":1.0,"estimated_usd_cost":1.0,"supported_rails":["subscription","x402","mpp"],"pricing_note":"STC is the source of truth; payment rails translate this STC cost.","description":"Construct the proposed alternative portfolio.","purpose":"Build an equal-weight candidate portfolio from Stock Trends signals.","workflow_role":"Portfolio construction.","required_inputs":{},"optional_inputs":{"universe":{"type":"string","required":false,"enum":["top"],"safe_default":"top","example":"top","description":"Candidate universe selector. Currently supports top-ranked signal candidates."},"count":{"type":"integer","required":false,"minimum":1,"maximum":10,"safe_default":5,"example":5,"description":"Number of equal-weight positions to construct."},"bias":{"type":"string","required":false,"enum":["auto","bullish","bearish"],"safe_default":"auto","example":"auto","description":"Portfolio orientation selector. auto derives context from market regime signals."},"exchange":{"type":"string","required":false,"enum":["N","Q","A","T"],"example":"N","description":"Optional exchange filter for candidate selection."}},"safe_example_request":{"method":"POST","path":"/v1/portfolio/construct","json":{"universe":"top","count":5,"bias":"auto"}},"output_summary":"Constructed equal-weight portfolio with signal, decision, ST-IM tiebreaker, and regime fields.","related_endpoints":["/v1/agent/screener/top","/v1/portfolio/evaluate","/v1/portfolio/compare"],"optional":false},{"step_id":"compare_portfolios","endpoint":"POST /v1/portfolio/compare","method":"POST","path":"/v1/portfolio/compare","pricing_rule_id":"portfolio_compare","stc_cost":1.25,"estimated_usd_cost":1.25,"supported_rails":["subscription","x402","mpp"],"pricing_note":"STC is the source of truth; payment rails translate this STC cost.","description":"Compare current and proposed portfolios to quantify the difference.","purpose":"Compare current and proposed portfolios.","workflow_role":"Portfolio comparison.","required_inputs":{"left":{"type":"array","required":true,"description":"Left portfolio as a direct array of symbol-weight positions.","example":[{"symbol_exchange":"IBM-N","weight":1.0}],"items":{"type":"object","properties":{"symbol_exchange":{"type":"string","example":"IBM-N","pattern":"^[A-Z0-9.]+-[A-Z]$","description":"Stock Trends symbol plus exchange suffix."},"weight":{"type":"number","minimum":0,"maximum":1,"example":1.0,"description":"Portfolio weight for this position."}},"required":["symbol_exchange","weight"],"additionalProperties":false}},"right":{"type":"array","required":true,"description":"Right portfolio as a direct array of symbol-weight positions.","example":[{"symbol_exchange":"MSFT-Q","weight":1.0}],"items":{"type":"object","properties":{"symbol_exchange":{"type":"string","example":"IBM-N","pattern":"^[A-Z0-9.]+-[A-Z]$","description":"Stock Trends symbol plus exchange suffix."},"weight":{"type":"number","minimum":0,"maximum":1,"example":1.0,"description":"Portfolio weight for this position."}},"required":["symbol_exchange","weight"],"additionalProperties":false}}},"optional_inputs":{},"safe_example_request":{"method":"POST","path":"/v1/portfolio/compare","json":{"left":[{"symbol_exchange":"IBM-N","weight":1.0}],"right":[{"symbol_exchange":"MSFT-Q","weight":1.0}]}},"output_summary":"Side-by-side portfolio evaluations and comparison metrics.","related_endpoints":["/v1/portfolio/evaluate","/v1/portfolio/construct"],"optional":false}]},{"workflow_id":"historical_signal_validation","name":"Historical Signal Validation and Model Integration Review","description":"Retrieve bounded historical Stock Trends observations across the instrument, cross-sectional, market-regime and inference layers so an external research system, forecasting model, portfolio system or agent can evaluate whether Stock Trends context adds information beyond its own existing baseline.","tags":["agent","research","historical","validation","integration"],"supported_rails":["subscription","x402","mpp"],"total_stc_cost":0.875,"total_estimated_usd_cost":0.875,"pricing_note":"STC is the pricing source of truth. The estimated USD value uses the current operational policy of 1 STC approximately 1 USD and is for planning only.","decision_guidance":"Use when the question is whether Stock Trends context is worth integrating into an existing research or forecasting process, rather than what the current market state is. The evaluation itself is performed by the caller.","best_for":"Evaluating Stock Trends as a candidate contextual feature or data layer for an external model or research process.","agent_goal_examples":["Assemble a historical Stock Trends feature set aligned on weekdate for a researcher-defined forward-return target.","Compare Stock Trends classification, breadth, leadership and regime context against an existing baseline feature set over a defined historical period.","Check whether a measured contribution holds across different market regimes before deciding on recurring integration."],"symbol_selection_guidance":"Instrument-level steps take symbol_exchange. Resolve tickers through /v1/instruments/lookup or /v1/instruments/resolve first and reuse the returned symbol_exchange. The cross-sectional, regime and evidence steps are market-level and take no symbol.","interpretation_guidance":"Stock Trends observations are weekly classification states keyed on weekdate; weekdate is the alignment key for any join the caller performs. Read /v1/meta/indicators for indicator semantics and /v1/meta/inference for the provider-agnostic inference contract before treating any field as a feature. ST-IM is one inference provider over the classification framework rather than the framework itself, so the instrument, breadth, leadership and regime layers are evaluated on their own terms and not only through ST-IM. Historical depth supports comparability across market environments; it does not establish that any measured relationship will persist.","required_interpretation_steps":["Call GET /v1/meta/indicators before treating trend, trend_cnt, mt_cnt, rsi, rsi_updn or vol_tag as features.","Call GET /v1/meta/inference before interpreting any provider-specific inference output.","Call GET /v1/meta/stim before interpreting ST-IM fields, if ST-IM history is used.","Treat weekdate as the point-in-time key; each row describes the week it is keyed on.","Read applied_bounds on every history response to confirm the date bounds and row limit that were actually applied, and whether the result was truncated.","GET /v1/market/regime/history returns at most 52 recent weekly observations and start_date only raises the earliest eligible week; it does not page backwards. Do not assume it covers the chosen research period.","If ST-IM Select outcome evidence is used, interpret it as an aggregate measurement of one stated signal rule over a stated population, not as a portfolio result, a forecast, or evidence about the broader classification layers."],"stock_trends_supplies":["Point-in-time weekly historical observations for the instrument, cross-sectional, market-regime and inference layers, each bounded and each reporting its applied_bounds.","Interpretation semantics and field definitions for those observations.","Published evidence families, each carrying its own methodology and limitations, mapped at /v1/ai/context.","weekdate as a consistent alignment key across all layers.","Explicit applied_bounds describing the window and row limit each response was produced under."],"researcher_supplied_steps":["Define the historical research period appropriate to the question.","Define the target, outcome definition and forecast horizon being predicted.","Perform the join between Stock Trends observations and that target.","Enforce point-in-time discipline and avoid look-ahead leakage in that join.","Define the existing baseline or feature set the comparison is against.","Measure any incremental contribution over that baseline.","Examine stability across market regimes or other relevant contexts, supplying the researcher's own regime segmentation for any period the 52-week regime endpoint does not cover.","Separate in-sample exploration from out-of-sample validation.","Decide whether the measured contribution justifies recurring integration."],"not_provided_by_this_api":["bulk dataset download","model training or fitting","automatic feature engineering","joins to external targets or datasets","backtesting or portfolio simulation","statistical significance testing","causal validation"],"success_condition":"The caller can state, from the material actually retrieved, whether a measured incremental contribution was stable enough to justify recurring use. A completed evaluation is the success condition; a positive result is not asserted, implied, or required.","next_step_guidance":["Use /v1/cost-estimate to bound the STC cost of the paid steps before executing them.","Use /v1/instruments/resolve to produce symbol_exchange values for the instrument-level steps.","Use the regime_analysis or portfolio_build workflows instead if the goal turns out to be current market context rather than historical evaluation."],"steps":[{"step_id":"meta_indicators","endpoint":"GET /v1/meta/indicators","method":"GET","path":"/v1/meta/indicators","pricing_rule_id":null,"stc_cost":0.0,"estimated_usd_cost":0.0,"supported_rails":[],"pricing_note":"Public non-metered planning helper; no STC charge applies.","description":"Retrieve Stock Trends indicator definitions before treating any field as a research feature.","purpose":"Retrieve Stock Trends indicator definitions before treating any field as a research feature.","workflow_role":null,"required_inputs":{},"optional_inputs":{},"safe_example_request":{"method":"GET","path":"/v1/meta/indicators","query":{}},"output_summary":null,"related_endpoints":[],"optional":false},{"step_id":"meta_inference","endpoint":"GET /v1/meta/inference","method":"GET","path":"/v1/meta/inference","pricing_rule_id":null,"stc_cost":0.0,"estimated_usd_cost":0.0,"supported_rails":[],"pricing_note":"Public non-metered planning helper; no STC charge applies.","description":"Retrieve the provider-agnostic inference contract governing any inference output used.","purpose":"Retrieve the provider-agnostic inference contract governing any inference output used.","workflow_role":null,"required_inputs":{},"optional_inputs":{},"safe_example_request":{"method":"GET","path":"/v1/meta/inference","query":{}},"output_summary":null,"related_endpoints":[],"optional":false},{"step_id":"stim_select_outcome_evidence","endpoint":"GET /v1/selections/stim-select/outcomes/summary","method":"GET","path":"/v1/selections/stim-select/outcomes/summary","pricing_rule_id":null,"stc_cost":0.0,"estimated_usd_cost":0.0,"supported_rails":[],"pricing_note":"Public non-metered planning helper; no STC charge applies.","description":"Optionally inspect published aggregate outcome evidence for the ST-IM Select filter. This is one evidence family, specific to one application of the framework; it is relevant when the evaluation concerns that filter, and not a precondition for evaluating the broader classification and context layers. See the evidence map at /v1/ai/context for the other families and their limitations.","purpose":"Summarize mature historical outcomes for the ST-IM Select signal-selection rule.","workflow_role":"Public signal outcome evidence.","required_inputs":{},"optional_inputs":{"start_date":{"type":"string","required":false,"format":"date","example":"2020-01-03","description":"Inclusive signal weekdate filter in YYYY-MM-DD format. If both date filters are omitted, the persistent summary table's trailing 10-year default window is applied."},"end_date":{"type":"string","required":false,"format":"date","example":"2024-12-27","description":"Inclusive signal weekdate filter in YYYY-MM-DD format. If both date filters are omitted, the persistent summary table row defines the latest mature outcome date."},"exchange":{"type":"string","required":false,"enum":["N","Q","A","B","T"],"example":"N","description":"Optional exchange filter."},"limit_rank":{"type":"integer","required":false,"minimum":1,"maximum":5000,"example":10,"description":"Optional per-week rank cutoff by prob13wk descending. When start_date and end_date are omitted, seeded default summary rows support limit_rank omitted/null and limit_rank=10; other no-date limit_rank values require explicit date filters or a custom summary refresh."}},"safe_example_request":{"method":"GET","path":"/v1/selections/stim-select/outcomes/summary","query":{"limit_rank":10}},"output_summary":"Aggregate historical count, date range, realized return averages/medians, positive-return rates, and base-period outperformance rates for ST-IM Select signal observations.","related_endpoints":["/v1/meta/stim","/v1/stim/latest","/v1/selections/history","/v1/selections/published/history"],"optional":true},{"step_id":"instrument_classification_history","endpoint":"GET /v1/indicators/history","method":"GET","path":"/v1/indicators/history","pricing_rule_id":"indicators_history_paid","stc_cost":0.01,"estimated_usd_cost":0.01,"supported_rails":["subscription","x402","mpp"],"pricing_note":"STC is the source of truth; payment rails translate this STC cost.","description":"Retrieve bounded weekly Stock Trends classification history for a resolved instrument: the core candidate feature set.","purpose":"Retrieve a bounded weekly history of Stock Trends indicator rows for one instrument.","workflow_role":"Historical signal context and trend persistence review.","required_inputs":{"symbol_exchange":{"type":"string","required":true,"example":"IBM-N","safe_default_for_demo":"IBM-N","pattern":"^[A-Z0-9.]+-[A-Z]$","description":"Stock Trends symbol plus exchange suffix."}},"optional_inputs":{"symbol":{"type":"string","required":false,"example":"IBM","description":"Ticker symbol. Use with exchange when symbol_exchange is not supplied."},"exchange":{"type":"string","required":false,"enum":["N","Q","A","B","T","I"],"example":"N","description":"Stock Trends exchange suffix. Common examples: N=NYSE, Q=NASDAQ, A=AMEX, T=TSX."},"cs_only":{"type":"boolean","required":false,"safe_default":true,"example":true,"description":"Filter to Common Stocks only where the endpoint supports instrument type filtering."},"start":{"type":"string","required":false,"format":"date","example":"2025-01-03","description":"Inclusive start weekdate in YYYY-MM-DD format."},"end":{"type":"string","required":false,"format":"date","example":"2025-12-26","description":"Inclusive end weekdate in YYYY-MM-DD format."},"limit":{"type":"integer","required":false,"safe_default":260,"minimum":1,"maximum":2600,"example":260,"description":"Maximum number of rows returned. This endpoint applies no default date window. The applied_bounds block on the response reports the limit that was actually used."}},"safe_example_request":{"method":"GET","path":"/v1/indicators/history","query":{"symbol_exchange":"IBM-N","limit":52,"cs_only":true}},"output_summary":"Weekly indicator history with trend classification, trend_cnt, mt_cnt, rsi, rsi_updn, vol_tag, price-change fields, moving averages, and high/low context.","related_endpoints":["/v1/indicators/latest","/v1/stim/history","/v1/prices/history"],"optional":false},{"step_id":"regime_history","endpoint":"GET /v1/market/regime/history","method":"GET","path":"/v1/market/regime/history","pricing_rule_id":"market_regime_history","stc_cost":0.25,"estimated_usd_cost":0.25,"supported_rails":["subscription","x402","mpp"],"pricing_note":"STC is the source of truth; payment rails translate this STC cost.","description":"Optionally retrieve recent market regime context. This endpoint returns at most 52 weekly regime observations and returns the most recent eligible weeks, so it covers recent regime history rather than an arbitrary research period. If the research interval predates that coverage, regime segmentation is the researcher's own work.","purpose":"Review recent market regime transitions.","workflow_role":"Historical market context.","required_inputs":{},"optional_inputs":{"limit":{"type":"integer","required":false,"safe_default":12,"minimum":1,"maximum":52,"example":12,"description":"Maximum number of rows returned. This endpoint applies no default date window. The applied_bounds block on the response reports the limit that was actually used."},"start_date":{"type":"string","required":false,"format":"date","example":"2025-01-03","description":"Optional earliest weekdate to include, in YYYY-MM-DD format. This filters which weeks are eligible; the endpoint still returns at most `limit` weeks and returns the most recent eligible weeks, so it does not select an arbitrary historical window."}},"safe_example_request":{"method":"GET","path":"/v1/market/regime/history","query":{"limit":12}},"output_summary":"Recent weekly market regime sequence.","related_endpoints":["/v1/market/regime/latest","/v1/market/regime/forecast"],"optional":true},{"step_id":"breadth_history","endpoint":"GET /v1/breadth/sector/history","method":"GET","path":"/v1/breadth/sector/history","pricing_rule_id":"breadth_sector_history_paid","stc_cost":0.3,"estimated_usd_cost":0.3,"supported_rails":["subscription","x402","mpp"],"pricing_note":"STC is the source of truth; payment rails translate this STC cost.","description":"Retrieve historical cross-sectional participation context as an independent candidate feature layer.","purpose":"Retrieve historical breadth context across sector or industry groupings.","workflow_role":"Market breadth context.","required_inputs":{},"optional_inputs":{"group_level":{"type":"string","required":false,"enum":["sector","industry_group","industry"],"safe_default":"sector"},"exchange":{"type":"string","required":false,"enum":["N","Q","A","B","T","I"],"example":"N","description":"Stock Trends exchange suffix. Common examples: N=NYSE, Q=NASDAQ, A=AMEX, T=TSX."},"start":{"type":"string","required":false,"format":"date","example":"2025-01-03","description":"Inclusive start weekdate in YYYY-MM-DD format."},"end":{"type":"string","required":false,"format":"date","example":"2025-12-26","description":"Inclusive end weekdate in YYYY-MM-DD format."},"group_by_week":{"type":"boolean","required":false,"safe_default":true},"population":{"type":"string","required":false,"enum":["equities","cs","all"],"safe_default":"equities","description":"equities is canonical CS+UN; cs is CS only; all is the legacy unrestricted population."},"cs_only":{"type":"boolean","required":false,"safe_default":null,"example":null,"description":"Legacy alias: omitted=equities, true=cs, false=all. Supplying a conflicting population is rejected."},"include_unknown":{"type":"boolean","required":false,"safe_default":false},"limit":{"type":"integer","required":false,"safe_default":5000,"minimum":1,"maximum":500000,"example":5000,"description":"Maximum number of rows returned. When start and end are both omitted, a trailing 104-week window ending at the latest available weekdate is applied as well. The applied_bounds block on the response reports the window and limit that were actually used."}},"safe_example_request":{"method":"GET","path":"/v1/breadth/sector/history","query":{"group_level":"sector","group_by_week":true}},"output_summary":"Historical breadth groups and weekly signal distribution metrics.","related_endpoints":["/v1/breadth/sector/latest","/v1/market/regime/history"],"optional":true},{"step_id":"leadership_rotation_history","endpoint":"GET /v1/leadership/rotation/history","method":"GET","path":"/v1/leadership/rotation/history","pricing_rule_id":"leadership_rotation_history_paid","stc_cost":0.3,"estimated_usd_cost":0.3,"supported_rails":["subscription","x402","mpp"],"pricing_note":"STC is the source of truth; payment rails translate this STC cost.","description":"Retrieve historical sector leadership concentration and rotation context as a further independent feature layer.","purpose":"Retrieve historical sector leadership rotation over time.","workflow_role":"Historical leadership rotation context.","required_inputs":{},"optional_inputs":{"exchange":{"type":"string","required":false,"enum":["N","Q","A","B","T","I","*"],"example":"N","description":"Stock Trends exchange suffix, or * for the canonical A/N/Q/T aggregate."},"start":{"type":"string","required":false,"format":"date","example":"2025-01-03","description":"Inclusive start weekdate in YYYY-MM-DD format."},"end":{"type":"string","required":false,"format":"date","example":"2025-12-26","description":"Inclusive end weekdate in YYYY-MM-DD format."},"type":{"type":"string","required":false,"safe_default":"EQ","example":"EQ","description":"Canonical rotation population. EQ (CS+UN) is the default; CS remains available for compatibility."},"top_k":{"type":"integer","required":false,"safe_default":5,"minimum":1,"maximum":50,"example":5,"description":"Top sectors per week. Omit for all sectors."},"min_constituents":{"type":"integer","required":false,"safe_default":25,"minimum":1,"maximum":5000,"example":25},"group_by_week":{"type":"boolean","required":false,"safe_default":true,"example":true},"limit":{"type":"integer","required":false,"safe_default":2000,"minimum":1,"maximum":50000,"example":2000,"description":"Maximum number of rows returned. When start and end are both omitted, a trailing 104-week window ending at the latest available weekdate is applied as well. The applied_bounds block on the response reports the window and limit that were actually used."}},"safe_example_request":{"method":"GET","path":"/v1/leadership/rotation/history","query":{"exchange":"N","type":"EQ","top_k":5,"group_by_week":true}},"output_summary":"Historical sector leadership rotation with bullish share, average RSI, trend maturity, leadership_score, and weekly rank.","related_endpoints":["/v1/leadership/summary/latest","/v1/breadth/sector/history","/v1/market/regime/history"],"optional":true},{"step_id":"price_context_history","endpoint":"GET /v1/prices/history","method":"GET","path":"/v1/prices/history","pricing_rule_id":"prices_history_paid","stc_cost":0.0075,"estimated_usd_cost":0.0075,"supported_rails":["subscription","x402","mpp"],"pricing_note":"STC is the source of truth; payment rails translate this STC cost.","description":"Retrieve bounded weekly price context the caller may use when constructing its own outcome definition.","purpose":"Retrieve weekly price history for one instrument.","workflow_role":"Historical price context.","required_inputs":{"symbol_exchange":{"type":"string","required":true,"example":"IBM-N","safe_default_for_demo":"IBM-N","pattern":"^[A-Z0-9.]+-[A-Z]$","description":"Stock Trends symbol plus exchange suffix."}},"optional_inputs":{"symbol":{"type":"string","required":false,"example":"IBM","description":"Ticker symbol. Use with exchange when symbol_exchange is not supplied."},"exchange":{"type":"string","required":false,"enum":["N","Q","A","B","T","I"],"example":"N","description":"Stock Trends exchange suffix. Common examples: N=NYSE, Q=NASDAQ, A=AMEX, T=TSX."},"cs_only":{"type":"boolean","required":false,"safe_default":true,"example":true,"description":"Filter to Common Stocks only where the endpoint supports instrument type filtering."},"start":{"type":"string","required":false,"format":"date","example":"2025-01-03","description":"Inclusive start weekdate in YYYY-MM-DD format."},"end":{"type":"string","required":false,"format":"date","example":"2025-12-26","description":"Inclusive end weekdate in YYYY-MM-DD format."},"limit":{"type":"integer","required":false,"safe_default":260,"minimum":1,"maximum":2600,"example":260,"description":"Maximum number of rows returned. This endpoint applies no default date window. The applied_bounds block on the response reports the limit that was actually used."}},"safe_example_request":{"method":"GET","path":"/v1/prices/history","query":{"symbol_exchange":"IBM-N","limit":52,"cs_only":true}},"output_summary":"Weekly price history for one symbol.","related_endpoints":["/v1/prices/latest","/v1/indicators/history"],"optional":true},{"step_id":"meta_stim","endpoint":"GET /v1/meta/stim","method":"GET","path":"/v1/meta/stim","pricing_rule_id":null,"stc_cost":0.0,"estimated_usd_cost":0.0,"supported_rails":[],"pricing_note":"Public non-metered planning helper; no STC charge applies.","description":"Retrieve the ST-IM provider profile, required only if ST-IM history is included in the evaluation.","purpose":"Retrieve the ST-IM provider profile, required only if ST-IM history is included in the evaluation.","workflow_role":null,"required_inputs":{},"optional_inputs":{},"safe_example_request":{"method":"GET","path":"/v1/meta/stim","query":{}},"output_summary":null,"related_endpoints":[],"optional":true},{"step_id":"inference_history","endpoint":"GET /v1/stim/history","method":"GET","path":"/v1/stim/history","pricing_rule_id":"stim_history_paid","stc_cost":0.0075,"estimated_usd_cost":0.0075,"supported_rails":["subscription","x402","mpp"],"pricing_note":"STC is the source of truth; payment rails translate this STC cost.","description":"Optionally retrieve bounded historical ST-IM forward-return distributions as one inference layer over the classification framework.","purpose":"Retrieve a symbol-level history of ST-IM distribution records.","workflow_role":"Historical forward-distribution context.","required_inputs":{"symbol_exchange":{"type":"string","required":true,"example":"IBM-N","safe_default_for_demo":"IBM-N","pattern":"^[A-Z0-9.]+-[A-Z]$","description":"Stock Trends symbol plus exchange suffix."}},"optional_inputs":{"symbol":{"type":"string","required":false,"example":"IBM","description":"Ticker symbol. Use with exchange when symbol_exchange is not supplied."},"exchange":{"type":"string","required":false,"enum":["N","Q","A","B","T","I"],"example":"N","description":"Stock Trends exchange suffix. Common examples: N=NYSE, Q=NASDAQ, A=AMEX, T=TSX."},"start":{"type":"string","required":false,"format":"date","example":"2025-01-03","description":"Inclusive start weekdate in YYYY-MM-DD format."},"end":{"type":"string","required":false,"format":"date","example":"2025-12-26","description":"Inclusive end weekdate in YYYY-MM-DD format."},"limit":{"type":"integer","required":false,"safe_default":260,"minimum":1,"maximum":2600,"example":260,"description":"Maximum number of rows returned. This endpoint applies no default date window. The applied_bounds block on the response reports the limit that was actually used."},"include_gaps":{"type":"boolean","required":false,"safe_default":false}},"safe_example_request":{"method":"GET","path":"/v1/stim/history","query":{"symbol_exchange":"IBM-N","limit":52}},"output_summary":"Historical ST-IM distributions across 4, 13, and 40 week horizons.","related_endpoints":["/v1/meta/inference","/v1/meta/stim","/v1/stim/latest","/v1/indicators/history"],"optional":true}]}]}