Create a Forward Insight

POST/insights

Puts a finished study run on your charts as a Forward Insight: click one of the definition's events and a card shows what happened after events like it. Call it once the study publishes pin_cell and a run of it has succeeded.

Scope	Heavy call	Long poll	CLI
`scripts:write`	Yes	No	`chartnaut insights create`

Guidance

The in-app Attach to chart wizard has an agent write pin_cell for you. This endpoint never does, and never spends AI credits: you, or your own AI, write pin_cell into the study first. Forward Insights is the contract.
The usual flow: save the study with pin_cell using Save a script version, start it with Create a run, wait on Get a run, then read keys=pin_cell from Get run results and check there is one row per combination of its indexedBy dimensions. Then call this with dry_run: true, look at the card, and call it again without.
dry_run runs every check and compiles the preview card for a sample event, then saves nothing. It skips only the name check that replace: false makes.
The insight goes on the definition the study reads. When it reads only one of yours, that one is used. When it reads several, name one in definition, or you get 400 with the choices. Forward Insights go on your own definitions only: to use someone else's, save a copy, have the study declare the copy, and run it again.
It shows on your charts of that definition, on the run's instrument and timeframe, with the definition profile the run used. Run the study on the instrument and timeframe you trade.
To change the numbers, change the study, run it again and call this with the same name. replace defaults to true, so the new insight archives the old one on that definition. Send replace: false to be refused with 409 conflict instead.
A 422 script_invalid answer is a change the study needs. details.fix, when present, is the code to add, and details.docs_url links the contract. Fix the study, save it, run it again, and retry with the new run: a run is never re-checked against a newer version.

Request body

Field	Type	Required	Description
`run`	string	Yes	A succeeded study run: `run_…` from the API or `srun_…` from the app
`name`	string	Yes	What you see on the chart and in the definition's Forward Insights tab. At most 120 characters
`definition`	string	No	Your own definition's slug. Needed only when the study reads more than one of your definitions
`description`	string	No	What the card answers. At most 2,000 characters
`replace`	boolean	No	Default `true`: archive your insight with the same `name` on that definition. `false` refuses instead
`dry_run`	boolean	No	Default `false`. `true` checks everything and returns the preview without saving

Response

201 with the new Forward Insight and a preview. A dry run answers 200 with the fields below and saves nothing.

Field	Type	Description
`dry_run`	boolean	Dry run only. Always `true`
`definition`	string	Dry run only. The definition the insight would go on
`scope_dimensions`	array of string	Dry run only. `pin_cell`'s `indexedBy`: the dimensions the card is broken down by. `[]` for one global card
`preview.card`	object or null	The card as the chart would show it for `preview.sample_event`: a `heading`, its `lines` and `groups`, and the `methodology` with the sample
`preview.sample_event`	object or null	The scope values of the event the card was compiled for, such as `{"direction": "long"}`

Status codes

Status	Code	Meaning
`201`	-	The Forward Insight was saved and is on your charts
`200`	-	Dry run: every check passed. Nothing was saved
`400`	`invalid_request`	The body is not JSON; `run` or `name` is missing; `name` or `description` is too long; `run` is an indicator or definition run; the study reads several of your definitions and `definition` is missing (the message lists them); the run did not read `definition` (the message lists what it read); or Chartnaut refused the insight, and the message says why
`403`	`forbidden`	`definition`, or every definition the study reads, is someone else's
`403`	`plan_limit`	A limit of your plan. Do not retry
`404`	`not_found`	No run with that id on your account
`409`	`run_not_finished`	The run has not succeeded. `details.status` is its status
`409`	`conflict`	`replace` is `false` and you already have an insight with that `name` on the definition
`422`	`script_invalid`	The study does not meet the `pin_cell` contract, or declares no definition. `details` has `docs_topic`, `docs_url` and, for some causes, `fix`
`429`	`busy`	Past your heavy calls at once. Retry after `Retry-After`

Example request

Dry run first:

curl https://api.chartnaut.com/v1/insights \
  -H "Authorization: Bearer cn_live_XXXX" \
  -H "Content-Type: application/json" \
  -d '{
    "run": "run_4d8s1k7fq2mxv0ce",
    "name": "Breakout follow-through by direction",
    "description": "How often a BTC opening range break reached 1R before the stop, long and short.",
    "dry_run": true
  }'

Then the same body without dry_run to save it.

Example response

200 OK

{
  "dry_run": true,
  "definition": "orb-breakout",
  "scope_dimensions": ["direction"],
  "preview": {
    "card": {
      "heading": "Breakout follow-through by direction",
      "lines": [],
      "groups": [
        {
          "heading": "Long breaks",
          "dimensions": [
            { "id": "direction", "title": "Direction", "description": "Side of the range the break closed on.", "value": "long" }
          ],
          "lines": [
            { "label": "Reached 1R first", "value": "58%", "sample": "n=61", "baseline": "53%", "delta": "+5", "deltaDirection": "up" }
          ],
          "verdict": { "status": "pos", "label": "Above baseline" }
        }
      ],
      "methodology": {
        "scanWindow": "2024-09-27 to 2026-09-26",
        "definitions": [],
        "sample": "118 events"
      },
      "fullResults": { "runId": 5120, "studyId": 311, "versionId": 1874, "resultKeys": ["pin_cell"] }
    },
    "sample_event": { "direction": "long" }
  }
}

201 Created

{
  "id": "ins_842",
  "name": "Breakout follow-through by direction",
  "description": "How often a BTC opening range break reached 1R before the stop, long and short.",
  "definition": "orb-breakout",
  "study": "orb-follow-through",
  "study_version": 4,
  "instrument": "BTC",
  "timeframe": "1h",
  "profile": null,
  "window": {
    "from": "2024-09-27T00:00:00Z",
    "to": "2026-09-26T23:00:00Z"
  },
  "scope_dimensions": ["direction"],
  "app_url": "https://terminal.chartnaut.com/morpheus/studies/311/runs/5120",
  "created_at": "2026-09-27T10:14:52.381207Z",
  "updated_at": "2026-09-27T10:14:52.381207Z",
  "preview": {
    "card": { "heading": "Breakout follow-through by direction", "lines": [], "groups": [] },
    "sample_event": { "direction": "long" }
  }
}

422 Unprocessable Entity

{
  "error": {
    "code": "script_invalid",
    "message": "This study version does not declare pin_cell, the result a Forward Insight shows. Add it, save the study, run it again and create the insight from the new run.",
    "details": {
      "docs_topic": "chart-pins-overview",
      "docs_url": "https://docs.chartnaut.com/scripting/chart-pins-overview/",
      "fix": "results.declare({ id: \"pin_cell\", kind: \"popover_layout\", indexedBy: [<scope dimensions>] }) and, in onFinish, ctx.publish(\"pin_cell\", cells.map(c => ctx.popoverLayout.cell({ dims, n, blocks })))"
    }
  }
}

From the CLI

chartnaut insights create srun_665 --name "Median move by direction and gap" --dry-run
chartnaut insights create srun_665 --name "Median move by direction and gap"

--dry-run prints the preview card and saves nothing; without it the insight is saved and printed with the card. --definition, --description and --no-replace set the other fields, and --json prints this response. A refusal prints its fix: and docs: lines. Command reference