get_subjects

Get research subjects · $0.02 per call (x402, USDC) Retrieves matching released research subjects by name or kind, including companies, industries and investment themes. Returns matching subject identifiers and available research coverage. Useful for resolving a non-company topic before requesting a brief or cases. Use the returned entity_id for follow-up research and preserve ambiguity when multiple subjects match; a ticker is optional for non-company subjects.

Input parameters

Parameter	Type	Required	Description
`q`	string	No	min length 1; max length 80
`kind`	”company” \| “instrument” \| “commodity” \| “macro_variable” \| “industry” \| “sector” \| “theme” \| “country” \| “geography” \| “person” \| “policy” \| “event_series” \| “event_occurrence” \| “currency” \| “index”	No
`as_of`	string	No
`limit`	integer	No	Requested page size. For ticker/entity belief lists, MCP returns up to twelve complete summaries within its response budget; pagination.limit is the effective size. Continue with next_cursor and the same ticker/entity_id. REST supports larger pages. min 1; max 50
`cursor`	string	No	min length 1; max length 2048

Transports

MCP: tools/call with name get_subjects at https://beliefstate.ai/mcp (account access) or https://beliefstate.ai/v1/research/mcp (wallet access). See MCP integration.
x402 HTTP: POST https://beliefstate.ai/v1/research/get_subjects with the arguments as a JSON body. An unpaid request returns an HTTP 402 payment quote.
Related REST resource: GET /v1/beliefs.

Example request

MCP

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "get_subjects",
    "arguments": {
      "q": "semiconductors",
      "limit": 5
    }
  }
}

x402 HTTP

curl --request POST \
  --url 'https://beliefstate.ai/v1/research/get_subjects' \
  --header 'Content-Type: application/json' \
  --data '{"q":"semiconductors","limit":5}'

The example shows request shape only. Identifiers are placeholders, not records.

Contract version: 2026-11-08. Input parameters and tool metadata come from the shared executable catalog. REST API version: v1.

Get Started

Core Concepts

Guides

Reference

Endpoints

Research tools

Input parameters

Transports

Example request

MCP

x402 HTTP

​Input parameters

​Transports

​Example request

​MCP

​x402 HTTP

​Related

Input parameters

Transports

Example request

MCP

x402 HTTP

Related