---
title: "Signal Events"
method: GET
path: "/events"
tags: ["Events"]
---

# Signal Events

`GET /events`

## Request

- Base URL: `https://api.falpha.ai`
- URL: `https://api.falpha.ai/events`
- Auth: one of:
  - API key in query parameter `api_key`
  - API key in header `X-API-Key`

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.

## Query parameters

- `type` string: Event type: flip, confidence_cross, sentiment_shift or screener_entry
- `tickers` string[], nullable: Tickers to watch (repeated param or comma separated). Up to 50. Not used by screener_entry.
- `period` string: Signal horizon: 5d, 15d, or 2m
- `regime` string: Market regime: neutral, bear, or bull
- `lookback_days` integer: How many calendar days back to look for events.
- `min_confidence` number, nullable: flip: only flips whose new confidence is at least this.
- `threshold` number, nullable: confidence_cross: the level to watch, between 0.5 and 1.
- `direction` string: confidence_cross: above, below or any. sentiment_shift: up, down or any. screener_entry: buy, sell or any.
- `min_shift` number: sentiment_shift: the smallest day-over-day move to report. Scores run from about -1 to 1.
- `sector` string, nullable: screener_entry: optional sector filter (see /sectors).
- `min_quality` number, nullable: screener_entry: minimum quality floor.
- `rank_by` string: screener_entry: confidence or quality
- `top` integer: screener_entry: the size of the list to watch (max 50).

## Response `200`

Successful Response

- EventsResponse
  - `type` string, required
  - `since` string, required: Events dated on or after this day are included.
  - `as_of` string, nullable: The newest data date the answer was computed from.
  - `count` integer, required
  - `events` Event[], required
    - `id` string, required: Stable id for this event. The same event always has the same id; deduplicate on it.
    - `type` string, required: flip, confidence_cross, sentiment_shift or screener_entry
    - `ticker` string, required
    - `date` string, required: The day the event happened (YYYY-MM-DD).
    - `previous_date` string, nullable: The earlier reading this one was compared with.
    - `period` string, nullable: Signal horizon: 5d, 15d or 2m
    - `horizon_label` string, nullable
    - `regime` string, nullable
    - `signal` string, nullable: The signal on the event date: buy or sell
    - `confidence` number, nullable: Confidence on the event date (0.5 to 1).
    - `previous_confidence` number, nullable
    - `from_signal` string, nullable: flip: the direction before
    - `to_signal` string, nullable: flip: the direction after
    - `threshold` number, nullable: confidence_cross: the level crossed
    - `crossed` string, nullable: confidence_cross: above or below
    - `sentiment` number, nullable: sentiment_shift: the daily news sentiment score on the event date
    - `previous_sentiment` number, nullable
    - `change` number, nullable: sentiment_shift: sentiment minus previous_sentiment
    - `shift` string, nullable: sentiment_shift: up or down
    - `signal_date` string, nullable: sentiment_shift: the date of the signal reading carried beside it
    - `rank` integer, nullable: screener_entry: position in the ranking
    - `rank_by` string, nullable
    - `top` integer, nullable
    - `quality` number, nullable: screener_entry: the quality score (a Sharpe-ratio proxy)
    - `url` string, required: The ticker's page on fAlpha.
    - `summary` string, required: One plain sentence describing the event. Model output, not investment advice.

## Other responses

- `422`: Validation Error

---

[API](https://skmtc.dev/falpha/apis/falpha-ai-api.md) · [All operations](https://skmtc.dev/falpha/apis/falpha-ai-api/llms.txt) · [OpenAPI document](https://skmtc.dev/falpha/apis/falpha-ai-api/revisions/d437fee1fac5?raw)