Get run results

GET/runs/{run_id}/results

Returns what a succeeded run produced: an indicator's points, a definition's events or a study's result blocks. The shape follows the run's kind.

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

Guidance

Call it only after Get a run says succeeded. A run still going answers 409 run_not_finished, and so does one that failed or was cancelled, since it has no results.
Narrow before you page: outputs for an indicator, event for a definition, and from and to for both. For an indicator, limit applies to each output, and next_cursor is set while any output has more points.
A study answers in one response, capped at 1 MB. Metrics come back inline; other blocks come back with omitted: true until you name them in keys, or ask for all with full=true. If truncated is true, ask for fewer keys at once.
For a large study table, fetch it alone as CSV: keys=<key>&format=csv. Study CSV needs exactly one key, and its data must be a list of rows.
A CSV answer carries no next_cursor. To page indicator or definition CSV, pass the number of rows already read as cursor, and stop at a page shorter than limit.
Indicator and definition results are kept for 7 days, then this answers 410. Run it again, or save what you need before then. Study results do not expire.
A from or to that is not RFC 3339 is ignored, not refused, so check the format when a filter seems to do nothing.

Path parameters

Name	Type	Description
`run_id`	string	A run id, `run_…` or `srun_…`

Query parameters

Name	Type	Required	Default	Description
`outputs`	string	No	All	Indicator only. Comma-separated output ids
`event`	string	No	All	Definition only. One event id
`keys`	string	No	None	Study only. Comma-separated result keys to return in full
`full`	boolean	No	`false`	Study only. `true` returns every block's data, within the 1 MB cap
`from`	string	No	None	Indicator and definition. RFC 3339; keeps points and events at or after it
`to`	string	No	None	Indicator and definition. RFC 3339; keeps points and events before it
`format`	string	No	`json`	`json` or `csv`
`limit`	integer	No	5,000	Indicator and definition. Most 50,000. For an indicator it applies to each output
`cursor`	string	No	None	Indicator and definition. From the previous page's `next_cursor`

Response

200 with a body that follows the run's kind. With format=csv, the answer is text/csv.

Indicator

Field	Type	Description
`kind`	string	`indicator`
`run_id`	string	The run id
`outputs`	array of object	One per output, sorted by id: `id`, `kind` and `points`
`next_cursor`	string or null	Set when any output has more points past this page

Output kind is line, area, baseline, histogram, fill, markers, labels, hlines, ranges or trendlines. Every point has t in Unix seconds, and the rest follows the kind:

Output kind	Point
`line`, `area`, `baseline`	`{t, v}`. `v` is `null` where the script produced no finite value
`histogram`	`{t, v}`, plus `color` when the bar has its own
`fill`	`{t, top, bottom}`
`markers`, `labels`, `hlines`, `ranges`, `trendlines`	`{t, data}`, where `data` is what the script drew. `hlines`, `ranges` and `trendlines` each come back as one output whose id is the kind

As CSV: one row per time with a time column, one column per line, area, baseline or histogram output, and id.top and id.bottom for a fill. Markers, labels, hlines, ranges and trendlines are left out.

Definition

Field	Type	Description
`kind`	string	`definition`
`run_id`	string	The run id
`events`	array of Event	This page of events
`next_cursor`	string or null	Pass it back as `cursor` for the next page

As CSV: the same columns as List events.

Study

Field	Type	Description
`kind`	string	`study`
`run_id`	string	The run id
`results`	array of object	One block per result. Fields below
`truncated`	boolean	`true` when a block you asked for was left out to keep the response under 1 MB

Each block:

Field	Type	Description
`key`	string	The result key
`kind`	string	The block kind, such as `metric` or `table`
`title`	string	The block title, or `""`
`data`	any	The block's data. Always present for `metric`; for other kinds only when named in `keys` or with `full=true`, and only while it fits under 1 MB
`omitted`	boolean	`true` when `data` was left out. Fetch it with `keys`
`size`	integer	The number of rows in the full data, when the data is a list

As CSV: exactly one key in keys, whose data must be a list of rows, with one column per field, sorted. Results and stats says what each block kind holds.

Status codes

Status	Code	Meaning
`200`	-	The results, in the shape of the run's kind
`400`	`invalid_request`	Study CSV without exactly one key, or the key's data is not a list of rows
`404`	`not_found`	You have no run with that id, or study CSV named a key the study does not have
`409`	`run_not_finished`	The run is still `queued` or `running`, or it `failed` or was `cancelled` and has no results
`410`	`not_found`	The indicator or definition run's results are more than 7 days old. Run it again

Example request

curl "https://api.chartnaut.com/v1/runs/run_7k2m9q4xw1ht0bza/results?outputs=ema&limit=3" \
  -H "Authorization: Bearer cn_live_XXXX"

Example response

200 OK

{
  "kind": "indicator",
  "run_id": "run_7k2m9q4xw1ht0bza",
  "outputs": [
    {
      "id": "ema",
      "kind": "line",
      "points": [
        { "t": 1756286700, "v": 110204.75 },
        { "t": 1756287000, "v": 110198.31 },
        { "t": 1756287300, "v": 110187.02 }
      ]
    }
  ],
  "next_cursor": "3"
}

409 Conflict

{
  "error": {
    "code": "run_not_finished",
    "message": "The run is still running. Poll GET /runs/run_7k2m9q4xw1ht0bza?wait=30."
  }
}

From the CLI

chartnaut runs results run_7k2m9q4xw1ht0bza --outputs ema --limit 3

runs results prints a readable view, --json this response and --format csv the CSV, and --all follows every page under one header. Command reference