# Field Reference

A human-readable companion to the [API Reference](/api) schemas. **All return values are decimal
fractions** (`0.0523` = +5.23%) with up to 6 decimal places, and are `null` when the fund lacks
enough history for that period.

## Fund

Returned by `GET /v1/funds` (as a list) and `GET /v1/funds/{code}`.

| Field | Type | Notes |
|---|---|---|
| `code` | string | Bare ticker, e.g. `SPY`. Primary key. |
| `market` | string | Always `US` today. Reserved for future multi-market support. |
| `name` | string \| null | Fund name. |
| `country` | string \| null | Domicile country. |
| `exchange` | string \| null | Listing exchange. |
| `currency` | string \| null | Reporting currency. |
| `type` | string \| null | Security type, e.g. `ETF` or `FUND`. |
| `isin` | string \| null | ISIN identifier, when available. |
| `is_inactive` | bool \| null | `true` if the fund is delisted/closed. |
| `inactive_date` | date \| null | Date the fund went inactive. |
| `min_return_date` | date \| null | Earliest date with return data (≈ inception). |
| `max_return_date` | date \| null | Latest date with return data. |

## Trailing returns

Returned by `GET /v1/funds/{code}/trailing-returns` (one row) and
`POST /v1/trailing-returns/batch` (one row per found code).

| Field | Type | Notes |
|---|---|---|
| `code` | string | Bare ticker. |
| `market` | string | Always `US`. |
| `as_of_date` | date | The trading day this row is for (after any snap-back). |
| `return_1d` | decimal \| null | Trailing 1-day total return (cumulative). |
| `return_1w` | decimal \| null | 1-week (cumulative). |
| `return_1m` | decimal \| null | 1-month (cumulative). |
| `return_3m` | decimal \| null | 3-month (cumulative). |
| `return_6m` | decimal \| null | 6-month (cumulative). |
| `return_ytd` | decimal \| null | Year-to-date (cumulative). |
| `return_1y` | decimal \| null | 1-year (cumulative). |
| `return_2y` | decimal \| null | 2-year (annualized / CAGR). |
| `return_3y` | decimal \| null | 3-year (annualized). |
| `return_4y` | decimal \| null | 4-year (annualized). |
| `return_5y` | decimal \| null | 5-year (annualized). |
| `return_7y` | decimal \| null | 7-year (annualized). |
| `return_10y` | decimal \| null | 10-year (annualized). |
| `return_15y` | decimal \| null | 15-year (annualized). |
| `return_20y` | decimal \| null | 20-year (annualized). |
| `return_earliest_available` | decimal \| null | Since inception (annualized). |
| `extra_returns` | object | Any newer, seed-driven `return_*` period not yet a first-class field above. Usually empty. Forward-compatibility: new periods appear here without a breaking change. |

> **Why `extra_returns`?** The set of return periods is data-driven upstream. If a new period is
> added, it surfaces under `extra_returns` (as `{ "return_x": 0.123 }`) rather than breaking your
> client. Read known periods from their named fields and treat `extra_returns` as optional extras.

## Calendar-year returns

Returned by `GET /v1/funds/{code}/calendar-returns` (one row) and
`POST /v1/calendar-returns/batch` (one row per found code).

| Field | Type | Notes |
|---|---|---|
| `code` | string | Bare ticker. |
| `market` | string | Always `US`. |
| `calendar_year` | integer | The calendar year, e.g. `2024`. |
| `base_date` | date \| null | Last trading day of the prior year (or inception for the first year). |
| `end_date` | date \| null | Last trading day of the year (or latest available for the current year). |
| `calendar_year_return` | decimal \| null | Total return over the year (always cumulative). |

## Pagination

`GET /v1/funds` returns a `FundList`:

| Field | Type | Notes |
|---|---|---|
| `data` | Fund[] | The page of funds. |
| `next_cursor` | string \| null | Pass back as `?cursor=` for the next page. `null` when there are no more. |

See [Errors, rate limits & quotas](/errors) for pagination limits and error shapes, and
[Methodology](/methodology) for how each return is computed.