> ## Documentation Index
> Fetch the complete documentation index at: https://docs.askfutures.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Developer concepts

> The handful of objects and patterns you need to drive AskFutures from an MCP client: sessions, strategy artifacts, async operations, status fields, and deep links.

The MCP server exposes the same AskFutures you use in chat, just as tools. If
you understand five things — **sessions**, **strategy artifacts**,
**operations**, **status fields**, and **optimization batches** — every tool
falls into place.

<Note>
  These are the same ideas as the in-app
  [sessions, versions & artifacts](/concepts/sessions-versions-artifacts)
  concept page, named the way the tools name them. If you have only ever used
  the web app, start there, then come back.
</Note>

## The mental model

```mermaid theme={null}
flowchart LR
  S["Session<br/>session_id"] --> A1["Strategy artifact<br/>artifact_id"]
  S --> A2["Strategy artifact<br/>artifact_id"]
  A1 --> O["Operation<br/>operation_id<br/>(create / update)"]
  A1 --> B["Backtest<br/>backtestStatus"]
  A1 --> OPT["Optimization batch<br/>optimization_id"]
```

## Sessions

A **session** is a workspace. It owns your strategies, their versions, the chat
history, and a task list. Almost every tool takes a `session_id`, so the first
call in any flow is `create_session` (or `list_sessions` to reuse one).

* Created by `create_session`, returns a `session_id`.
* Listed by `list_sessions` (filter `active` | `archived` | `all`, paginate
  with `cursor`).
* Fetched by `get_session`.
* Sessions are owned by the authenticated user — you only ever see your own.

## Strategy artifacts

A **strategy artifact** is one saved strategy, identified by an `artifact_id`.
Every edit produces a new versioned artifact, so a session typically holds a
small family of them.

* `list_strategies` returns a summary of every strategy artifact in a session —
  including the **canonical parameters** you need before you can optimize.
* `inspect_strategy` returns one artifact in full: entry rules, exit rules,
  exit conditions, parameters, and its backtest status.

A summarized artifact carries the fields you act on:

<ResponseField name="artifact_id" type="string">
  The handle you pass to backtest, update, optimize, inspect, and delete tools.
</ResponseField>

<ResponseField name="version" type="number">
  Which version in the lineage this artifact is. Edits bump the version.
</ResponseField>

<ResponseField name="lifecycle_status" type="string">
  `creating` while an operation is in flight, otherwise the artifact is ready to
  use.
</ResponseField>

<ResponseField name="ticker" type="string">
  The traded symbol, e.g. `MNQ`.
</ResponseField>

