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

# Responses and result types

> One envelope for analyze, proposals and trade checks, and a fixed set of typed result blocks.

`POST /v1/analyze`, `POST /v1/proposals` (and `GET /v1/proposals/{id}`) and `POST /v1/trades/check` all answer with the same envelope.

```json theme={null}
{ "object": "analysis | proposal | trade_check",
  "answer": "plain English; every number in it comes from results",
  "understood": { "...": "what Abacus Labs read from the request" },
  "results": [ { "type": "tax", "data": { } }, { "type": "option", "data": { } } ],
  "warnings": [ "..." ],
  "ids": { "account_id": "...", "snapshot_id": "...", "proposal_id": "...", "decision_id": "..." },
  "provenance": { "risk_model": { }, "prices": "...", "engine": { } },
  "effort": "standard",
  "credits_charged": 15 }
```

| Field | Meaning |
| - | - |
| `object` | `analysis`, `proposal` or `trade_check`. |
| `answer` | Text to show the person. Every number in it comes from `results`. |
| `understood` | What Abacus Labs read. Analyze: the question, the analyses it ran, the benchmark. Proposals: the policy it solved. Trade checks: the number of trades. |
| `results` | Typed blocks: `{type, data}`. Read numbers here, not from `answer`. |
| `warnings` | Things the person should know: missing prices, estimated tax rates, the reach of wash-sale checks. |
| `ids` | `account_id`, `snapshot_id` (the exact holdings used), `decision_id` (the audit record), and `proposal_id` or `saved_account_id` when they apply. |
| `provenance` | The risk model version and data end, the price source, and for proposals the engine that ran. |
| `effort` | Analyze and proposals: the effort used (`quick`, `standard` or `deep`). |
| `credits_charged` | The credits the call cost. A `202` proposal also has `credits_held`. See [Credits](https://docs.abacuslabs.ai/credits.md). |

Proposals also carry `id`, `status` and `outcome`. Trade checks carry `status`. Analyze carries `as_of`, `usage` and, for an account sent inline, `account_expires_at`.

## Result types

Which blocks come back depends on the request. The fields of a block type never change.

| `type` | From | What `data` holds |
| - | - | - |
| `holdings` | analyze | Value, cash, and each position: quantity, price and its time, value, weight, sector, unrealized gain, cost basis. |
| `exposures` | analyze | Weights by sector, industry, region, asset class or issuer (ETFs looked through), the benchmark's weights, and the active difference. Concentration (`hhi`, `effective_positions`). |
| `lookthrough` | analyze | Company-level exposure counting what the funds hold. `companies`: `[{symbol, total, direct, via_funds: {FUND: weight}}]`, largest first; `n_companies`; `top10_weight`; `held_in_more_than_one_place`; `fund_overlap`: `[{funds: [A, B], holdings_overlap, account_weight_shared}]`; `coverage`: `{looked_through, opaque_funds, invested}`; `focus` when the question names one company. Definitions: a company's `total` = its `direct` weight + Σ over funds (the fund's weight in the account × the company's weight in the fund); `top10_weight` = the ten largest `total`s; `held_in_more_than_one_place` = the summed `total` of companies held in two or more places (directly and/or in funds); `holdings_overlap` = Σ min(weight in fund A, weight in fund B) over shared companies; `account_weight_shared` = the same with each fund scaled by its weight in the account; `looked_through` = the account weight in funds with holdings data; `opaque_funds` = funds without it, counted as single positions. Share classes (GOOG / GOOGL) are one company, listed in `share_classes`. All weights are fractions of the account. |
| `factor_exposures` | analyze | Market beta, 13 style factors (value, momentum, size, ...) with a one-line reading each, and industry bets. |
| `risk` | analyze | Volatility, beta, value at risk, and which holdings carry the risk. |
| `tracking_error` | analyze | Tracking error against the benchmark, and where it comes from. |
| `tax` | analyze | Unrealized gains and losses by term, `harvest_candidates` (lot, loss, term, a replacement that tracks a different index), and `wash_windows`. |
| `drift` | analyze | Distance from the account's target mix. |
| `option` | proposals, trade checks | One trade list and its consequences. See [Proposals](https://docs.abacuslabs.ai/concepts/proposals.md#the-option-block). |
| `violations` | proposals, trade checks | `[{rule, symbol, detail, amounts?}]`: each rule your trades broke. |
| `infeasible` | proposals | Why no trade list meets every rule: each variant Abacus Labs tried and the rules it could not meet. |
| `benchmark` | proposals | A benchmark definition, when the goal only asked for one. |

## Units

| Kind | Unit |
| - | - |
| Weights, rates, volatility, tracking error, turnover | Fractions: `0.10` is 10%. |
| Money, cost basis, gains, tax | Dollars. |
| Quantities | Shares. |
| `gap_bp` | Basis points of the account value. |
| Dates | `YYYY-MM-DD`. Times are ISO 8601. |

Account ids and lot ids come back exactly as you sent them. Symbols come back upper-cased, with share classes as `BRK-B`.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.