fAlpha Events API

openapi: 3.2.0
info:
  title: fAlpha.ai Events API
  description: 'Welcome to the fAlpha.ai API. Access trading signals, daily sentiment scores, and scraped news articles for S&P 500 tickers and beyond. API access is currently available to enterprise users only. Please contact info@bam.money to request access. By using the API, you consent to the Terms of Service and Privacy Policy. ## Interactive Docs Guidance


    Use `/docs` for quick, small validation requests. For 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. Current date-range and size caps are:


    - `GET /signals-history/{ticker}`: up to **365 days**

    - `GET /signals-history-batched`: up to **90 days**

    - `GET /signals-history-all`: up to **30 days**

    - `GET /signals-batched`: up to **100 tickers** per call (latest signal per ticker)

    - `GET /screener`: up to **50 rows** per call


    After a large test, click **Clear** for that operation or refresh the page to keep the interactive docs responsive. ## Data Dictionary


    The API currently returns the following response fields:


    | Field | Meaning |

    | --- | --- |

    | `ticker` | Security ticker symbol, for example `AAPL`. |

    | `date` | For signals: the model run date in UTC. For articles: the crawl date in UTC. |

    | `period` | Signal forecast horizon. Current supported values are `5d`, `15d`, and `2m`. |

    | `regime` | Market regime used for the signal model: `neutral`, `bear`, or `bull`. |

    | `signal` | Trading direction returned by the model: `buy` or `sell`. |

    | `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. |

    | `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`). |

    | `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. |

    | `quality.sharpe_ratio` | Risk-adjusted measure of the signal''s recent strength (a Sharpe-ratio proxy). Higher is better; can be negative. |

    | `quality.sortino_ratio` | Downside-risk-adjusted counterpart to the Sharpe ratio. |

    | `quality.iis_score` | Information-strength score for the signal at this horizon. |

    | `quality.normalized_iis` | IIS score normalized for cross-ticker comparison. |

    | `quality.percent_positive_pnl` | Percentage of recent signal-following outcomes with positive PnL (0–100). |

    | `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. |

    | `performance.pnl` | Realized signal-following PnL for the row''s horizon. |

    | `performance.ticker_return` / `performance.index_return` | Realized gross-return ratios over the horizon for the ticker and the benchmark index (`1.05` = +5%). |

    | `performance.release_date` | When realized returns were backfilled for the row. |

    | `as_of` | Screener responses: the model-run date of the screened signal cube (the latest available). |

    | `surface` | Usage metering: originating client surface — `excel`, `sheets`, `sdk-python`, `zapier`, or `api` (default) — attributed via the optional `X-Falpha-Surface` request header. |

    | `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.'
  termsOfService: https://bam.money/terms
  contact:
    name: fAlpha.ai
    url: https://bam.money/contact
    email: info@bam.money
  version: 0.2.0
servers:
- url: https://api.falpha.ai
  description: fAlpha.ai API server