<ResponseField name="backtestStatus" type="string">
  `not_tested`, `passed`, or `failed`. See [backtest status](#backtest-status).
</ResponseField>

<ResponseField name="canonicalParameters" type="array">
  The tunable parameters of the strategy. Each has a `key`, `label`, `value`,
  and `category`. The `key` is what you feed to `setup_optimization`.
</ResponseField>

<ResponseField name="backtestResults" type="object">
  Present once a backtest has passed: `tradeCount`, `totalPnl`, `winRate`,
  `maxDrawdown`, `sharpeRatio`. See the
  [metrics glossary](/reference/metrics-glossary).
</ResponseField>

## Operations and the `operation_id`

Building and editing a strategy is **asynchronous**. `create_strategy` and
`update_strategy` do not return a finished strategy — they queue the work and
hand back an `operation_id`. You then poll for completion.

<Warning>
  Never treat a strategy as ready the moment `create_strategy` returns. The
  artifact is still being built. Always run `wait_for_completion` against the
  `operation_id` first.
</Warning>

An operation resolves to one of three terminal states:

| Operation status | Meaning                                                                                           |
| ---------------- | ------------------------------------------------------------------------------------------------- |
| `succeeded`      | The strategy artifact is built and ready. The result carries the finished strategy summary.       |
| `failed`         | The strategy could not be built (ambiguous or unsupported request).                               |
| `timed_out`      | The operation ran past `wait_for_completion`'s window. It keeps running server-side — poll again. |

A `timed_out` result from `wait_for_completion` is **not** a failure. The work
continues on the server; you just call `wait_for_completion` again with the same
`operation_id`. The maximum per-call wait is 300 seconds (default 45).

## Backtest status

A backtest is also asynchronous, but it is tracked **on the artifact**, not by
an operation id. You poll by re-reading the artifact's `backtestStatus`.

| `backtestStatus` | Meaning                                                        |
| ---------------- | -------------------------------------------------------------- |
| `not_tested`     | No backtest has run yet (e.g. created with `backtest=false`).  |
| `passed`         | The backtest finished; `backtestResults` are populated.        |
| `failed`         | The backtest could not complete; `backtestError` explains why. |

`create_strategy` runs a backtest by default, so most strategies arrive already
`passed`. Use `backtest_existing_strategy` only to (re-)test a strategy that is
`not_tested` or `failed`, or when you explicitly want a fresh run.

<Info>
  Backtests are hypothetical, simulated, minute-level results, net of modeled
  slippage and commission — not advice. Past performance does not guarantee
  future results. Always test before you trade. See
  [Is the backtest real?](/concepts/is-the-backtest-real)
</Info>

## Optimization batches

An **optimization batch** is one parameter sweep over a backtested strategy,
identified by an `optimization_id`. It is a two-step, asynchronous flow:

<Steps>
  <Step title="Configure">
    `setup_optimization` records which parameters to sweep (each with a `min`,
    `max`, and `step`) and returns an `optimization_id`. Nothing runs yet.
  </Step>

  <Step title="Run">
    `run_optimization` promotes that batch to running. It queues one backtest
    per parameter combination; results stream back and land on the strategy
    artifact's `optimizationBatches`.
  </Step>

  <Step title="Wait">
    `wait_for_completion` with `task='optimization'` polls the batch by
    `optimization_id`.
  </Step>
</Steps>

A completed batch reports `total_combinations`, `failed_count`, and a
`best_result`. A batch status is `completed` or `failed`.

<Note>
  A session runs **one** sweep at a time. That single running sweep is what
  `cancel_task` with `task='optimization'` resolves automatically — it stops
  between combinations and keeps the partial results.
</Note>

## The three task types

Three tools share a `task` discriminator — `wait_for_completion` and
`cancel_task` both use it, and it tells you which id each flow is keyed on:

| `task`         | Produced by                                         | Poll / cancel with                |
| -------------- | --------------------------------------------------- | --------------------------------- |
| `strategy_op`  | `create_strategy`, `update_strategy`                | `operation_id`                    |
| `backtest`     | `backtest_existing_strategy` (or the auto-backtest) | `artifact_id`                     |
| `optimization` | `run_optimization`                                  | `artifact_id` + `optimization_id` |

## Deep links: `app_url`

Most tools that touch a session return an `app_url` — a deep link straight to
that session in the web app, e.g. `https://app.askfutures.com/sessions/{session_id}`.
Surface it to your user so they can open the strategy card, the **Strategy Flow**
chart, and the full trade list in the browser.

<Tip>
  Treat `app_url` as the "show me" handoff. Automate the build over MCP, then
  drop the `app_url` in your reply so the trader can inspect, compare versions,
  and export trades in the app.
</Tip>

## Next steps

<CardGroup cols={2}>
  <Card title="MCP tools" icon="toolbox" href="/developers/tools">
    The full table of every tool, its inputs, and what it returns.
  </Card>

  <Card title="Recipes" icon="book-open" href="/developers/recipes">
    Worked end-to-end flows: build & backtest, sweep, cancel, look up specs.
  </Card>

  <Card title="Connect the MCP server" icon="plug" href="/developers/quickstart">
    Add AskFutures to Claude, Cursor, or Codex.
  </Card>

  <Card title="Sessions, versions & artifacts" icon="layer-group" href="/concepts/sessions-versions-artifacts">
    The same model from the trader's point of view.
  </Card>
</CardGroup>