How do I get started?
Choose the guide for where you want to use BeliefState. Check coverage before making a paid research request.- Connect an AI: choose your client, check whether setup is available, and follow its sign-in steps.
- REST quickstart: create an API key, verify access, and read your first belief from a terminal or application.
- API reference: inspect request parameters, example responses, and errors, or send a request in the playground.
What does BeliefState return?
BeliefState returns attributed investor 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.
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.- Open Connect and select your AI.
- 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.
- Enable BeliefState in a conversation and ask the coverage question below. Then ask about a company returned in that coverage.
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.tickers. The response includes belief and investor counts and observation dates. An absent ticker means no released coverage for that request. Do not substitute a different company or assume payment adds 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.
Treat empty results and missing fields as explicit gaps. Do not infer an investor’s current position, confidence, or target when the source does not state it. Use the brief response example to inspect the contract, or follow the first-belief walkthrough to check a result step by step.
Do I need a subscription?
Choose Investor, Pro, or Commercial by how many companies you want to actively track. Every plan offers monthly or yearly billing and a separate research request allowance. Existing purchased credit remains usable. Public documentation and ticker discovery are free; there is no open free research plan.
Annual billing saves 16.7% versus twelve monthly payments, paid upfront. 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. Each refill currently requires checkout; automatic refills are not enabled. There is no postpaid overage.
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 a $5 request refill does not add tracking slots. One AI question can make several research requests; included requests reset monthly. For REST retries, keep the sameX-Request-ID for the same logical request so a duplicate retry is counted once. 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.
Should I use MCP or REST?
Use MCP when an AI client should discover and call tools. Use REST when your application needs direct control over endpoints and request parameters. Both read the same released intelligence and use the same account access and metering rules. For agent-readable instructions, start with llms.txt, agents.md, or the developer quickstart. 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’sas_of cutoff, evidence timestamps, and methodology when comparing results. A publisher’s summary is evidence of that summary, not proof of an investor’s exact original words.