tags:
- name: Events
paths:
  /events:
    get:
      tags:
      - Events
      summary: Signal Events
      description: 'What changed, for clients that poll. Returns the events of one `type` inside a short window, newest first, each with a stable `id` to deduplicate on.


        - `flip`: the signal changed direction (buy to sell, or sell to buy).

        - `confidence_cross`: confidence moved across `threshold`. Confidence runs from 0.5 to 1. On the 5d and 15d horizons it stays near 0.5 to 0.65, so a level such as 0.8 only crosses on 2m.

        - `sentiment_shift`: the daily news sentiment score moved by at least `min_shift` from the previous reading. Each event carries the ticker''s current signal beside it.

        - `screener_entry`: a ticker entered the top N of a screen (same filters as `/screener`). Takes no `tickers`.


        **Billing:** each event is billed once per account, however many times it is returned. A request that returns nothing new costs nothing. Events already in the window the first time a given set of parameters is requested are not billed. A flip, crossing or sentiment shift counts as that day''s reading of its ticker, so reading the same ticker again that day costs nothing more. Up to 50 tickers per request.'
      operationId: get_events_events_get
      security:
      - APIKeyQuery: []
      - APIKeyHeader: []
      parameters:
      - name: type
        in: query
        required: false
        schema:
          type: string
          description: 'Event type: flip, confidence_cross, sentiment_shift or screener_entry'
          default: flip
          title: Type
        description: 'Event type: flip, confidence_cross, sentiment_shift or screener_entry'
      - name: tickers
        in: query
        required: false
        schema:
          anyOf:
          - type: array
            items:
              type: string
          - type: 'null'
          description: Tickers to watch (repeated param or comma separated). Up to 50. Not used by screener_entry.
          title: Tickers
        description: Tickers to watch (repeated param or comma separated). Up to 50. Not used by screener_entry.
      - 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: lookback_days
        in: query
        required: false
        schema:
          type: integer
          maximum: 14
          minimum: 1
          description: How many calendar days back to look for events.
          default: 7
          title: Lookback Days
        description: How many calendar days back to look for events.
      - name: min_confidence
        in: query
        required: false
        schema:
          anyOf:
          - type: number
            maximum: 1
            minimum: 0
          - type: 'null'
          description: 'flip: only flips whose new confidence is at least this.'
          title: Min Confidence
        description: 'flip: only flips whose new confidence is at least this.'
      - name: threshold
        in: query
        required: false
        schema:
          anyOf:
          - type: number
            exclusiveMaximum: 1
            exclusiveMinimum: 0.5
          - type: 'null'
          description: 'confidence_cross: the level to watch, between 0.5 and 1.'
          title: Threshold
        description: 'confidence_cross: the level to watch, between 0.5 and 1.'
      - name: direction
        in: query
        required: false
        schema:
          type: string
          description: 'confidence_cross: above, below or any. sentiment_shift: up, down or any. screener_entry: buy, sell or any.'
          default: any
          title: Direction
        description: 'confidence_cross: above, below or any. sentiment_shift: up, down or any. screener_entry: buy, sell or any.'
      - name: min_shift
        in: query
        required: false
        schema:
          type: number
          maximum: 2
          exclusiveMinimum: 0
          description: 'sentiment_shift: the smallest day-over-day move to report. Scores run from about -1 to 1.'
          default: 0.4
          title: Min Shift
        description: 'sentiment_shift: the smallest day-over-day move to report. Scores run from about -1 to 1.'
      - name: sector
        in: query
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          description: 'screener_entry: optional sector filter (see /sectors).'
          title: Sector
        description: 'screener_entry: optional sector filter (see /sectors).'
      - name: min_quality
        in: query
        required: false
        schema:
          anyOf:
          - type: number
          - type: 'null'
          description: 'screener_entry: minimum quality floor.'
          title: Min Quality
        description: 'screener_entry: minimum quality floor.'
      - name: rank_by
        in: query
        required: false
        schema:
          type: string
          description: 'screener_entry: confidence or quality'
          default: confidence
          title: Rank By
        description: 'screener_entry: confidence or quality'
      - name: top
        in: query
        required: false
        schema:
          type: integer
          maximum: 50
          minimum: 1
          description: 'screener_entry: the size of the list to watch (max 50).'
          default: 10
          title: Top
        description: 'screener_entry: the size of the list to watch (max 50).'
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/events_response'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
components:
  schemas:
    events_response:
      properties:
        type:
          type: string
          title: Type
        since:
          type: string
          title: Since
          description: Events dated on or after this day are included.
        as_of:
          anyOf:
          - type: string
          - type: 'null'
          title: As Of
          description: The newest data date the answer was computed from.
        count:
          type: integer
          title: Count
        events:
          items:
            $ref: '#/components/schemas/event'
          type: array
          title: Events
      type: object
      required:
      - type
      - since
      - count
      - events
      title: events_response
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          type: array
          title: Detail
      type: object
      title: HTTPValidationError
    event:
      properties:
        id:
          type: string
          title: Id
          description: Stable id for this event. The same event always has the same id; deduplicate on it.
        type:
          type: string
          title: Type
          description: flip, confidence_cross, sentiment_shift or screener_entry
        ticker:
          type: string
          title: Ticker
        date:
          type: string
          title: Date
          description: The day the event happened (YYYY-MM-DD).
        previous_date:
          anyOf:
          - type: string
          - type: 'null'
          title: Previous Date
          description: The earlier reading this one was compared with.
        period:
          anyOf:
          - type: string
          - type: 'null'
          title: Period
          description: 'Signal horizon: 5d, 15d or 2m'
        horizon_label:
          anyOf:
          - type: string
          - type: 'null'
          title: Horizon Label
        regime:
          anyOf:
          - type: string
          - type: 'null'
          title: Regime
        signal:
          anyOf:
          - type: string
          - type: 'null'
          title: Signal
          description: 'The signal on the event date: buy or sell'
        confidence:
          anyOf:
          - type: number
          - type: 'null'
          title: Confidence
          description: Confidence on the event date (0.5 to 1).
        previous_confidence:
          anyOf:
          - type: number
          - type: 'null'
          title: Previous Confidence
        from_signal:
          anyOf:
          - type: string
          - type: 'null'
          title: From Signal
          description: 'flip: the direction before'
        to_signal:
          anyOf:
          - type: string
          - type: 'null'
          title: To Signal
          description: 'flip: the direction after'
        threshold:
          anyOf:
          - type: number
          - type: 'null'
          title: Threshold
          description: 'confidence_cross: the level crossed'
        crossed:
          anyOf:
          - type: string
          - type: 'null'
          title: Crossed
          description: 'confidence_cross: above or below'
        sentiment:
          anyOf:
          - type: number
          - type: 'null'
          title: Sentiment
          description: 'sentiment_shift: the daily news sentiment score on the event date'
        previous_sentiment:
          anyOf:
          - type: number
          - type: 'null'
          title: Previous Sentiment
        change:
          anyOf:
          - type: number
          - type: 'null'
          title: Change
          description: 'sentiment_shift: sentiment minus previous_sentiment'
        shift:
          anyOf:
          - type: string
          - type: 'null'
          title: Shift
          description: 'sentiment_shift: up or down'
        signal_date:
          anyOf:
          - type: string
          - type: 'null'
          title: Signal Date
          description: 'sentiment_shift: the date of the signal reading carried beside it'
        rank:
          anyOf:
          - type: integer
          - type: 'null'
          title: Rank
          description: 'screener_entry: position in the ranking'
        rank_by:
          anyOf:
          - type: string
          - type: 'null'
          title: Rank By
        top:
          anyOf:
          - type: integer
          - type: 'null'
          title: Top
        quality:
          anyOf:
          - type: number
          - type: 'null'
          title: Quality
          description: 'screener_entry: the quality score (a Sharpe-ratio proxy)'
        url:
          type: string
          title: Url
          description: The ticker's page on fAlpha.
        summary:
          type: string
          title: Summary
          description: One plain sentence describing the event. Model output, not investment advice.
      type: object
      required:
      - id
      - type
      - ticker
      - date
      - url
      - summary
      title: event
    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
  securitySchemes:
    APIKeyQuery:
      type: apiKey
      in: query
      name: api_key
    APIKeyHeader:
      type: apiKey
      in: header
      name: X-API-Key
