Events

GET /v1/events is the feed of your alerts. Store next_cursor after every page. Send that cursor on the next request. You then read each alert once.

The feed keeps alerts for 7 days. sequence on a feed event is null. A webhook copy of the same alert carries a sequence. The object itself is the alert schema.

Query

• Name: cursor. Meaning: Opaque next_cursor from an earlier page. It is c1_ plus the base64url form of a decimal alert id. Treat it as opaque. An example of the shape, for id 9001, is c1_OTAwMQ.
• Name: start. Meaning: latest or earliest. The default is latest. Ignored when cursor is set.
• Name: wait. Meaning: Whole seconds from 0 to 25. The default is 0.
• Name: limit. Meaning: Whole number from 1 to 100. The default is 50.
• Name: rule_id. Meaning: Only alerts for that rule. An unknown rule is 404.

start=latest begins after the newest alert, so the first page is empty until a new alert arrives. start=earliest begins at the oldest alert the feed still has. Use it once, store next_cursor, and continue with the cursor.

wait=0 returns the page that is ready. When the page already has events, the answer returns then, even if wait is above 0. When the page is empty and wait is above 0, the request stays open until an alert arrives or the wait ends. A key may have 2 of these open at once.

The page

• Field: events. Meaning: Alert objects, oldest first. Empty when nothing new is waiting.
• Field: next_cursor. Meaning: Pass this as cursor on the next request, whether or not this page had events.
• Field: has_more. Meaning: True when this page contains limit events. Read the next page with next_cursor. That next page can be empty.
• Field: gap. Meaning: True only when you sent a cursor and an alert after that cursor has aged out of the 7-day feed. False for start=earliest and for a cursor that is still inside the feed.

A muted rule, a snoozed rule, and a duplicate held back from this destination are left out of the feed. An alert held for quiet hours, the daily limit, or the morning brief is still in the feed.

When gap is true, read GET /v1/rules/{id}/record for alerts the plan's history still keeps, or GET /v1/alerts/{id} when you have the id. Drop duplicates by event id.

This request counts as a call only when events is not empty. An empty page is free. The rate limit still counts it.

The latest page is empty

Example. These are not live prices.

GET /v1/events?start=latest&wait=0 HTTP/1.1
Authorization: Bearer $TERMINAL_API_KEY

HTTP/1.1 200 OK

{
  "events": [],
  "next_cursor": "…",
  "has_more": false,
  "gap": false
}

An empty page is normal until a rule fires. The call is in Create your first rule.

The earliest page

Example. These are not live prices.

GET /v1/events?start=earliest&wait=0 HTTP/1.1
Authorization: Bearer $TERMINAL_API_KEY

HTTP/1.1 200 OK

{
  "events": [
    {
      "schema": "terminal.alert.v1",
      "type": "alert.fired",
      "sequence": null,
      "headline": "Solana (SOL) fell 5.0% in 1 hour.",
      "asset": { "symbol": "SOL", "name": "Solana" },
      "rule": {
        "name": "SOL falls 5% in 1 hour",
        "kind": "percent_change"
      },
      "note": { "status": "none" },
      "service": null
    }
  ],
  "next_cursor": "…",
  "has_more": false,
  "gap": false
}

Resume from the cursor

Send the cursor you stored. The page after the last alert is empty, and gap is false while that alert is still inside 7 days.

Example. These are not live prices.

GET /v1/events?cursor=$NEXT_CURSOR&wait=0 HTTP/1.1
Authorization: Bearer $TERMINAL_API_KEY

HTTP/1.1 200 OK

{
  "events": [],
  "next_cursor": "…",
  "has_more": false,
  "gap": false
}

Rules on the account

GET /v1/rules lists rules that are not archived, oldest first, plus how many are active against the plan limit.

Example. These are not live prices.

GET /v1/rules HTTP/1.1
Authorization: Bearer $TERMINAL_API_KEY

HTTP/1.1 200 OK

{
  "rules": [
    {
      "name": "SOL falls 5% in 1 hour",
      "kind": "percent_change",
      "scope": "symbol",
      "status": "active",
      "cooldown_seconds": 3600,
      "asset": { "symbol": "SOL", "name": "Solana" },
      "condition": { "threshold_pct": 5, "window": "1h", "direction": "down" }
    }
  ],
  "usage": { "active": 1, "limit": 200 }
}

Create a free account

Terminal reports market events for conditions you set. It does not tell you to buy, sell, or hold, and it does not place trades.