List events

GET/scripts/{slug}/events

Returns a definition's stored events, oldest first, filtered by instrument, timeframe, event, time, version and payload. These are the events studies read, from every time the definition ran over history in the app or the API.

Scope	Heavy call	Long poll	CLI
`scripts:read`	No	No	`chartnaut events`

Guidance

Stored events come only from running the definition over history. A run of a definition returns that run's events and stores nothing here. If a list comes back empty, check Summarise events and Run a definition over history for the instrument and timeframe you want.
total counts every event that matches the filters, across every page. Read it first to decide whether to page through everything.
Filter on the server rather than in your code: where takes up to 10 payload filters, and an event must match all of them. [{"key":"range","op":"gt","value":10}] keeps events whose range is above 10.
Pass version to see only what one version found. Without it, events from every version come back together.
A CSV answer carries no next_cursor. To page CSV, pass the number of rows already read as cursor, and stop at a page shorter than limit.
The path is your own definition's bare slug. A @N suffix is accepted and ignored, and a study that shares the slug is ignored here.

Path parameters

Name	Type	Description
`slug`	string	Your definition's slug

Query parameters

Name	Type	Required	Default	Description
`instrument`	string	No	All	Canonical or short symbol
`timeframe`	string	No	All	One of the timeframes
`event`	string	No	All	A declared event id
`from`	string	No	None	RFC 3339. Keeps events that start at or after it
`to`	string	No	None	RFC 3339. Keeps events that end at or before it
`version`	integer	No	All	Keeps events found by this version of the definition
`where`	string	No	None	Payload filters as a JSON array, URL-encoded. Fields below
`format`	string	No	`json`	`json` or `csv`
`limit`	integer	No	100	Most 1,000
`cursor`	string	No	None	From the previous page's `next_cursor`

where filter object

Field	Type	Required	Description
`key`	string	Yes	A payload key: letters, digits, `_` and `.`
`op`	string	Yes	`eq`, `neq`, `contains`, `gt`, `gte`, `lt`, `lte`, `between`, `is_empty` or `is_not_empty`
`value`	any	For every op but `is_empty` and `is_not_empty`	The value to compare with. The lower bound for `between`
`valueTo`	any	For `between`	The upper bound

Response

200 with:

Field	Type	Description
`events`	array of Event	This page of events
`total`	integer	How many events match the filters, across every page
`next_cursor`	string or null	Pass it back as `cursor` for the next page. `null` on the last page

With format=csv, the answer is text/csv with a header row event,intent,instrument,timeframe,start,end,bar_index,payload and one row per event on this page. payload is a JSON string.

Status codes

Status	Code	Meaning
`200`	-	A page of events. `events` is `[]` when nothing matches
`400`	`invalid_request`	The slug is not valid, `from` or `to` is not RFC 3339, `version` is not a positive integer, or `where` is not a valid filter list. The message says which
`400`	`unknown_instrument`	No instrument matches `instrument`
`400`	`unsupported_timeframe`	`timeframe` is not one of the nine
`404`	`not_found`	You have no definition with that slug, or it has no such `version`

Example request

curl -G https://api.chartnaut.com/v1/scripts/bull-bar/events \
  -H "Authorization: Bearer cn_live_XXXX" \
  --data-urlencode "instrument=BTC" \
  --data-urlencode "timeframe=5m" \
  --data-urlencode 'where=[{"key":"range","op":"gt","value":10}]' \
  --data-urlencode "limit=1"

Example response

200 OK

{
  "events": [
    {
      "event": "bull_bar",
      "intent": "long",
      "instrument": "HYPERLIQUID:BTC",
      "timeframe": "5m",
      "start": "2026-06-28T10:05:00Z",
      "end": "2026-06-28T10:10:00Z",
      "bar_index": 1,
      "payload": { "range": 42, "body_pct": 0.81 }
    }
  ],
  "total": 3118,
  "next_cursor": "1"
}

400 Bad Request

{
  "error": {
    "code": "invalid_request",
    "message": "from must be RFC 3339, e.g. 2026-01-02T00:00:00Z."
  }
}

From the CLI

chartnaut events bull-bar --on BTC --tf 5m --where '[{"key":"range","op":"gt","value":10}]' --limit 1

--on, --tf and --event map to instrument, timeframe and event; --all follows every page, and --out events.csv writes CSV. Command reference