x-topics:
- title: Getting Started
  content: '

    To get started, contact the fAlpha.ai team to provision enterprise API access and an API key.


    1. Contact [info@bam.money](mailto:info@bam.money)

    2. Receive your enterprise API credentials

    3. Use your API key to access the API

    '
- title: Authentication
  content: '

    The fAlpha.ai API uses API keys to authenticate requests. Send your key in the `X-API-Key` request header (preferred):


    ```

    curl -H "X-API-Key: YOUR_KEY" https://api.falpha.ai/signals/NVDA

    ```


    The 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.


    > info

    > 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.

    '
- title: Rate Limits
  content: '

    The fAlpha.ai API enforces rate limits per API key:


    - **10 requests per second** (burst cap)

    - **300 requests per minute** (sustained cap)


    If 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.


    The 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`.

    '
- title: Client Surfaces (SDK & Excel)
  content: '

    Three first-party client surfaces wrap this API:


    - **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.

    - **Excel add-in** — `=FALPHA.*` custom functions (single cells, spilled history, watchlists, screener) plus a task pane with account, usage, and pre-trade validation panels.

    - **Google Sheets add-on** — `FALPHA_*` custom functions and a sidebar with the same watchlist / validator / screener / usage workflows.


    Each 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`).

    '
- title: Interactive Docs Guidance
  content: '

    ## Interactive Docs Guidance


    Use `/docs` for quick, small validation requests.


    For 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.


    Current date-range and size caps are:


    - `GET /signals-history/{ticker}`: up to **365 days**

    - `GET /signals-history-batched`: up to **90 days**

    - `GET /signals-history-all`: up to **30 days**

    - `GET /signals-batched`: up to **100 tickers** per call (latest signal per ticker)

    - `GET /screener`: up to **50 rows** per call


    After a large test, click **Clear** for that operation or refresh the page to keep the interactive docs responsive.

    '
