Run a definition over history

POST/scripts/{slug}/collect

Runs one version of a definition over a window and stores its events, the same as running it over history in the app. Only the part of the window the definition has not covered yet runs.

Scope	Heavy call	Long poll	CLI
`runs:write`	Yes	No	`chartnaut collect`

Guidance

The call returns once the work is queued. Then poll Summarise events until collecting is empty, and read the events with List events. The next field says the same.
Calling it again for a window that is already covered answers 200 with covered: true and runs nothing, so it is safe to call before every study.
You rarely need it before a study: Create a run of a study runs each definition it reads over the study's window first.
The window is not moved to your plan's history start, unlike a run's. Keep from at or after history_start from Get usage.
held counts parts held back instead of queued, because they cannot run as things stand. A non-zero held means the window will not be fully covered when collecting empties.
The stored events count toward your plan's definition events. At the cap, or when your plan does not include running definitions over history, the answer is 403 plan_limit.
It is a heavy call. On 429 busy, wait for Retry-After (2 seconds) and send it again.

Path parameters

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

Request body

Field	Type	Required	Description
`instrument`	string	Yes	Canonical or short symbol
`timeframe`	string	Yes	One of the timeframes. Upper case is lowered
`window`	object	Yes	Exactly one of `{from, to}`, `{last}` or `{bars}`, as on Create a run
`version`	integer	No	The version to run. Defaults to the latest

Response

202 when runs were queued, 200 when the whole window was already covered:

Field	Type	Description
`definition`	string	The version that runs, as `slug@N`
`instrument`	string	Canonical symbol
`timeframe`	string	Timeframe
`window`	object	`from` and `to` after resolving, ending on a closed bar
`covered`	boolean	`true` when nothing needed to run
`collections`	integer	How many runs were queued for the parts not covered
`held`	integer	How many parts were held back instead of queued
`next`	string	What to call next

Status codes

Status	Code	Meaning
`200`	-	The window was already covered. Nothing ran
`202`	-	Runs were queued for the parts not covered
`400`	`invalid_request`	The slug or body is not valid, or the window is not: it needs exactly one of `from`, `last` or `bars`, and `from` must be before `to`
`400`	`unknown_instrument`	No instrument matches `instrument`
`400`	`unsupported_timeframe`	`timeframe` is not one of the nine
`403`	`plan_limit`	Your plan does not include running definitions over history, or you are at your definition events cap
`404`	`not_found`	You have no definition with that slug, or it has no such `version`
`429`	`busy`	Past your heavy calls at once. `Retry-After: 2`

Example request

curl https://api.chartnaut.com/v1/scripts/bull-bar/collect \
  -H "Authorization: Bearer cn_live_XXXX" \
  -H "Content-Type: application/json" \
  -d '{
    "instrument": "BTC",
    "timeframe": "5m",
    "window": { "last": "1y" }
  }'

Example response

202 Accepted

{
  "definition": "bull-bar@4",
  "instrument": "HYPERLIQUID:BTC",
  "timeframe": "5m",
  "window": {
    "from": "2025-09-26T09:25:00Z",
    "to": "2026-09-26T09:25:00Z"
  },
  "covered": false,
  "collections": 2,
  "held": 0,
  "next": "Poll GET /scripts/bull-bar/events/summary until `collecting` is empty, then read GET /scripts/bull-bar/events."
}

400 Bad Request

{
  "error": {
    "code": "unsupported_timeframe",
    "message": "timeframe must be one of 1m, 5m, 15m, 30m, 1h, 2h, 4h, 1d, 1w."
  }
}

From the CLI

chartnaut collect bull-bar --on BTC --tf 5m --last 1y --wait

With --wait the CLI polls Summarise events every 3 seconds, for up to 20 minutes, and prints the definition's total when nothing is left running. Command reference