get_search_results

Get matching investment cases · $1.50 per call (x402, USDC) Retrieves ranked published investment cases matching thesis, investment theme or trade setup, with an optional company or subject filter. Returns ranked matching passages, attributed investors, dates, case IDs and citations. Useful for finding research about a business trend or investment question without knowing a ticker. Open selected cases with get_case for more depth. Ranking reflects library matches and coverage, rather than market-wide consensus. Continue with the returned cursor and unchanged query, filters and as_of cutoff.

Input parameters

Parameter	Type	Required	Description
`q`	string	No	Thesis, topic or trade setup. Required on the first page. min length 1; max length 2000
`ticker`	string	No	min length 1; max length 32
`entity_id`	string	No	Released subject ID returned by get_subjects.
`person_id`	string	No	min length 1; max length 128
`direction`	”bullish” \| “bearish” \| “mixed” \| “neutral” \| “non_directional” \| “unknown”	No
`status`	”forming” \| “active” \| “strengthened” \| “weakened” \| “reversed” \| “resolved” \| “abandoned” \| “unknown”	No
`time_horizon`	string	No	min length 1; max length 128
`changed_since`	string	No	Find initial research, author revisions, condition checks/plans or released outcomes becoming available after this cutoff. Keeps author dates and stance separate from system activity. Release changes and a complete ordered event-history checkpoint are not yet included.
`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	Use next_cursor for another page of the same search. min length 1; max length 2048

Transports

MCP: tools/call with name get_search_results 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_search_results 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_search_results",
    "arguments": {
      "q": "data center power demand",
      "limit": 5
    }
  }
}

x402 HTTP

curl --request POST \
  --url 'https://beliefstate.ai/v1/research/get_search_results' \
  --header 'Content-Type: application/json' \
  --data '{"q":"data center power demand","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