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

# Fund Returns API

> A REST API for trailing and calendar-year total returns of US mutual funds and ETFs, the same data as the Snowflake listing, without Snowflake.

The Fund Returns API serves trailing and calendar-year total returns for \~32,000 US
mutual funds and ETFs over a fast, cheap REST endpoint. It's the same curated data
behind our [Snowflake listing](/datasets/fund-returns), refreshed daily from adjusted
end-of-day pricing, for teams that want an HTTP API instead of a warehouse share.

## Base URL

```
https://api.fruitstand.dev
```

## Authentication

Every request needs your API key, sent as a Bearer token:

```bash theme={null}
curl https://api.fruitstand.dev/v1/funds/SPY/trailing-returns \
  -H "Authorization: Bearer YOUR_API_KEY"
```

Create a key and pick a plan from your [dashboard](https://app.fruitstand.dev). Keys are
metered and rate-limited by plan. See [Pricing](/pricing).

<Card title="Create a free key" icon="key" href="https://app.fruitstand.dev/pricing">
  Create an account, grab an API key, and pick any plan (free or not).
</Card>

## Quick start

```bash theme={null}
# Search for a fund
curl -H "Authorization: Bearer YOUR_API_KEY" \
  "https://api.fruitstand.dev/v1/funds?q=S%26P%20500&type=ETF"

# Latest trailing returns for one fund
curl -H "Authorization: Bearer YOUR_API_KEY" \
  "https://api.fruitstand.dev/v1/funds/SPY/trailing-returns"

# Trailing returns as of a specific date
curl -H "Authorization: Bearer YOUR_API_KEY" \
  "https://api.fruitstand.dev/v1/funds/SPY/trailing-returns?as_of=2026-08-14"

# Latest returns for many funds in one call (up to 100)
curl -H "Authorization: Bearer YOUR_API_KEY" -H "Content-Type: application/json" \
  -d '{"codes":["SPY","QQQ","VTI"]}' \
  "https://api.fruitstand.dev/v1/trailing-returns/batch"
```

## How it works

* **Point lookups by design.** Trailing and calendar-year endpoints return a single row:
  the latest for a fund, or a specific `as_of` date / `year`. To pull many funds at once,
  use the `/batch` endpoints (up to 100 codes per call) rather than paging a huge range.
* **Fund discovery.** `GET /v1/funds` searches by ticker or name and filters by type,
  country, and exchange, with keyset pagination via the `cursor` field.
* **Returns semantics.** Cumulative for periods under 2 years (including YTD), annualized
  (CAGR) for 2 years and longer, matching the [Snowflake docs](/datasets/fund-returns) exactly.
* **Freshness.** Data refreshes daily on trading days; `GET /healthz` reports the newest
  available `as_of_date`.

## MCP server

The same data is available to AI agents over the [Model Context
Protocol](https://modelcontextprotocol.io). Point an MCP client at:

```
https://api.fruitstand.dev/mcp
```

Authenticate with the same API key (as a Bearer token). Tools: `searchFunds`, `getFund`,
`getTrailingReturns`, `batchTrailingReturns`, `getCalendarReturns`, `batchCalendarReturns`,
subject to the same plan rate limits as the REST API.

<Card title="Get an API key" icon="key" href="https://app.fruitstand.dev">
  Sign up, choose a plan, and start querying in minutes.
</Card>

<Note>
  Fund Returns data is provided for informational purposes only and is not investment
  advice or a recommendation. See [Pricing](/pricing) for plan terms.
</Note>