# Frequently asked questions Answers about setup, research data, coverage, billing, and common errors > Section: Help > Last updated: **2026-11-01**. > API version: **v1 (Latest)**. OpenAPI publication: **2026-11-08**. ## How do I get started? Choose the guide for where you want to use BeliefState. Check coverage before making a paid research request. - [Accountless x402 research](https://beliefstate.ai/agent-quickstart.md#pay-per-call-with-x402): check free coverage, then choose a research tool. Eighteen data tools cost 0.02 USDC, built-in comparison 0.50 USDC and search 1.50 USDC per call on Base. No account or API key required. - [Connect an AI](https://beliefstate.ai/connect): choose your client, check whether setup is available, and follow its sign in steps. - [REST quickstart](https://beliefstate.ai/docs/quickstart): create an API key, verify access, and read your first belief from a terminal or application. - [API reference](https://beliefstate.ai/docs/api/brief): inspect request parameters, example responses, and errors, or send a request in the playground. ## What does BeliefState return? BeliefState returns attributed analyst views: who held a thesis, what they said, when it was published and observed, and the evidence supporting it. Available revisions and measured market outcomes stay attached to the record. | Resource | Use it to | | --- | --- | | [Brief](https://beliefstate.ai/docs/api/brief) | Read a ticker's analyst theses, disagreements, risks, and recent changes. | | [Beliefs](https://beliefstate.ai/docs/api/beliefs) | Browse individual views or retrieve one full record with claims and evidence. | | [Sources](https://beliefstate.ai/docs/api/sources) | Inspect source identity, coverage, and access rights. | | [Tickers](https://beliefstate.ai/docs/api/tickers) | Check which symbols have released analyst beliefs. | Missing confidence, targets, horizons, or outcomes remain unknown. A recorded belief describes the source's view; it does not certify that the view is correct. ## Which AI clients can I connect? Check the Connect page for ChatGPT, Claude, Codex, and Cursor. It shows the setup action available to each client. A listed client is not a guarantee that new connections are open. 1. Open [Connect](https://beliefstate.ai/connect) and select your AI. 2. If setup is available, follow the client specific instructions and sign in with the BeliefState account that holds your credit. Review the read only permissions. 3. Select the @BeliefState mention in your AI and send the question below. Pasted text alone does not select the plugin. The first response checks coverage; stock research follows after you choose one. ```text Help me research a stock @BeliefState. ``` If setup is unavailable, adding the MCP URL or buying credit will not open it. Existing connections and new setup can have different availability. See [client setup and availability](https://beliefstate.ai/connect) for details. Keep API keys out of chat; consumer chat connections use browser sign in. ## Is my ticker covered? Use the public ticker endpoint. It requires no API key and does not use research credits. Coverage changes as records are released. ```bash curl --fail-with-body \ "https://beliefstate.ai/v1/tickers" ``` Look for your company's symbol in `tickers`. The response includes belief and analyst counts and observation dates. An absent company ticker means no released direct-company coverage for that request. Do not substitute a different company or assume payment adds coverage. This directory does not count fund or theme coverage. For an ETF, request a brief with the fund ticker to inspect dated holdings and related company research. The brief reports available, missing, and unauthorized coverage separately. - [Ticker response fields and examples](https://beliefstate.ai/docs/api/tickers) - [Coverage limits](https://beliefstate.ai/docs/coverage) ## How do I know a research response is usable? Check the returned company, data status, and evidence. A connected server badge or an HTTP 200 response alone does not establish useful research coverage. | Check | What it tells you | | --- | --- | | `data` | The actual returned records. Confirm they match your company and question. | | `data_status` | Whether the response is live or preview, how fresh it is, and where coverage is incomplete. | | `citations` | The evidence behind supported claims. Preserve the links and source timestamps. | | `warnings` | Limits or gaps that must stay visible in the answer. | Treat empty results and missing fields as explicit gaps. Do not infer an analyst's current position, confidence, or target when the source does not state it. Use the [brief response example](https://beliefstate.ai/docs/api/brief#response) to inspect the contract, or follow the [first-belief walkthrough](https://beliefstate.ai/docs/quickstart#verify) to check a result step by step. ## Do I need a subscription? Use accountless x402 data tools for 0.02 USDC per call on Base, built-in comparison for 0.50 USDC or search for 1.50 USDC. Alternatively, use account-based prepaid credits from $20. Pro and Commercial subscriptions include monthly research allowances and active company tracking. Public documentation and ticker discovery are free; there is no open free research plan. | Access | Price | Included capacity | | --- | --- | --- | | [x402](https://beliefstate.ai/agent-quickstart.md#pay-per-call-with-x402) | 0.02 USDC data · 0.50 comparison · 1.50 search | One selected research operation over HTTP or native MCP | | Pay as you go | From $20 per purchase, no subscription required | 1,000 | | Starter | $19 / month or $149 / year | 5 actively tracked companies and 1,000 successful requests / month | | Pro | $29 / month or $249 / year | 25 actively tracked companies and 3,000 successful requests / month | | Commercial | $299 / month or $2,990 / year | 100 actively tracked companies and 1,000,000 successful requests / month | $19 for your first month, then $29/month. First subscription, monthly Pro only; first subscription per account only. Existing and returning subscribers, annual plans and Commercial are excluded. Full Pro allowance applies from the first month. Annual Research API is $149 upfront, saving $79 versus twelve $19 monthly payments. Annual Pro is $249 upfront, saving $99 versus twelve standard $29 monthly payments. Commercial is $2,990 upfront, saving $598 (16.7%) versus twelve $299 monthly payments. Subscriptions renew monthly or annually until canceled. Included requests reset monthly, including annual plans, and do not roll over; annual subscribers do not receive a year's requests upfront. All plans can query currently released tickers and share usage across AI, MCP, and API. Purchased credit does not expire. Optional automatic refills are off by default and require separate consent. Historical prepaid credits retain their original request rate. There is no postpaid overage. - [Access options](https://beliefstate.ai/pricing) - [Manage billing or cancel a subscription](https://beliefstate.ai/billing) ## Do failed requests or retries use credits? Failed, rejected, and rate limited requests use no request units. Status and public ticker discovery are also free. Successful research reads use your account's allowance or credit. Tracking slots are separate from research requests. The Tracked companies page shows released research updates for your active selection without consuming requests. Buying prepaid credits does not add tracking slots. One AI question can make several research requests; included requests reset monthly. After an uncertain outcome for an account-based REST request, retry the exact request with the same `X-Request-ID` to avoid another charge. A duplicate request does not replay the response. If the API says the request is still in progress, wait for the original response. If it says the request ended without a charge, start a new logical request with a new UUID. Generate a new UUID when changing the endpoint, ticker, filters, or page. Reading a belief's full detail after listing beliefs is a separate research request. - [Check account usage](https://beliefstate.ai/usage) - [Request and retry instructions](https://beliefstate.ai/docs/quickstart#belief) ## Should I use MCP or REST? Use MCP when an AI client should discover and call tools. Use HTTP when your application needs direct control over requests. Account-based MCP and REST share account access and metering. The separate accountless x402 HTTP and native MCP interfaces expose twenty paid research tools. Eighteen data tools cost 0.02 USDC, built-in comparison 0.50 USDC and search 1.50 USDC per call on Base. - [MCP server and tools](https://beliefstate.ai/docs/mcp-server) - [REST quickstart](https://beliefstate.ai/docs/quickstart) - [Authentication](https://beliefstate.ai/docs/guides/authentication) For agent readable instructions, start with [llms.txt](https://beliefstate.ai/llms.txt), [agents.md](https://beliefstate.ai/agents.md), or the [developer quickstart](https://beliefstate.ai/agent-quickstart.md). Every documentation page also has a Markdown version in its page menu. ## What does point in time mean? A historical query excludes evidence observed after its declared cutoff. Publication time and first observed time are separate: an older article found later was not available to the system earlier. Later revisions add history rather than replacing earlier records. Preserve the response's `as_of` cutoff, evidence timestamps, and methodology when comparing results. A publisher's summary is evidence of that summary, not proof of an analyst's exact original words. - [Query at a historical cutoff](https://beliefstate.ai/docs/guides/point-in-time) - [Evidence and provenance](https://beliefstate.ai/docs/provenance) ## Why is my request failing? Read the error response before retrying. Authentication, billing, and missing coverage need different fixes. | Response | Next step | | --- | --- | | `400` | Check the parameter names, allowed values, and combinations in the endpoint reference. | | `401` | Use an active Bearer key, or reconnect your AI through browser sign in. | | `403` | Check workspace permissions and whether this client or operation is allowed. | | `402` | Check the credit balance, request allowance, and spend limits for the account making the request. | | `404` / `503` | Check ticker or record coverage and the error body. The requested record or service may be unavailable; more credit does not fix that. | | `429` / timeout | Wait before retrying. Follow Retry-After when present and reuse the request ID only for the same logical request. | - [Authentication help](https://beliefstate.ai/docs/guides/authentication) - [Check API access](https://beliefstate.ai/docs/api/status) - [Billing](https://beliefstate.ai/billing) ## Can BeliefState trade or read my whole conversation? The research service is read only. It cannot place or copy trades, edit research, or provide personalized investment advice. BeliefState receives the arguments your AI sends to its tools, not automatic access to the full conversation. Tool arguments can contain text from your question. Keep passwords, API keys, OAuth tokens, and private source material out of those arguments. Review connected app permissions in [account connections](https://beliefstate.ai/account/connections). - [Privacy policy](https://beliefstate.ai/privacy) - [Research disclosures](https://beliefstate.ai/disclosures) ## How do I report an error or request a correction? Use the Contact page. Include the page or record URL, what you expected, and what happened. For a data correction, identify the disputed field and link to the supporting original source. For API problems, include the HTTP status and request ID when available. Remove secrets and private source text from logs or screenshots. Privacy requests use the same contact route. - [Contact support](https://beliefstate.ai/contact) ## Agent feedback Report unclear, stale, or incorrect documentation through [BeliefState support](https://beliefstate.ai/contact). Include this page URL and the smallest reproducible detail.