> ## Documentation Index
> Fetch the complete documentation index at: https://docs.beliefstate.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# get_search_results

> Get matching investment cases

**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](https://docs.beliefstate.ai/guides/mcp-server.md).
* **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`](https://docs.beliefstate.ai/api-reference/beliefs/find-investor-beliefs-or-inspect-a-full-record).

## Example request

### MCP

```json theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "get_search_results",
    "arguments": {
      "q": "data center power demand",
      "limit": 5
    }
  }
}
```

### x402 HTTP

```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
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.

## Related

* [All research tools](https://docs.beliefstate.ai/tools/index.md)
* [API reference: GET /v1/beliefs](https://docs.beliefstate.ai/api-reference/beliefs/find-investor-beliefs-or-inspect-a-full-record.md)

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


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.