{"openapi":"3.1.0","info":{"title":"fAlpha.ai API","description":"\nWelcome to the fAlpha.ai API. Access trading signals, daily sentiment scores, and scraped news articles for S&P 500 tickers and beyond.\n\nAPI access is currently available to enterprise users only. Please contact [info@bam.money](mailto:info@bam.money) to request access.\n\nBy using the API, you consent to the [Terms of Service](https://bam.money/terms) and [Privacy Policy](https://bam.money/confidentiality-and-privacy).\n\n\n\n## Interactive Docs Guidance\n\nUse `/docs` for quick, small validation requests.\n\nFor larger batched queries or longer date ranges, prefer the generated `curl` command or call the endpoint URL directly from your browser or API client. Large JSON responses can make the interactive Swagger UI sluggish even when the API itself is healthy.\n\nCurrent date-range and size caps are:\n\n- `GET /signals-history/{ticker}`: up to **365 days**\n- `GET /signals-history-batched`: up to **90 days**\n- `GET /signals-history-all`: up to **30 days**\n- `GET /signals-batched`: up to **100 tickers** per call (latest signal per ticker)\n- `GET /screener`: up to **50 rows** per call\n\nAfter a large test, click **Clear** for that operation or refresh the page to keep the interactive docs responsive.\n\n\n\n## Data Dictionary\n\nThe API currently returns the following response fields:\n\n| Field | Meaning |\n| --- | --- |\n| `ticker` | Security ticker symbol, for example `AAPL`. |\n| `date` | For signals: the model run date in UTC. For articles: the crawl date in UTC. |\n| `period` | Signal forecast horizon. Current supported values are `5d`, `15d`, and `2m`. |\n| `regime` | Market regime used for the signal model: `neutral`, `bear`, or `bull`. |\n| `signal` | Trading direction returned by the model: `buy` or `sell`. |\n| `confidence` | Absolute value of the signal score used to rank signal strength. Recent rows use the index-adjusted score; older historical rows may fall back to the raw score when adjusted data is unavailable. |\n| `sentiment` | News sentiment paired with the signal: the **previous calendar day's** finalized average score (news is crawled overnight — including weekends — so day D's sentiment isn't ready when the day-D signal is produced; the most recent finalized reading is D-1's). Returns `null` when that reading is unavailable (internally, a stored score of `10.0` is a \"not computed\" sentinel and is always surfaced as `null`). |\n| `quality` | Optional block of signal quality metrics. `null` unless the request sets `include_quality=true`; individual metrics may still be `null` when unavailable for a row. |\n| `quality.sharpe_ratio` | Risk-adjusted measure of the signal's recent strength (a Sharpe-ratio proxy). Higher is better; can be negative. |\n| `quality.sortino_ratio` | Downside-risk-adjusted counterpart to the Sharpe ratio. |\n| `quality.iis_score` | Information-strength score for the signal at this horizon. |\n| `quality.normalized_iis` | IIS score normalized for cross-ticker comparison. |\n| `quality.percent_positive_pnl` | Percentage of recent signal-following outcomes with positive PnL (0–100). |\n| `performance` | Optional realized-performance block on history rows. `null` unless the request sets `include_performance=true`. Values are backfilled once returns are realized, so recent rows return `null` fields. |\n| `performance.pnl` | Realized signal-following PnL for the row's horizon. |\n| `performance.ticker_return` / `performance.index_return` | Realized gross-return ratios over the horizon for the ticker and the benchmark index (`1.05` = +5%). |\n| `performance.release_date` | When realized returns were backfilled for the row. |\n| `as_of` | Screener responses: the model-run date of the screened signal cube (the latest available). |\n| `surface` | Usage metering: originating client surface — `excel`, `sheets`, `sdk-python`, or `api` (default) — attributed via the optional `X-Falpha-Surface` request header. |\n| `by_client` | Usage metering: split by anonymous install id (optional `X-Falpha-Client` header; each add-in install / spreadsheet generates its own). No user accounts involved. |\n| `predictions` | Historical array of signal rows for a ticker. |\n| `count` | Number of articles returned in an articles response. |\n| `articles` | Array of article objects returned by the articles endpoint. |\n| `title` | Article headline. |\n| `score` | Sentiment score for an individual article. |\n| `source` | Source domain or publisher for the article. |\n| `summary` | AI-generated summary for the article when available. |\n| `link` | Canonical article URL. |\n| `account` | Role, access, and subscription metadata for the caller. Returned by `GET /account` and available to any authenticated API key, including non-enterprise ones. |\n","termsOfService":"https://bam.money/terms","contact":{"name":"fAlpha.ai","url":"https://bam.money/contact","email":"info@bam.money"},"version":"0.2.0"},"paths":{"/health":{"get":{"tags":["Health"],"summary":"Health","description":"Liveness/readiness probe. No authentication and no rate limit. Reports API status and Mongo reachability.","operationId":"health_health_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}}}}},"/signals/{ticker}":{"get":{"tags":["Signals"],"summary":"Signals","description":"Get the latest signal and sentiment for a ticker.","operationId":"get_signals_signals__ticker__get","security":[{"APIKeyQuery":[]},{"APIKeyHeader":[]}],"parameters":[{"name":"ticker","in":"path","required":true,"schema":{"type":"string","title":"Ticker"}},{"name":"period","in":"query","required":false,"schema":{"type":"string","description":"Signal horizon: 5d, 15d, or 2m","default":"15d","title":"Period"},"description":"Signal horizon: 5d, 15d, or 2m"},{"name":"regime","in":"query","required":false,"schema":{"type":"string","description":"Market regime: neutral, bear, or bull","default":"neutral","title":"Regime"},"description":"Market regime: neutral, bear, or bull"},{"name":"include_sentiment","in":"query","required":false,"schema":{"type":"boolean","description":"Include sentiment enrichment from daily sentiment data. Defaults to false; set to true to include sentiment lookups.","default":false,"title":"Include Sentiment"},"description":"Include sentiment enrichment from daily sentiment data. Defaults to false; set to true to include sentiment lookups."},{"name":"include_quality","in":"query","required":false,"schema":{"type":"boolean","description":"Include signal quality metrics (Sharpe/Sortino/IIS). Defaults to false; when true the `quality` field is populated (individual metrics may still be null).","default":false,"title":"Include Quality"},"description":"Include signal quality metrics (Sharpe/Sortino/IIS). Defaults to false; when true the `quality` field is populated (individual metrics may still be null)."},{"name":"include_drivers","in":"query","required":false,"schema":{"type":"boolean","description":"Include the model's top attribution drivers (which named factors moved the signal, as % of total attribution). Defaults to false.","default":false,"title":"Include Drivers"},"description":"Include the model's top attribution drivers (which named factors moved the signal, as % of total attribution). Defaults to false."}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/signal"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/signals-history/{ticker}":{"get":{"tags":["Signals"],"summary":"Signal History","description":"Get historical signals and sentiment for a ticker. If no date range is provided, returns the last 7 calendar days by default.","operationId":"get_signal_history_signals_history__ticker__get","security":[{"APIKeyQuery":[]},{"APIKeyHeader":[]}],"parameters":[{"name":"ticker","in":"path","required":true,"schema":{"type":"string","title":"Ticker"}},{"name":"period","in":"query","required":false,"schema":{"type":"string","description":"Signal horizon: 5d, 15d, or 2m","default":"15d","title":"Period"},"description":"Signal horizon: 5d, 15d, or 2m"},{"name":"regime","in":"query","required":false,"schema":{"type":"string","description":"Market regime: neutral, bear, or bull","default":"neutral","title":"Regime"},"description":"Market regime: neutral, bear, or bull"},{"name":"include_sentiment","in":"query","required":false,"schema":{"type":"boolean","description":"Include sentiment enrichment from daily sentiment data. Defaults to false; set to true to include sentiment lookups.","default":false,"title":"Include Sentiment"},"description":"Include sentiment enrichment from daily sentiment data. Defaults to false; set to true to include sentiment lookups."},{"name":"include_quality","in":"query","required":false,"schema":{"type":"boolean","description":"Include signal quality metrics (Sharpe/Sortino/IIS). Defaults to false; when true the `quality` field is populated (individual metrics may still be null).","default":false,"title":"Include Quality"},"description":"Include signal quality metrics (Sharpe/Sortino/IIS). Defaults to false; when true the `quality` field is populated (individual metrics may still be null)."},{"name":"include_performance","in":"query","required":false,"schema":{"type":"boolean","description":"Include realized performance fields (pnl, ticker_return, index_return, release_date). Defaults to false. Values are backfilled once returns are realized, so recent rows return nulls.","default":false,"title":"Include Performance"},"description":"Include realized performance fields (pnl, ticker_return, index_return, release_date). Defaults to false. Values are backfilled once returns are realized, so recent rows return nulls."},{"name":"start_date","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Start date (YYYY-MM-DD, inclusive). If both dates are omitted, history endpoints default to the last 7 calendar days. The maximum allowed range between start_date and end_date for this endpoint is 365 days; larger ranges are rejected with HTTP 400.","title":"Start Date"},"description":"Start date (YYYY-MM-DD, inclusive). If both dates are omitted, history endpoints default to the last 7 calendar days. The maximum allowed range between start_date and end_date for this endpoint is 365 days; larger ranges are rejected with HTTP 400."},{"name":"end_date","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"End date (YYYY-MM-DD, inclusive). If both dates are omitted, history endpoints default to the last 7 calendar days. The maximum allowed range between start_date and end_date for this endpoint is 365 days; larger ranges are rejected with HTTP 400.","title":"End Date"},"description":"End date (YYYY-MM-DD, inclusive). If both dates are omitted, history endpoints default to the last 7 calendar days. The maximum allowed range between start_date and end_date for this endpoint is 365 days; larger ranges are rejected with HTTP 400."}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/signal_history"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/signals-history-batched":{"get":{"tags":["Signals"],"summary":"Batched Signal History","description":"Get historical signals and sentiment for one or more tickers. If no date range is provided, returns the last 7 calendar days by default.","operationId":"get_signal_history_batched_signals_history_batched_get","security":[{"APIKeyQuery":[]},{"APIKeyHeader":[]}],"parameters":[{"name":"tickers","in":"query","required":true,"schema":{"type":"array","items":{"type":"string"},"description":"List of tickers, e.g. tickers=AAPL&tickers=MSFT","title":"Tickers"},"description":"List of tickers, e.g. tickers=AAPL&tickers=MSFT"},{"name":"period","in":"query","required":false,"schema":{"type":"string","description":"Signal horizon: 5d, 15d, or 2m","default":"15d","title":"Period"},"description":"Signal horizon: 5d, 15d, or 2m"},{"name":"regime","in":"query","required":false,"schema":{"type":"string","description":"Market regime: neutral, bear, or bull","default":"neutral","title":"Regime"},"description":"Market regime: neutral, bear, or bull"},{"name":"include_sentiment","in":"query","required":false,"schema":{"type":"boolean","description":"Include sentiment enrichment from daily sentiment data. Defaults to false; set to true to include sentiment lookups.","default":false,"title":"Include Sentiment"},"description":"Include sentiment enrichment from daily sentiment data. Defaults to false; set to true to include sentiment lookups."},{"name":"include_quality","in":"query","required":false,"schema":{"type":"boolean","description":"Include signal quality metrics (Sharpe/Sortino/IIS). Defaults to false; when true the `quality` field is populated (individual metrics may still be null).","default":false,"title":"Include Quality"},"description":"Include signal quality metrics (Sharpe/Sortino/IIS). Defaults to false; when true the `quality` field is populated (individual metrics may still be null)."},{"name":"include_performance","in":"query","required":false,"schema":{"type":"boolean","description":"Include realized performance fields (pnl, ticker_return, index_return, release_date). Defaults to false. Values are backfilled once returns are realized, so recent rows return nulls.","default":false,"title":"Include Performance"},"description":"Include realized performance fields (pnl, ticker_return, index_return, release_date). Defaults to false. Values are backfilled once returns are realized, so recent rows return nulls."},{"name":"start_date","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Start date (YYYY-MM-DD, inclusive). If both dates are omitted, history endpoints default to the last 7 calendar days. The maximum allowed range between start_date and end_date for this endpoint is 90 days; larger ranges are rejected with HTTP 400.","title":"Start Date"},"description":"Start date (YYYY-MM-DD, inclusive). If both dates are omitted, history endpoints default to the last 7 calendar days. The maximum allowed range between start_date and end_date for this endpoint is 90 days; larger ranges are rejected with HTTP 400."},{"name":"end_date","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"End date (YYYY-MM-DD, inclusive). If both dates are omitted, history endpoints default to the last 7 calendar days. The maximum allowed range between start_date and end_date for this endpoint is 90 days; larger ranges are rejected with HTTP 400.","title":"End Date"},"description":"End date (YYYY-MM-DD, inclusive). If both dates are omitted, history endpoints default to the last 7 calendar days. The maximum allowed range between start_date and end_date for this endpoint is 90 days; larger ranges are rejected with HTTP 400."}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/batched_signal_history"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/signals-history-all":{"get":{"tags":["Signals"],"summary":"All Batched Signal History","description":"Get historical signals and sentiment for all tickers in a sector. If no date range is provided, returns the last 7 calendar days by default.","operationId":"get_signal_history_all_signals_history_all_get","security":[{"APIKeyQuery":[]},{"APIKeyHeader":[]}],"parameters":[{"name":"sector","in":"query","required":true,"schema":{"type":"string","description":"Sector name (e.g. 'energy', 'healthcare', 'financials')","title":"Sector"},"description":"Sector name (e.g. 'energy', 'healthcare', 'financials')"},{"name":"period","in":"query","required":false,"schema":{"type":"string","description":"Signal horizon: 5d, 15d, or 2m","default":"15d","title":"Period"},"description":"Signal horizon: 5d, 15d, or 2m"},{"name":"regime","in":"query","required":false,"schema":{"type":"string","description":"Market regime: neutral, bear, or bull","default":"neutral","title":"Regime"},"description":"Market regime: neutral, bear, or bull"},{"name":"include_sentiment","in":"query","required":false,"schema":{"type":"boolean","description":"Include sentiment enrichment from daily sentiment data. Defaults to false; set to true to include sentiment lookups.","default":false,"title":"Include Sentiment"},"description":"Include sentiment enrichment from daily sentiment data. Defaults to false; set to true to include sentiment lookups."},{"name":"include_quality","in":"query","required":false,"schema":{"type":"boolean","description":"Include signal quality metrics (Sharpe/Sortino/IIS). Defaults to false; when true the `quality` field is populated (individual metrics may still be null).","default":false,"title":"Include Quality"},"description":"Include signal quality metrics (Sharpe/Sortino/IIS). Defaults to false; when true the `quality` field is populated (individual metrics may still be null)."},{"name":"include_performance","in":"query","required":false,"schema":{"type":"boolean","description":"Include realized performance fields (pnl, ticker_return, index_return, release_date). Defaults to false. Values are backfilled once returns are realized, so recent rows return nulls.","default":false,"title":"Include Performance"},"description":"Include realized performance fields (pnl, ticker_return, index_return, release_date). Defaults to false. Values are backfilled once returns are realized, so recent rows return nulls."},{"name":"start_date","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Start date (YYYY-MM-DD, inclusive). If both dates are omitted, history endpoints default to the last 7 calendar days. The maximum allowed range between start_date and end_date for this endpoint is 30 days; larger ranges are rejected with HTTP 400.","title":"Start Date"},"description":"Start date (YYYY-MM-DD, inclusive). If both dates are omitted, history endpoints default to the last 7 calendar days. The maximum allowed range between start_date and end_date for this endpoint is 30 days; larger ranges are rejected with HTTP 400."},{"name":"end_date","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"End date (YYYY-MM-DD, inclusive). If both dates are omitted, history endpoints default to the last 7 calendar days. The maximum allowed range between start_date and end_date for this endpoint is 30 days; larger ranges are rejected with HTTP 400.","title":"End Date"},"description":"End date (YYYY-MM-DD, inclusive). If both dates are omitted, history endpoints default to the last 7 calendar days. The maximum allowed range between start_date and end_date for this endpoint is 30 days; larger ranges are rejected with HTTP 400."}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/batched_signal_history"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/signals-batched":{"get":{"tags":["Signals"],"summary":"Batched Latest Signals","description":"Get the latest signal for up to 100 tickers in a single call. The response is keyed by uppercase ticker; tickers with no signal data are omitted. Requests with more than 100 distinct tickers are rejected with HTTP 400.","operationId":"get_signals_batched_signals_batched_get","security":[{"APIKeyQuery":[]},{"APIKeyHeader":[]}],"parameters":[{"name":"tickers","in":"query","required":true,"schema":{"type":"array","items":{"type":"string"},"description":"List of tickers (repeated param), e.g. tickers=AAPL&tickers=MSFT. Up to 100 distinct tickers.","title":"Tickers"},"description":"List of tickers (repeated param), e.g. tickers=AAPL&tickers=MSFT. Up to 100 distinct tickers."},{"name":"period","in":"query","required":false,"schema":{"type":"string","description":"Signal horizon: 5d, 15d, or 2m","default":"15d","title":"Period"},"description":"Signal horizon: 5d, 15d, or 2m"},{"name":"regime","in":"query","required":false,"schema":{"type":"string","description":"Market regime: neutral, bear, or bull","default":"neutral","title":"Regime"},"description":"Market regime: neutral, bear, or bull"},{"name":"include_sentiment","in":"query","required":false,"schema":{"type":"boolean","description":"Include sentiment enrichment from daily sentiment data. Defaults to false; set to true to include sentiment lookups.","default":false,"title":"Include Sentiment"},"description":"Include sentiment enrichment from daily sentiment data. Defaults to false; set to true to include sentiment lookups."},{"name":"include_quality","in":"query","required":false,"schema":{"type":"boolean","description":"Include signal quality metrics (Sharpe/Sortino/IIS). Defaults to false; when true the `quality` field is populated (individual metrics may still be null).","default":false,"title":"Include Quality"},"description":"Include signal quality metrics (Sharpe/Sortino/IIS). Defaults to false; when true the `quality` field is populated (individual metrics may still be null)."},{"name":"include_drivers","in":"query","required":false,"schema":{"type":"boolean","description":"Include the model's top attribution drivers (which named factors moved the signal, as % of total attribution). Defaults to false.","default":false,"title":"Include Drivers"},"description":"Include the model's top attribution drivers (which named factors moved the signal, as % of total attribution). Defaults to false."}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/batched_latest_signals"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/screener":{"get":{"tags":["Signals"],"summary":"Signal Screener","description":"Cross-sectional sweep of the covered universe on the latest model-run date: rank tickers by signal strength or quality, optionally filtered by direction, sector, and a minimum quality floor. Returns at most 50 rows. **Billing/DB note:** `top` only truncates the response. Ranking requires reading the filtered cube date (often the full universe), so `top=10` and `top=50` do essentially the same Mongo work — see response field `scanned` and the usage `meter` (db_docs). Prefer sector filters to shrink work.","operationId":"get_screener_screener_get","security":[{"APIKeyQuery":[]},{"APIKeyHeader":[]}],"parameters":[{"name":"period","in":"query","required":false,"schema":{"type":"string","description":"Signal horizon: 5d, 15d, or 2m","default":"15d","title":"Period"},"description":"Signal horizon: 5d, 15d, or 2m"},{"name":"regime","in":"query","required":false,"schema":{"type":"string","description":"Market regime: neutral, bear, or bull","default":"neutral","title":"Regime"},"description":"Market regime: neutral, bear, or bull"},{"name":"direction","in":"query","required":false,"schema":{"type":"string","description":"Filter by signal direction: buy, sell, or any","default":"any","title":"Direction"},"description":"Filter by signal direction: buy, sell, or any"},{"name":"sector","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Optional sector filter (e.g. 'energy', 'informationtechnology')","title":"Sector"},"description":"Optional sector filter (e.g. 'energy', 'informationtechnology')"},{"name":"min_quality","in":"query","required":false,"schema":{"anyOf":[{"type":"number"},{"type":"null"}],"description":"Minimum quality (Sharpe-ratio proxy) floor; rows without a quality value are excluded when set","title":"Min Quality"},"description":"Minimum quality (Sharpe-ratio proxy) floor; rows without a quality value are excluded when set"},{"name":"rank_by","in":"query","required":false,"schema":{"type":"string","description":"Ranking key: confidence (absolute signal score) or quality (Sharpe-ratio proxy)","default":"confidence","title":"Rank By"},"description":"Ranking key: confidence (absolute signal score) or quality (Sharpe-ratio proxy)"},{"name":"top","in":"query","required":false,"schema":{"type":"integer","maximum":50,"minimum":1,"description":"Number of rows to return (max 50). Does not reduce DB scan size.","default":25,"title":"Top"},"description":"Number of rows to return (max 50). Does not reduce DB scan size."}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/screener_response"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/signals-card":{"get":{"tags":["Signals"],"summary":"Signal Cards","description":"Presentation-ready signal cards for up to 100 tickers in one call: direction, confidence, holding period (hp), regime, the top explainability drivers (named factors with their % share of the model's attribution and whether each pushed the signal bullish or bearish), and a deep link to the ticker's fAlpha page. Built for spreadsheet dashboards.","operationId":"get_signals_card_signals_card_get","security":[{"APIKeyQuery":[]},{"APIKeyHeader":[]}],"parameters":[{"name":"tickers","in":"query","required":true,"schema":{"type":"array","items":{"type":"string"},"description":"List of tickers (repeated param). Up to 100 distinct.","title":"Tickers"},"description":"List of tickers (repeated param). Up to 100 distinct."},{"name":"period","in":"query","required":false,"schema":{"type":"string","description":"Signal horizon: 5d, 15d, or 2m","default":"15d","title":"Period"},"description":"Signal horizon: 5d, 15d, or 2m"},{"name":"regime","in":"query","required":false,"schema":{"type":"string","description":"Market regime: neutral, bear, or bull","default":"neutral","title":"Regime"},"description":"Market regime: neutral, bear, or bull"},{"name":"drivers","in":"query","required":false,"schema":{"type":"integer","maximum":10,"minimum":0,"description":"Number of top drivers to include (0-10)","default":4,"title":"Drivers"},"description":"Number of top drivers to include (0-10)"}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/batched_signal_cards"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/articles/{ticker}":{"get":{"tags":["News"],"summary":"News Articles","description":"Get scraped news articles and their sentiment scores for a ticker. Use `date` for a single day, or `start_date` / `end_date` for a range. If none are provided, defaults to today (UTC).","operationId":"get_articles_articles__ticker__get","security":[{"APIKeyQuery":[]},{"APIKeyHeader":[]}],"parameters":[{"name":"ticker","in":"path","required":true,"schema":{"type":"string","title":"Ticker"}},{"name":"date","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Single date (YYYY-MM-DD). Ignored when start_date/end_date are set.","title":"Date"},"description":"Single date (YYYY-MM-DD). Ignored when start_date/end_date are set."},{"name":"start_date","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Range start (YYYY-MM-DD, inclusive).","title":"Start Date"},"description":"Range start (YYYY-MM-DD, inclusive)."},{"name":"end_date","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Range end (YYYY-MM-DD, inclusive).","title":"End Date"},"description":"Range end (YYYY-MM-DD, inclusive)."}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/articles_list_response"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/account":{"get":{"tags":["Account"],"summary":"Account","description":"Returns the account and role information associated with the provided API key. Any valid API key can call this endpoint, even without enterprise access, so customers can inspect why they are (or are not) being granted access.","operationId":"get_account_account_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/account_response"}}}}},"security":[{"APIKeyQuery":[]},{"APIKeyHeader":[]}]}},"/account/usage":{"get":{"tags":["Account"],"summary":"Account Usage","description":"Aggregated API usage for the calling key over the last N days (default 30): totals by day, by endpoint, and by client surface (excel / sdk-python / api). Surfaces are attributed via the optional X-Falpha-Surface request header. Available to any valid API key. Counts successful and failed requests (failures are recorded by the metering middleware with their status_code).","operationId":"get_account_usage_account_usage_get","security":[{"APIKeyQuery":[]},{"APIKeyHeader":[]}],"parameters":[{"name":"days","in":"query","required":false,"schema":{"type":"integer","maximum":90,"minimum":1,"description":"Aggregation window in days (max 90)","default":30,"title":"Days"},"description":"Aggregation window in days (max 90)"}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/usage_response"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/tickers/available":{"get":{"tags":["Discovery"],"summary":"Available Tickers","description":"List every ticker currently covered by the signal model. Refreshed from the underlying coverage data at most every 15 minutes. Use this to validate watchlists before requesting signals.","operationId":"get_tickers_available_tickers_available_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/available_tickers_response"}}}}},"security":[{"APIKeyQuery":[]},{"APIKeyHeader":[]}]}},"/sectors":{"get":{"tags":["Discovery"],"summary":"Sectors","description":"List the sector taxonomy. `key` is the slug accepted by the `sector` query parameter on /signals-history-all and /screener; `name` is the display label.","operationId":"get_sectors_sectors_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/sectors_response"}}}}},"security":[{"APIKeyQuery":[]},{"APIKeyHeader":[]}]}}},"components":{"schemas":{"HTTPValidationError":{"properties":{"detail":{"items":{"$ref":"#/components/schemas/ValidationError"},"type":"array","title":"Detail"}},"type":"object","title":"HTTPValidationError"},"ValidationError":{"properties":{"loc":{"items":{"anyOf":[{"type":"string"},{"type":"integer"}]},"type":"array","title":"Location"},"msg":{"type":"string","title":"Message"},"type":{"type":"string","title":"Error Type"}},"type":"object","required":["loc","msg","type"],"title":"ValidationError"},"account_response":{"properties":{"email":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Email"},"is_admin":{"type":"boolean","title":"Is Admin","default":false},"is_enterprise":{"type":"boolean","title":"Is Enterprise","default":false},"api_disabled":{"type":"boolean","title":"Api Disabled","default":false},"role":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"title":"Role"}},"type":"object","title":"account_response"},"article_response":{"properties":{"date":{"type":"string","title":"Date","description":"Crawl date (YYYY-MM-DD)","example":"2026-04-14"},"title":{"type":"string","title":"Title","description":"Article headline","example":"Apple reports record earnings"},"score":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Score","description":"Sentiment score for this article","example":0.65},"source":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Source","description":"Source domain","example":"seekingalpha.com"},"summary":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Summary","description":"AI-generated summary of the article"},"link":{"type":"string","title":"Link","description":"URL of the article","example":"https://seekingalpha.com/article/123"}},"type":"object","required":["date","title","link"],"title":"article_response"},"articles_list_response":{"properties":{"ticker":{"type":"string","title":"Ticker","example":"AAPL"},"date":{"type":"string","title":"Date","description":"Requested date","example":"2026-04-14"},"count":{"type":"integer","title":"Count","description":"Number of articles returned","example":5},"articles":{"items":{"$ref":"#/components/schemas/article_response"},"type":"array","title":"Articles"}},"type":"object","required":["ticker","date","count","articles"],"title":"articles_list_response"},"available_tickers_response":{"properties":{"available_tickers":{"items":{"type":"string"},"type":"array","title":"Available Tickers"}},"type":"object","required":["available_tickers"],"title":"available_tickers_response"},"batched_latest_signals":{"additionalProperties":{"$ref":"#/components/schemas/signal"},"type":"object","title":"batched_latest_signals","description":"Latest signal per ticker, keyed by uppercase ticker symbol.","example":{"AAPL":{"confidence":0.51,"date":"2026-07-13T00:00:00","period":"15d","regime":"neutral","sentiment":0.42,"signal":"buy","ticker":"AAPL"},"MSFT":{"confidence":0.48,"date":"2026-07-13T00:00:00","period":"15d","regime":"neutral","signal":"sell","ticker":"MSFT"}}},"batched_signal_cards":{"additionalProperties":{"$ref":"#/components/schemas/signal_card"},"type":"object","title":"batched_signal_cards","description":"Signal card per ticker, keyed by uppercase ticker symbol."},"batched_signal_history":{"additionalProperties":{"$ref":"#/components/schemas/signal_history"},"type":"object","title":"batched_signal_history"},"driver":{"properties":{"name":{"type":"string","title":"Name","description":"Human-readable factor name, e.g. Price, Sentiment, Volume, Credit Ratings","example":"Sentiment"},"weight_pct":{"type":"number","title":"Weight Pct","description":"Share of total signal attribution (0-100)","example":23.4},"direction":{"type":"string","title":"Direction","description":"Which way this factor pushes the signal: buy or sell","example":"buy"}},"type":"object","required":["name","weight_pct","direction"],"title":"driver","description":"One attribution driver: which factor moved the signal, and how much."},"performance_metrics":{"properties":{"pnl":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Pnl","description":"Realized signal-following PnL for this row's horizon. Null until realized."},"ticker_return":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Ticker Return","description":"Realized ticker gross-return ratio over the horizon (1.05 = +5%). Null until realized."},"index_return":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Index Return","description":"Realized benchmark index gross-return ratio over the same window (1.05 = +5%). Null until realized."},"release_date":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Release Date","description":"When realized returns were backfilled for this row."}},"type":"object","title":"performance_metrics","description":"Realized performance for a historical signal row. These values are\nbackfilled once returns are realized, so recent rows legitimately return\nnulls. Only populated when the request sets include_performance=true.","example":{"index_return":0.012,"pnl":0.0123,"release_date":"2026-05-18T00:00:00","ticker_return":0.031}},"quality_metrics":{"properties":{"sharpe_ratio":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Sharpe Ratio","description":"Risk-adjusted measure of the signal's recent strength (a Sharpe-ratio proxy). Higher is better; can be negative."},"sortino_ratio":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Sortino Ratio","description":"Downside-risk-adjusted counterpart to the Sharpe ratio."},"iis_score":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Iis Score","description":"Information-strength score for the signal at this horizon."},"normalized_iis":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Normalized Iis","description":"IIS score normalized for cross-ticker comparison."},"percent_positive_pnl":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Percent Positive Pnl","description":"Percentage of recent signal-following outcomes with positive PnL (0-100)."}},"type":"object","title":"quality_metrics","description":"Signal quality metrics for one signal row. Only populated when the request\nsets include_quality=true; otherwise the parent `quality` key is null.\nIndividual metrics are null when unavailable for that row.","example":{"iis_score":0.18,"normalized_iis":0.55,"percent_positive_pnl":0.57,"sharpe_ratio":0.42,"sortino_ratio":0.61}},"screener_response":{"properties":{"as_of":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"As Of","description":"Model-run date of the screened signal cube (latest available)"},"period":{"type":"string","title":"Period"},"regime":{"type":"string","title":"Regime"},"direction":{"type":"string","title":"Direction","description":"Direction filter applied: buy, sell, or any"},"sector":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Sector","description":"Sector filter applied, if any"},"rank_by":{"type":"string","title":"Rank By","description":"Ranking key: confidence or quality"},"count":{"type":"integer","title":"Count"},"scanned":{"type":"integer","title":"Scanned","description":"Docs considered from the cube date (after sector filter, before top truncate). `top` only caps `results` — DB work is O(scanned), so top=10 and top=50 cost the same."},"results":{"items":{"$ref":"#/components/schemas/screener_row"},"type":"array","title":"Results"}},"type":"object","required":["period","regime","direction","rank_by","count","scanned","results"],"title":"screener_response","example":{"as_of":"2026-07-13T00:00:00","count":2,"direction":"buy","period":"15d","rank_by":"confidence","regime":"neutral","results":[{"confidence":0.61,"date":"2026-07-13T00:00:00","quality":0.44,"signal":"buy","ticker":"XOM"},{"confidence":0.55,"date":"2026-07-13T00:00:00","quality":0.29,"signal":"buy","ticker":"CVX"}],"scanned":120,"sector":"energy"}},"screener_row":{"properties":{"ticker":{"type":"string","title":"Ticker"},"date":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Date"},"signal":{"type":"string","title":"Signal","description":"buy or sell (sign of the signal score)"},"confidence":{"type":"number","title":"Confidence","description":"Absolute signal score used for ranking"},"quality":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Quality","description":"Sharpe-ratio quality proxy for the row (null when unavailable)"}},"type":"object","required":["ticker","signal","confidence"],"title":"screener_row"},"sector_entry":{"properties":{"key":{"type":"string","title":"Key","description":"Slug accepted by `sector` query parameters, e.g. 'informationtechnology'"},"name":{"type":"string","title":"Name","description":"Display name, e.g. 'Information Technology'"}},"type":"object","required":["key","name"],"title":"sector_entry"},"sectors_response":{"properties":{"sectors":{"items":{"$ref":"#/components/schemas/sector_entry"},"type":"array","title":"Sectors"}},"type":"object","required":["sectors"],"title":"sectors_response"},"signal":{"properties":{"ticker":{"type":"string","title":"Ticker","description":"Stock ticker symbol","example":"AAPL"},"date":{"anyOf":[{"type":"string","format":"date-time"},{"type":"string"},{"type":"null"}],"title":"Date"},"period":{"type":"string","title":"Period","description":"Signal horizon: 5d, 15d, or 2m","example":"15d"},"regime":{"type":"string","title":"Regime","description":"Market regime: neutral, bear, or bull","example":"neutral"},"signal":{"type":"string","title":"Signal","description":"Signal: buy or sell","example":"buy"},"confidence":{"type":"number","title":"Confidence","description":"Confidence level","example":0.73},"sentiment":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Sentiment","description":"Average daily sentiment score (null when unavailable)","example":0.42},"quality":{"anyOf":[{"$ref":"#/components/schemas/quality_metrics"},{"type":"null"}],"description":"Signal quality metrics. Null unless include_quality=true is requested."},"drivers":{"anyOf":[{"items":{"$ref":"#/components/schemas/driver"},"type":"array"},{"type":"null"}],"title":"Drivers","description":"Top attribution drivers (which factors moved the signal). Null unless include_drivers=true is requested."}},"type":"object","required":["ticker","period","regime","signal","confidence"],"title":"signal"},"signal_card":{"properties":{"ticker":{"type":"string","title":"Ticker"},"date":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Date"},"direction":{"type":"string","title":"Direction","description":"buy or sell"},"confidence":{"type":"number","title":"Confidence","description":"Absolute signal score (higher = stronger)"},"hp":{"type":"string","title":"Hp","description":"Holding period / forecast horizon: 5d, 15d, or 2m"},"regime":{"type":"string","title":"Regime","description":"Market regime the signal is conditioned on: neutral, bear, or bull"},"drivers":{"items":{"$ref":"#/components/schemas/driver"},"type":"array","title":"Drivers","description":"Top factors moving this signal, most influential first"},"url":{"type":"string","title":"Url","description":"Deep link to the ticker's page on falpha.ai"}},"type":"object","required":["ticker","direction","confidence","hp","regime","url"],"title":"signal_card","description":"A compact, presentation-ready signal card: direction + confidence + horizon\n+ regime + the top explainability drivers + a deep link to the fAlpha page.","example":{"confidence":0.5073,"date":"2026-07-15T00:00:00","direction":"buy","drivers":[{"direction":"sell","name":"Day of Week","weight_pct":41.0},{"direction":"buy","name":"Credit Ratings","weight_pct":26.4},{"direction":"sell","name":"Price","weight_pct":22.1},{"direction":"buy","name":"Volume","weight_pct":6.1}],"hp":"15d","regime":"neutral","ticker":"NVDA","url":"https://falpha.ai/company/NVDA"}},"signal_history":{"properties":{"ticker":{"type":"string","title":"Ticker"},"regime":{"type":"string","title":"Regime"},"period":{"type":"string","title":"Period"},"predictions":{"items":{"$ref":"#/components/schemas/signal_item"},"type":"array","title":"Predictions"}},"type":"object","required":["ticker","regime","period","predictions"],"title":"signal_history"},"signal_item":{"properties":{"date":{"type":"string","format":"date-time","title":"Date"},"signal":{"type":"string","title":"Signal"},"confidence":{"type":"number","title":"Confidence"},"sentiment":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Sentiment","description":"Average daily sentiment score (null when unavailable)"},"quality":{"anyOf":[{"$ref":"#/components/schemas/quality_metrics"},{"type":"null"}],"description":"Signal quality metrics. Null unless include_quality=true is requested."},"performance":{"anyOf":[{"$ref":"#/components/schemas/performance_metrics"},{"type":"null"}],"description":"Realized performance fields. Null unless include_performance=true is requested; inner fields stay null until returns are realized."}},"type":"object","required":["date","signal","confidence"],"title":"signal_item"},"usage_bucket":{"properties":{"key":{"type":"string","title":"Key","description":"Bucket label: a YYYY-MM-DD day, an endpoint path, or a surface name"},"count":{"type":"integer","title":"Count"}},"type":"object","required":["key","count"],"title":"usage_bucket"},"usage_response":{"properties":{"window_days":{"type":"integer","title":"Window Days","description":"Size of the aggregation window in days"},"since":{"type":"string","format":"date-time","title":"Since","description":"UTC start of the aggregation window"},"total":{"type":"integer","title":"Total","description":"Total successful requests recorded in the window"},"by_day":{"items":{"$ref":"#/components/schemas/usage_bucket"},"type":"array","title":"By Day"},"by_endpoint":{"items":{"$ref":"#/components/schemas/usage_bucket"},"type":"array","title":"By Endpoint"},"by_surface":{"items":{"$ref":"#/components/schemas/usage_bucket"},"type":"array","title":"By Surface","description":"Split by client surface: excel, sheets, sdk-python, or api (default)"},"by_client":{"items":{"$ref":"#/components/schemas/usage_bucket"},"type":"array","title":"By Client","description":"Split by anonymous install id (X-Falpha-Client header); requests without one bucket under '-'"},"meter":{"additionalProperties":true,"type":"object","title":"Meter","description":"Unified work meter summed over the window: db_calls, db_docs, db_ms (see dbmeter contract). Requests are traffic; the meter is work."}},"type":"object","required":["window_days","since","total","by_day","by_endpoint","by_surface"],"title":"usage_response"}},"securitySchemes":{"APIKeyQuery":{"type":"apiKey","in":"query","name":"api_key"},"APIKeyHeader":{"type":"apiKey","in":"header","name":"X-API-Key"}}},"servers":[{"url":"https://api.falpha.ai","description":"fAlpha.ai API server"}],"x-topics":[{"title":"Getting Started","content":"\nTo get started, contact the fAlpha.ai team to provision enterprise API access and an API key.\n\n1. Contact [info@bam.money](mailto:info@bam.money)\n2. Receive your enterprise API credentials\n3. Use your API key to access the API\n"},{"title":"Authentication","content":"\nThe fAlpha.ai API uses API keys to authenticate requests. Send your key in the `X-API-Key` request header (preferred):\n\n```\ncurl -H \"X-API-Key: YOUR_KEY\" https://api.falpha.ai/signals/NVDA\n```\n\nThe legacy `api_key` query parameter is still accepted for backward compatibility. Prefer the header: query strings tend to be captured in proxy/server logs and browser history. When both are sent, the header wins.\n\n> info\n> Your API keys carry many privileges, so be sure to keep them secure! **Do not share your API keys** in publicly accessible areas such as GitHub, client-side code, and so forth.\n"},{"title":"Rate Limits","content":"\nThe fAlpha.ai API enforces rate limits per API key:\n\n- **10 requests per second** (burst cap)\n- **300 requests per minute** (sustained cap)\n\nIf you exceed either limit, you will receive a `429 Too Many Requests` response with a `Retry-After` header indicating how many seconds to wait before retrying.\n\nThe official Python SDK and Excel add-in pace themselves within these limits automatically (client-side token buckets, request batching, and `Retry-After`-aware retries), so a 100-ticker watchlist still resolves in a single request via `GET /signals-batched`.\n"},{"title":"Client Surfaces (SDK & Excel)","content":"\nThree first-party client surfaces wrap this API:\n\n- **Python SDK (`falpha`)** — a typed client with client-side rate limiting, retries, pandas integration, analytics helpers (screener, signal flips, regime consensus, pre-trade validation), and a CLI.\n- **Excel add-in** — `=FALPHA.*` custom functions (single cells, spilled history, watchlists, screener) plus a task pane with account, usage, and pre-trade validation panels.\n- **Google Sheets add-on** — `FALPHA_*` custom functions and a sidebar with the same watchlist / validator / screener / usage workflows.\n\nEach sends an `X-Falpha-Surface` header (`sdk-python` / `excel` / `sheets`) so `GET /account/usage` can meter usage per surface. Direct integrations may omit the header (metered as `api`).\n"},{"title":"Interactive Docs Guidance","content":"\n## Interactive Docs Guidance\n\nUse `/docs` for quick, small validation requests.\n\nFor larger batched queries or longer date ranges, prefer the generated `curl` command or call the endpoint URL directly from your browser or API client. Large JSON responses can make the interactive Swagger UI sluggish even when the API itself is healthy.\n\nCurrent date-range and size caps are:\n\n- `GET /signals-history/{ticker}`: up to **365 days**\n- `GET /signals-history-batched`: up to **90 days**\n- `GET /signals-history-all`: up to **30 days**\n- `GET /signals-batched`: up to **100 tickers** per call (latest signal per ticker)\n- `GET /screener`: up to **50 rows** per call\n\nAfter a large test, click **Clear** for that operation or refresh the page to keep the interactive docs responsive.\n"},{"title":"Enterprise Access","content":"\nThe API is currently available to enterprise users only. To access data (including sentiment scores and summaries) for our full corpus of 16,000+ tickers, please contact [info@bam.money](mailto:info@bam.money).\n"},{"title":"Data Timing","content":"\n- **Signal dates** reflect the model run date (UTC). A signal dated 2026-04-14 uses market data available as of that date; prices in the signal correspond to the previous trading day's close.\n- **Sentiment scores** and **articles** correspond to the crawl calendar day (UTC midnight). The crawl runs overnight (including weekends), so a signal's paired `sentiment` is the **previous calendar day's** finalized score, not the signal date's. Up to 10 articles per ticker per day are scraped.\n- **Realized performance fields** (`include_performance=true`) are backfilled after each horizon completes, so the most recent history rows return `null` values until returns are realized.\n- All timestamps in API responses are in UTC.\n"},{"title":"Data Dictionary","content":"\n## Data Dictionary\n\nThe API currently returns the following response fields:\n\n| Field | Meaning |\n| --- | --- |\n| `ticker` | Security ticker symbol, for example `AAPL`. |\n| `date` | For signals: the model run date in UTC. For articles: the crawl date in UTC. |\n| `period` | Signal forecast horizon. Current supported values are `5d`, `15d`, and `2m`. |\n| `regime` | Market regime used for the signal model: `neutral`, `bear`, or `bull`. |\n| `signal` | Trading direction returned by the model: `buy` or `sell`. |\n| `confidence` | Absolute value of the signal score used to rank signal strength. Recent rows use the index-adjusted score; older historical rows may fall back to the raw score when adjusted data is unavailable. |\n| `sentiment` | News sentiment paired with the signal: the **previous calendar day's** finalized average score (news is crawled overnight — including weekends — so day D's sentiment isn't ready when the day-D signal is produced; the most recent finalized reading is D-1's). Returns `null` when that reading is unavailable (internally, a stored score of `10.0` is a \"not computed\" sentinel and is always surfaced as `null`). |\n| `quality` | Optional block of signal quality metrics. `null` unless the request sets `include_quality=true`; individual metrics may still be `null` when unavailable for a row. |\n| `quality.sharpe_ratio` | Risk-adjusted measure of the signal's recent strength (a Sharpe-ratio proxy). Higher is better; can be negative. |\n| `quality.sortino_ratio` | Downside-risk-adjusted counterpart to the Sharpe ratio. |\n| `quality.iis_score` | Information-strength score for the signal at this horizon. |\n| `quality.normalized_iis` | IIS score normalized for cross-ticker comparison. |\n| `quality.percent_positive_pnl` | Percentage of recent signal-following outcomes with positive PnL (0–100). |\n| `performance` | Optional realized-performance block on history rows. `null` unless the request sets `include_performance=true`. Values are backfilled once returns are realized, so recent rows return `null` fields. |\n| `performance.pnl` | Realized signal-following PnL for the row's horizon. |\n| `performance.ticker_return` / `performance.index_return` | Realized gross-return ratios over the horizon for the ticker and the benchmark index (`1.05` = +5%). |\n| `performance.release_date` | When realized returns were backfilled for the row. |\n| `as_of` | Screener responses: the model-run date of the screened signal cube (the latest available). |\n| `surface` | Usage metering: originating client surface — `excel`, `sheets`, `sdk-python`, or `api` (default) — attributed via the optional `X-Falpha-Surface` request header. |\n| `by_client` | Usage metering: split by anonymous install id (optional `X-Falpha-Client` header; each add-in install / spreadsheet generates its own). No user accounts involved. |\n| `predictions` | Historical array of signal rows for a ticker. |\n| `count` | Number of articles returned in an articles response. |\n| `articles` | Array of article objects returned by the articles endpoint. |\n| `title` | Article headline. |\n| `score` | Sentiment score for an individual article. |\n| `source` | Source domain or publisher for the article. |\n| `summary` | AI-generated summary for the article when available. |\n| `link` | Canonical article URL. |\n| `account` | Role, access, and subscription metadata for the caller. Returned by `GET /account` and available to any authenticated API key, including non-enterprise ones. |\n"}]}