# Brief Review a stock thesis today and its conditional future case > Section: API reference > Last updated: **2026-10-24**. > API version: **v1 (Latest)**. OpenAPI publication: **2026-11-08**. ## `GET /v1/brief` Analyst views, catalysts, risks, and supporting sources for a company. Read a combined view of analyst theses, source comparison, recent changes, and available measured outcomes. Missing evidence and coverage gaps remain explicit. Lifecycle: **stable**. Availability: **released**. Account-based authentication: **Bearer API key**. Accountless alternative: the [x402 catalog](/v1/research) exposes POST /v1/research/{tool} and native MCP at /v1/research/mcp. Fourteen data tools cost 0.02 USDC per call on Base; built-in comparison costs 0.50 USDC and search costs 1.50 USDC. GET /v1/brief/{ticker} still supports the 0.02-USDC overview. Check free /v1/tickers coverage first, then follow the [x402 quickstart](/agent-quickstart.md#pay-per-call-with-x402). Bearer examples below apply to account-based access. ## Examples Requires a Bearer API key. Replace `` in each request with your developer key. Uses an included request or $0.02 in enabled prepaid credit for a successful new billable read. Response excerpts below illustrate the shape only; placeholders and empty arrays are not live research or proof of coverage. Actual responses include additional fields. ### Get a company's research brief Read a compact overview of attributed analyst views, supporting reasons, risks, and source citations for one company. ```bash curl --request GET \ --url 'https://beliefstate.ai/v1/brief?ticker=NVDA' \ --header 'Authorization: Bearer ' ``` Response excerpt: ```json { "view": "overview", "views": [ { "belief_id": "", "summary": "" } ] } ``` Choose a ticker from /v1/tickers. Use detail=full for the larger research response, including available claims, conditions, and outcomes. Coverage and missing evidence remain explicit. ## Request ```bash curl --request GET \ --url 'https://beliefstate.ai/v1/brief?max_results=10' \ --header 'Authorization: Bearer ' ``` ```javascript const options = { method: "GET", headers: {"Authorization":"Bearer "} }; fetch("https://beliefstate.ai/v1/brief?max_results=10", options) .then((response) => response.json()) .then((data) => console.log(data)); ``` ```python import requests url = "https://beliefstate.ai/v1/brief?max_results=10" headers = {"Authorization":"Bearer "} response = requests.get(url, headers=headers) print(response.text) ``` ## Parameters | Name | In | Type | Required | Description | | --- | --- | --- | --- | --- | | `X-Request-ID` | header | `string` | no | Stable ID for an idempotent retry. Reuse it only for the same logical request. | | `ticker` | query | `string` | no | Ticker for the requested company. Check released coverage before querying. | | `refresh_market_data` | query | `boolean` | no | Filter by refresh_market_data. | | `as_of` | query | `string` | no | RFC 3339 point in time cutoff. Future values are clamped. | | `max_results` | query | `integer` | no | Maximum detailed theses to return, from 1 to 20. | | `detail` | query | `enum` | no | Filter by detail. | | `exchange` | query | `string` | no | Filter by exchange. | | `entity_id` | query | `string` | no | Filter by entity_id. | | `cursor` | query | `string` | no | Filter by cursor. | | `issuer_document_id` | query | `string` | no | Filter by issuer_document_id. | | `issuer_query` | query | `string` | no | Filter by issuer_query. | | `issuer_match_offset` | query | `integer` | no | Filter by issuer_match_offset. | | `snapshot_only` | query | `true` | no | Filter by snapshot_only. | ## Response includes - Active and historical theses with attributed people - Claims, reasons, disagreements, catalysts, risks, and invalidations - Measured outcomes, citations, warnings, and explicit unknowns ## Response schemas ### 200 Successful read only response (response variant 1 of 2) - `view` ("issuer_evidence", required) - `version` ("issuer-evidence-v1", required) - `billing_notice` (object) - `code` ("signup_credit_exhausted", required) - `message` (string, required) - `remaining_requests` (0, required) - `add_credits_url` (string, required) - `plans_url` (string, required) - `as_of` (string, required) - `ticker` (string, required) - `security_id` (string, required) - `observation` (object, required) - `id` (string, required) - `content_hash` (string, required) - `observed_at` (string, required) - `documents` (object[], required) - `document_id` (string, required) - `source_url` (string, required) - `name` (string, required) - `form` (string, required) - `filing_date` (string, required) - `accession_number` (string, required) - `capture_status` (complete | unavailable, required) - `content_hash` (string, required) - `byte_length` (integer, required) - `observed_at` (string, required) - `snapshot_text_truncated` (boolean, required) - `response_url_status` (matched | unknown, required) - `query` (string | null, required) - `selected_document_id` (string, required) - `normalization_version` ("sec-filing-text-v1", required) - `normalized_content_hash` (string, required) - `normalized_text_length` (integer, required) - `match_basis` ("literal_phrase", required) - `passages` (object[], required) - `start` (integer, required) - `end` (integer, required) - `match_start` (integer, required) - `match_end` (integer, required) - `text` (string, required) - `source_url` (string, required) - `pagination` (object, required) - `returned` (integer, required) - `next_match_offset` (integer, required) - `coverage` (object, required) - `available_documents` (integer, required) - `retained_documents` (integer, required) - `listed_filings` (integer, required) - `limitations` (string[], required) ### 200 Successful read only response (response variant 2 of 2) - `view` ("company_snapshot", required) - `access` ("free", required) - `next_earnings` (object) - `fiscal_year` (integer, required) - `fiscal_quarter` (integer, required) - `release_date` (string, required) - `release_session` (string, required) - `webcast_at` (string, required) - `filed_on` (string, required) - `accepted_at` (string, required) - `observed_at` (string, required) - `available_at` (string, required) - `url` (string, required) - `as_of` (string, required) - `listing` (object, required) - `id` (string, required) - `ticker` (string, required) - `name` (string, required) - `exchange` (string, required) - `currency` (string | null, required) - `listing_reference` (object) - `selector` (string, required) - `ticker` (string, required) - `exchange` (string, required) - `country` (string, required) - `currency` (string, required) - `isin` (string, required) - `name` (string, required) - `instrument` (ordinary_share | depositary_share | preferred_share, required) - `source_url` (string, required) - `investor_research_released` (boolean, required) - `issuer_guidance` (object) - `text` (string, required) - `source_url` (string, required) - `issuer` (object, required) - `cik` (string, required) - `name` (string, required) - `observed_at` (string, required) - `source_url` (string, required) - `industry` (object) - `sic` (string, required) - `name` (string, required) - `adjusted_close` (object, required) - `value` (number, required) - `session_date` (string, required) - `observed_at` (string, required) - `source` (string, required) - `change_from_previous_retained_close` (object) - `session_date` (string, required) - `percent` (number, required) - `financials` (object, required) - `revenue` (number, required) - `revenue_label` (string) - `reported_revenue_increment` (integer) - `revenue_basis` (total_revenue | net_sales | customer_contract_revenue | total_income, required) - `unit` (string, required) - `period_start` (string, required) - `period_end` (string, required) - `revenue_growth_pct` (number | null, required) - `operating_income_pct_of_revenue` (number | null, required) - `operating_income_pct_change_pp` (number | null, required) - `filing` (object, required) - `form` (string, required) - `filed_on` (string, required) - `accepted_at` (string, required) - `items` (string[], required) - `url` (string, required) - `filings` (object[], required) - `form` (string, required) - `filed_on` (string, required) - `accepted_at` (string, required) - `items` (string[], required) - `url` (string, required) - `research_coverage` (object) - `direct` (released | not_released, required) - `related` (object, required) - `status` ("not_checked", required) - `disclosures` (object) - `scope` ("retained_primary_disclosures", required) - `status` (available | not_covered, required) - `observed_at` (string, required) - `price_move_attribution` ("unverified", required) - `next_earnings` (object, required) - `scheduled_on` (string, required) - `release_timing` ("before_market_open", required) - `call_at` (string, required) - `source` (object, required) - `publisher` (string, required) - `published_on` (string, required) - `published_at` (string) - `url` (string, required) - `recent_announcements` (object[], required) - `headline` (string, required) - `summary` (string, required) - `source` (object, required) - `publisher` (string, required) - `published_on` (string, required) - `published_at` (string) - `url` (string, required) - `corroborating_source` (object) - `publisher` (string, required) - `published_on` (string, required) - `published_at` (string) - `url` (string, required) - `finviz_market_snapshot` (object) - `provider` ("Finviz Elite", required) - `observed_at` (string, required) - `source_url` (string, required) - `price` (number, required) - `change_pct` (number) - `change_basis` ("provider_reported") ### 400 Invalid input - `error` (object, required) - `code` (string, required) - `message` (string, required) - `recovery` (string | null, required) - `retryable` (boolean, required) ### 401 Authentication failed - `error` (object, required) - `code` (string, required) - `message` (string, required) - `recovery` (string | null, required) - `retryable` (boolean, required) ### 402 Paid access required - `error` (object, required) - `code` (string, required) - `message` (string, required) - `recovery` (string | null, required) - `retryable` (boolean, required) ### 404 Security unavailable - `error` (object, required) - `code` (string, required) - `message` (string, required) - `recovery` (string | null, required) - `retryable` (boolean, required) ### 409 Duplicate request ID - `error` (object, required) - `code` (string, required) - `message` (string, required) - `recovery` (string | null, required) - `retryable` (boolean, required) ### 503 Stored intelligence temporarily unavailable - `error` (object, required) - `code` (string, required) - `message` (string, required) - `recovery` (string | null, required) - `retryable` (boolean, required) ## Agent feedback Report unclear, stale, or incorrect documentation through [BeliefState support](https://beliefstate.ai/contact). Include this page URL and the smallest reproducible detail.