/api/v1/portfolio/briefs/{brief_id}Read a portfolio brief
Returns the current state and result fields for a portfolio brief.
freeSince 3.152.0
Why use this
Poll a brief job result and obtain the source freshness metadata used for the response.
Common use case
Refresh a briefing view until the brief succeeds or reports a terminal failure.
Parameters
| Name | In | Required | Default | Allowed | Description | Example |
|---|---|---|---|---|---|---|
| brief_id | path | required | — | — | Brief identifier returned by the create operation. | 00000000-0000-4000-8000-000000000005 |
Response schema
| Field | Type | Nullable | Description |
|---|---|---|---|
| status | string | no | `success`. |
| request_id | string | no | Request correlation identifier. |
| timestamp | string | no | Response timestamp. |
| data | object | no | Brief result with exactly `id`, `portfolio_id`, `state`, `content`, `source_version`, `citations`, `reconciled_at`, `authoritative_version`, and `evidence`. `content`, `reconciled_at`, `authoritative_version`, and `evidence` are null until a successful result is reconciled. |
| data.evidence | object | yes | On success, reconciliation evidence with `kind`, `reference`, `verified_at`, and `authoritative_version`. |
| meta | object | no | Source metadata with exactly `source_as_of`, `freshness`, `coverage`, `version`, and `omissions`; `coverage` has `covered_count` and `omitted_count`. |
Sample response
·
- "status": "success"
- "request_id": "00000000-0000-4000-8000-000000000010"
- "timestamp": "2026-09-07T12:00:00Z"
- "data":
- "id": "00000000-0000-4000-8000-000000000005"
- "portfolio_id": "00000000-0000-4000-8000-000000000004"
- "state": "RUNNING"
- "content": null
- "source_version": "source-v1"
- "citations": []
- "reconciled_at": null
- "authoritative_version": null
- "evidence": null
- "meta":
- "source_as_of": "2026-09-07T12:00:00Z"
- "freshness": "FRESH"
- "coverage":
- "version": "source-v1"
- "omissions": []
Errors
| Status | Label | Description |
|---|---|---|
| 200 | Success; returns the brief data and source metadata. | |
| 400 | `INVALID_REQUEST` — the brief identifier is malformed. | |
| 401 | `UNAUTHENTICATED` — authentication is required. | |
| 403 | `FORBIDDEN` — the caller lacks `portfolio:read`. | |
| 404 | `NOT_FOUND` — the brief does not exist or is not visible to the caller. | |
| 429 | `RATE_LIMITED` — retry after the server-provided delay. | |
| 503 | `SERVICE_UNAVAILABLE`, `DEADLINE_EXCEEDED`, `RESULT_GRAPH_INVALID`, or `RESULT_GRAPH_LIMIT_EXCEEDED`. |
Code samples
curl "https://api.finradar.ai/api/v1/portfolio/briefs/00000000-0000-4000-8000-000000000005" \
-H "Authorization: Bearer YOUR_JWT_TOKEN"Generate an API key in /account/credentials to run live queries (literal YOUR_API_KEY placeholder shown until then).