> ## 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.

# Analyze

> Ask about an account in plain English. Abacus Labs runs the analyses it needs and answers with typed results.

```bash theme={null}
curl -s https://api.abacuslabs.ai/v1/analyze \
  -H "Authorization: Bearer $ABACUS_API_KEY" -H "Content-Type: application/json" \
  -d '{"account": {"id": "acct_demo_tech"}, "question": "What do I own, where am I concentrated, and where can I save on taxes?"}'
```

`200 OK`, about 15 seconds, 15 credits. This question ran four analyses (trimmed):

```json theme={null}
{ "object": "analysis", "answer": "...",
  "understood": { "analyses": [ { "component": "holdings", "params": {} }, { "component": "exposures", "params": { "group_by": "sector", "top": 5 } },
                                { "component": "lookthrough", "params": { "top": 10, "symbol": null } }, { "component": "tax", "params": { "rates": null } } ], ... },
  "results": [ { "type": "holdings", "data": { ... } }, { "type": "exposures", "data": { ... } }, { "type": "lookthrough", "data": { ... } }, { "type": "tax", "data": { ... } } ],
  "usage": { "input_tokens": 8716, "output_tokens": 632, "seconds": 14.47 }, "credits_charged": 15 }
```

The whole envelope is described in [Responses and result types](https://docs.abacuslabs.ai/concepts/results.md).

| Field | Required | Meaning |
| - | - | - |
| `question` | yes | Plain English. Missing: `422 invalid_request`, `param: "question"`. |
| `account`, `accounts` or `snapshot_id` | one of them | An inline account, `{"id": "..."}` of a saved account, several accounts (analysed as one household), or a `snapshot_id` from an earlier answer. See [Accounts and lots](https://docs.abacuslabs.ai/concepts/accounts.md). |
| `benchmark` | no | What risk and exposures compare against. Default SPY. Any form in [Benchmark](https://docs.abacuslabs.ai/concepts/policy.md#benchmark) except `current`. |
| `save` | no | `true` saves an inline account and returns `ids.saved_account_id`. One account at a time. |
| `effort` | no | `quick`, `standard` (default) or `deep`: at most 2, 6 or 10 analyses. 5, 15 or 40 credits. |
| `max_credits` | no | Refuse the call (`402 max_credits_exceeded`, nothing charged) if it would cost more credits than this. See [Credits](https://docs.abacuslabs.ai/credits.md). |

Abacus Labs picks the analyses the question needs, up to the `effort` limit, and runs them: `holdings`, `exposures`, `lookthrough`, `factor_exposures`, `risk`, `tracking_error`, `tax`, `drift`. Each comes back as a block in `results` ([result types](https://docs.abacuslabs.ai/concepts/results.md#result-types)).

| In the answer | Meaning |
| - | - |
| `understood.analyses` | The analyses Abacus Labs ran, with their parameters. |
| `understood.grounding` | `ok: true` when every number in `answer` came from a result. Any that did not is listed in `unmatched` and named in `warnings`. |
| `understood.model` | The LLM that chose the analyses and wrote the answer. |
| `usage` | Tokens and seconds. |
| `account_expires_at` | For an inline account not saved: when Abacus Labs forgets it (24 hours). |

The analyses chosen, and the wording of `answer`, can differ between two calls with the same question. The numbers in `results` for the same account and prices do not.

Questions about fund overlap, hidden concentration or total exposure to one company ("how much NVDA do I really own, counting my ETFs?") get a `lookthrough` block: each company's weight directly and through each fund.

```bash theme={null}
curl -s https://api.abacuslabs.ai/v1/analyze \
  -H "Authorization: Bearer $ABACUS_API_KEY" -H "Content-Type: application/json" \
  -d '{"account": {"id": "lt_demo", "cash": 1000, "positions": [{"symbol": "SPY", "quantity": 100}, {"symbol": "QQQ", "quantity": 100}, {"symbol": "NVDA", "quantity": 500}]},
       "question": "How much NVDA do I really own counting my ETFs, and how much do my funds overlap?"}'
```

The `lookthrough` block (trimmed):

```json theme={null}
{ "type": "lookthrough", "data": {
    "focus": { "symbol": "NVDA", "total": 0.4011, "direct": 0.3605, "via_funds": { "SPY": 0.0203, "QQQ": 0.0203 } },
    "companies": [ { "symbol": "NVDA", "total": 0.4011, ... }, { "symbol": "AAPL", "total": 0.0539, "direct": 0.0, "via_funds": { "SPY": 0.027, "QQQ": 0.0269 } }, ... ],
    "n_companies": 509, "top10_weight": 0.6398, "held_in_more_than_one_place": 0.8249,
    "fund_overlap": [ { "funds": ["QQQ", "SPY"], "holdings_overlap": 0.5249, "account_weight_shared": 0.1751 } ],
    "coverage": { "looked_through": 0.635, "opaque_funds": [], "invested": 0.9956 } } }
```

This account is sent inline, so it counts as one [portfolio](https://docs.abacuslabs.ai/credits.md#portfolios) this month. The `warnings` say its cost basis is unknown (no lots were sent). The fields are defined in [Result types](https://docs.abacuslabs.ai/concepts/results.md#result-types).

Analyze is read-only. It never proposes trades. To change something, send a goal to [Proposals](https://docs.abacuslabs.ai/concepts/proposals.md).

> [!NOTE]
>
> Analyze needs an LLM on the server. Without one it answers `503 llm_unavailable`.

Reference: [Analyze an account](https://docs.abacuslabs.ai/api-reference/analyze/analyze-an-account.md).


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