# Ask the analyst

`POST https://api.getchord.xyz/v1/ask`

Source: https://getchord.xyz/docs/api-reference/operations/ask/

Chord's analyst over the Arc index and the router — 40+ tools (trending, a token's flow, holders and risk, support and resistance, top traders on a token, a wallet's PnL and trades, largest prints, launches, depth, a bridge quote, read-only SQL over the index). Returns the answer, source links, an optional route card, tables and charts the analysis produced, and a report when one was built. It analyses: a plan (zones, tranches, an exit, the level where the idea is wrong) is written only when the question asks for one, and is illustrative, with its assumptions stated.

**Layout**: `text` is the whole answer on its own. The optional fields `shape`, `parts`, `details`, `followUpKinds` and `focus` say how the chat lays it out: `parts` is the same answer in order, with the tables and charts of `viz` placed inside the text (in `text` a placed table is written out as a Markdown table), and `details` is further depth the chat folds, which `text` does not repeat. A client that ignores them loses nothing of the answer.

**Auth**: a developer API key (`X-API-Key`) or a Google session bearer. Metered per key per day against the deployment's token budget; 8 questions a minute per caller.

**Agents**: send `"stream": false` for one JSON answer (5–40 s). Without it the response is `text/event-stream` with `status` events (which tool is running), one `answer` event, then `done`.

## Request body (JSON)

| Field | Required | Type | Description |
| --- | --- | --- | --- |
| `question` | yes | string | May be empty when `images` is set. |
| `stream` | no | boolean | false = one JSON response instead of SSE. |
| `history` | no | object[] | Up to 12 prior turns. |
| `wallet` | no | string | The caller's wallet, so "my PnL" resolves. |
| `mode` | no | `quick` · `deep` | How long an answer to write. `quick`: the shortest form (the verdict, its claim, at most three rows of evidence, 120 words at most), faster. `deep`: a judgement or an explanation comes back as a full research note (`shape: "report"`), any other answer with a longer folded `details`. Omitted: the length the question calls for. Any other value is ignored. |
| `images` | no | string[] | Up to 4 ids from `POST /v1/ask/image` (your own, 30 days). The analyst reads each image — chart, positions, a swap or wallet screenshot — before it answers, and can zoom into one. |

```json
{
  "question": "What is moving on Arc right now, and is ARGUS still being bought by real wallets?",
  "stream": false
}
```

## Response 200

With `stream: false`: the whole answer. Otherwise `text/event-stream`.

- **400**: Invalid parameters — `error` names the check that failed (`INVALID_PARAMS`, `BAD_ADDRESS`, `BAD_LIMIT`, `BAD_HOURS`, …).
- **401**: Missing or unknown credential (`UNAUTHORIZED`).
- **429**: Over the per-minute limit (`RATE_LIMIT_EXCEEDED`). Read `X-RateLimit-Reset` and back off.
- **503**: The lane behind this endpoint is not ready or not enabled here (`NOT_READY`, `CHAIN_NOT_ENABLED`, `NOT_ENABLED`, `*_UNAVAILABLE`). Retry later; do not treat it as an empty answer.