tickerbot_list_events

{
  "type": "object",
  "properties": {
    "kind": {
      "type": "string",
      "description": "Comma list of kinds. Omitted → the five corporate kinds; `signal` and `news` join only when named here.",
      "enum": [
        "dividend",
        "split",
        "insider",
        "analyst",
        "earnings",
        "signal",
        "news"
      ]
    },
    "ticker": {
      "type": "string",
      "description": "Single-ticker filter. When both `ticker` and `tickers` are passed, `ticker` wins."
    },
    "tickers": {
      "type": "string",
      "description": "Comma list of tickers (max 50). Mutually exclusive with `universe`."
    },
    "universe": {
      "type": "string",
      "description": "Universe slug (`top_10`, `top_100`, or one of yours) to scope the stream. Mutually exclusive with `tickers`."
    },
    "firm": {
      "type": "string",
      "description": "Analyst-only structured filter — requires `kind=analyst` alone (`400` otherwise). Exact firm-name match on the ratings feed."
    },
    "action": {
      "type": "string",
      "description": "Analyst-only structured filter — requires `kind=analyst` alone. Same `action` vocabulary as Analyst actions.",
      "enum": [
        "upgrades",
        "downgrades",
        "initiates_coverage_on",
        "maintains",
        "reiterates",
        "assumes",
        "reinstates",
        "suspends",
        "terminates_coverage_on"
      ]
    },
    "signal": {
      "type": "string",
      "description": "Signal-only filter — requires `kind=signal` alone (`400` otherwise). One built-in boolean signal; REQUIRED with `q` or `join=state` on that kind. See Signal firings."
    },
    "transition": {
      "type": "string",
      "description": "Signal-only filter — requires `kind=signal` alone. `enter` (false→true) or `exit` (true→false).",
      "enum": [
        "enter",
        "exit"
      ]
    },
    "from": {
      "type": "string",
      "description": "Events at/after this instant — strict ISO: `YYYY-MM-DD` or `YYYY-MM-DDTHH:MM[:SS]Z`. A bare `YYYY-MM-DD` means from the start of that day. (`since` accepted as an alias.)"
    },
    "to": {
      "type": "string",
      "description": "Window end — same strict ISO subset. A bare `YYYY-MM-DD` means through the end of that day, matching bars/series/spans; a timestamp is exclusive (events strictly before it). (`until` accepted as an alias.)"
    },
    "q": {
      "type": "string",
      "description": "SQL WHERE over the projection — `ticker`, `ts`, `kind`, `payload` (plus ticker-state signals when `join=state`). When exactly ONE `kind` is named, that kind's payload fields are additionally first-class typed columns (`amount > 1`, `firm = 'Goldman Sachs'` — see each kind page for its list); multi-kind requests use `payload->>'…'`. Max 4000 chars. ANDs with the filter params."
    },
    "join": {
      "type": "string",
      "description": "Set to `state` to allow ticker-state signals in `q`/`select`/`group_by`/`having`, evaluated as of each event's timestamp (daily resolution).",
      "enum": [
        "state"
      ]
    },
    "interval": {
      "type": "string",
      "description": "Grain the per-event state is reconstructed at, when `join=state`: `1m`, `1h`, `1d`, or `auto` (default). `auto` resolves to `1d` — the event set's tickers are not known before the query runs, and `1d` is the only tier covering the whole universe, so it is the only grain guaranteed to satisfy every event. An explicit `1m`/`1h` trades coverage for precision: events on tickers absent from that tier join to `null`. A referenced column the grain does not store is a `400`. Reported back as `_meta.state_interval`.",
      "enum": [
        "1m",
        "1h",
        "1d",
        "auto"
      ],
      "default": "auto"
    },
    "select": {
      "type": "string",
      "description": "Aggregate-mode output columns (requires `group_by`). Default: group keys + `COUNT(*) AS events`. Same naming rule as `group_by` — alias with `AS`, or take the name derived for you."
    },
    "group_by": {
      "type": "string",
      "description": "Comma list of rollup keys — switches the response to aggregate rows. Columns (`kind`, `ticker`), payload fields (`firm`, or the explicit `payload->>'firm'`), and expressions over them all roll up. Name a key with `AS` to choose its JSON key: `payload->>'firm' AS firm`. Un-named keys are named for you — a payload read takes its key (`payload->>'firm'` → `firm`), a function keeps the function's name (`lower(ticker)` → `lower`), and anything else falls back to `group_1`, `group_2`."
    },
    "having": {
      "type": "string",
      "description": "Post-aggregation filter. Requires `group_by`."
    },
    "order": {
      "type": "string",
      "description": "Aggregate-mode sort — a bare column name or an output name only (put expressions in `select` and sort by their alias). A group key's name works too, whether you aliased it or it was named for you: `group_by=payload->>'firm' AS firm&order=firm`. Default: `events`. (Row mode is always newest-first.)"
    },
    "dir": {
      "type": "string",
      "description": "Aggregate-mode sort direction.",
      "enum": [
        "asc",
        "desc"
      ],
      "default": "desc"
    },
    "limit": {
      "type": "integer",
      "description": "Page size (row modes) / max rollup rows (aggregate mode). Max 1000.",
      "default": 50
    },
    "cursor": {
      "type": "string",
      "description": "Opaque cursor from the previous response — carries the original filters (and `q` when short), so pass it alone. Not valid with `group_by`."
    }
  }
}