ChartnautDocs

Create a run

POST/runs

Starts a run of a saved script, or of inline source, on one instrument, timeframe and window, and can hold the call until it finishes. Every run is asynchronous: start it, wait on it, then read what it produced.

Scope

Heavy call

Long poll

CLI

runs:write

Yes

wait, up to 30 s

chartnaut run

Guidance

  • The usual loop: create the run with wait at 0, poll Get a run with wait=30 until status is succeeded, failed or cancelled, then read summary for counts or Get run results for everything.

  • wait on this call keeps its heavy place for as long as it holds. Starting several runs with wait set gets 429 busy quickly; waiting on Get a run does not, because it is not a heavy call. wait here is fine for one quick run.

  • Send an Idempotency-Key on every create, and reuse it when you retry. A retry with the same key returns the first run instead of starting a second. Use a new key for each run you mean to start.

  • script takes a ref: my-ema (your script, latest version), my-ema@3 (a version that never changes), jane/orb-breakout@7 (someone else's public indicator or definition, or an unlisted one you added to your library, run without seeing its source) or chartnaut/rsi (a built-in). Search the library gives each script's ref. Pin a version when you compare runs.

  • Inline source runs an indicator or definition without saving anything, which is the fast loop while you write one. Check it with Validate a script first: source with errors gets 422 script_invalid and nothing runs.

  • A study runs only from your own saved studies, by ref. Before it starts, Chartnaut runs each definition it reads over the window wherever that definition has no events yet, for up to 20 minutes; progress.phase shows collecting meanwhile.

  • The window ends on the last closed bar, and warmup is fetched before it without counting in results. Its start moves to where your plan's history or the instrument's data begins. One window holds at most 50,000 bars: 90 days of 5m fits, 90 days of 1m does not.

  • Two kinds of 429 busy: past your heavy calls at once (Retry-After: 2), or your API runs queued or running are full (Retry-After: 15). Your account can have its runs at once plus 4 API runs queued or running. Wait for Retry-After and retry with the same Idempotency-Key.

  • Indicator and definition results are kept for 7 days. Study results do not expire.

Headers

Name

Required

Description

Idempotency-Key

No

Up to 128 characters. A retry with the same key returns the first run. See Idempotency

Request body

Field

Type

Required

Description

script

string

One of script and source

A saved ref: slug, slug@N, author/slug[@N] or chartnaut/slug[@N]

source

object

One of script and source

Inline code for an indicator or definition, saved nowhere: kind and files, as on Validate a script. Inline studies are refused

instrument

string

Yes

Canonical or short symbol

timeframe

string

Yes

One of the timeframes. Upper case is lowered

window

object

Yes

Fields below

settings

object

No

Setting values keyed by setting id. Anything left out uses the script's default

study

object

No

Study runs only. event_filter: an object of payload values; the study keeps only events whose payload matches them

wait

integer

No

Seconds to hold the call until the run finishes, 0 to 30. Default 0. Values outside the range are clamped

label

string

No

Free text, returned on the run

window object

Send exactly one of from, last and bars.

Field

Type

Description

from

string

RFC 3339 start

last

string

A span back from to: a number and d (days), w (weeks), m (months of 30 days) or y (years of 365 days), such as 90d

bars

integer

This many bars of the run's timeframe back from to, counted in clock time

to

string

RFC 3339 end, with any of the three. Defaults to now; a later time is cut to now

Response

Returns a Run: 200 when it finished within wait, 202 while it is still queued or running.

Status codes

Status

Code

Meaning

200

-

The run finished within wait

202

-

The run is queued or running. Poll Get a run

400

invalid_request

The body is not JSON; both or neither of script and source; the ref, window or source is not valid; the window holds more than 50,000 bars; source is a study; script is someone else's study; or the Idempotency-Key is too long

400

unknown_instrument

instrument is missing or matches no instrument, or a short symbol matches several

400

unsupported_timeframe

timeframe is not one of the nine

400

out_of_coverage

The window ends before your plan's history, or the instrument's data, begins

404

not_found

No script by that ref you can run, or no such version

409

conflict

One of your studies shares the slug with an indicator or definition. Runs cannot choose between them

422

script_invalid

Inline source has errors. diagnostics lists them; nothing ran

429

busy

Past your heavy calls at once (Retry-After: 2), or your API runs queued or running are full (Retry-After: 15)

PreviousThe Event objectNextList runs