- title: Enterprise Access
  content: '

    The 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@falpha.ai](mailto:info@falpha.ai).

    '
- title: Data Timing
  content: '

    - **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.

    - **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.

    - **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.

    - All timestamps in API responses are in UTC.

    '
- title: Data Dictionary
  content: '

    ## Data Dictionary


    The API currently returns the following response fields:


    | Field | Meaning |

    | --- | --- |

    | `ticker` | Security ticker symbol, for example `AAPL`. |

    | `date` | For signals: the model run date in UTC. For articles: the crawl date in UTC. |

    | `period` | Signal forecast horizon. Current supported values are `5d`, `15d`, and `2m`. |

    | `regime` | Market regime used for the signal model: `neutral`, `bear`, or `bull`. |

    | `signal` | Trading direction returned by the model: `buy` or `sell`. |

    | `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. |

    | `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`). |

    | `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. |

    | `quality.sharpe_ratio` | Risk-adjusted measure of the signal''s recent strength (a Sharpe-ratio proxy). Higher is better; can be negative. |

    | `quality.sortino_ratio` | Downside-risk-adjusted counterpart to the Sharpe ratio. |

    | `quality.iis_score` | Information-strength score for the signal at this horizon. |

    | `quality.normalized_iis` | IIS score normalized for cross-ticker comparison. |

    | `quality.percent_positive_pnl` | Percentage of recent signal-following outcomes with positive PnL (0–100). |

    | `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. |

    | `performance.pnl` | Realized signal-following PnL for the row''s horizon. |

    | `performance.ticker_return` / `performance.index_return` | Realized gross-return ratios over the horizon for the ticker and the benchmark index (`1.05` = +5%). |

    | `performance.release_date` | When realized returns were backfilled for the row. |

    | `as_of` | Screener responses: the model-run date of the screened signal cube (the latest available). |

    | `surface` | Usage metering: originating client surface — `excel`, `sheets`, `sdk-python`, `zapier`, or `api` (default) — attributed via the optional `X-Falpha-Surface` request header. |

    | `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. |

    | `predictions` | Historical array of signal rows for a ticker. |

    | `count` | Number of articles returned in an articles response. |

    | `articles` | Array of article objects returned by the articles endpoint. |

    | `title` | Article headline. |

    | `score` | Sentiment score for an individual article. |

    | `source` | Source domain or publisher for the article. |

    | `summary` | AI-generated summary for the article when available. |

    | `link` | Canonical article URL. |

    | `account` | Role, access, and subscription metadata for the caller. Returned by `GET /account` and available to any authenticated API key, including non-enterprise ones. |

    '