> ## 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_market_returns

> Get market returns

**Get market returns** · \$0.02 per call (x402, USDC)

Retrieves supported split-adjusted close-price returns for one ticker versus SPY. Request session\_intervals from 1 to 252; date bounds select return end sessions, while an omitted date range uses the latest completed official session. Returns typed security and benchmark returns, excess percentage points, exact session dates and retained support. Complete security/SPY paths, official calendars and verified adjustment basis are required; missing or ambiguous inputs remain held. Price returns exclude dividends, fees and execution effects, and do not measure investor account performance. Current requests refresh only missing, incomplete or stale closing-price references from the configured delayed SIP feed; historical/pinned queries preserve input availability; use the returned snapshot, as\_of, filters and next\_offset for further pages.

## Input parameters

| Parameter | Type | Required | Description |
| - | - | - | - |
| `cursor` | string | No | Archive continuation token; reuse with snapshot ID/hash, as\_of and unchanged filters. max length 4096 |
| `ticker` | string | Yes | |
| `as_of` | string | No | Availability cutoff, separate from event/period filters. Historical reads never refresh. |
| `snapshot_id` | string | No | Pin continuation to the returned snapshot ID; reuse with snapshot\_hash and as\_of. |
| `snapshot_hash` | string | No | |
| `filters_sha256` | string | No | Reuse the returned filter hash unchanged with continuation pages. |
| `offset` | integer | No | min 0; max 10000000 |
| `limit` | integer | No | Matching typed observations per page; default32. min 1; max 100 |
| `max_snapshot_age_hours` | number | No | Requested verification-age tolerance: default1hour for retained archives,24hours for closing-price references. Record dates and publication cadence are separate. max 87600 |
| `date_from` | string | No | Inclusive native date lower bound, selected by date\_field. |
| `date_to` | string | No | Inclusive native date upper bound, selected by date\_field. |
| `date_field` | "period" \| "observation" | No | Date meaning; defaults to period for facts/macro/holdings/returns, event for insider trades, observation for options/short volume, scheduled for calendar. |
| `session_intervals` | array of integer | No | |

## Transports

* **MCP:** `tools/call` with name `get_market_returns` 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_market_returns` with the arguments as a JSON body. An unpaid request returns an HTTP 402 payment quote.

## Example request

### MCP

```json theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "get_market_returns",
    "arguments": {
      "ticker": "NVDA"
    }
  }
}
```

### x402 HTTP

```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
curl --request POST \
  --url 'https://beliefstate.ai/v1/research/get_market_returns' \
  --header 'Content-Type: application/json' \
  --data '{"ticker":"NVDA"}'
```

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

## Related

* [All research tools](https://docs.beliefstate.ai/tools/index.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.