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

# Data dictionary

> What the main fields mean in each dataset.

Fields that appear on most responses, such as `asOf` and `coverage`, are on [Conventions](https://docs.alphayou.net/api/conventions.md). This page covers the rest.

## Insider trades

`GET /api/v1/insiders/trades`

| Field | Meaning |
| - | - |
| `filings[].filedAt` | The day the Form 4 reached the SEC |
| `filings[].side` | The filing's main direction by dollar value: buy or sell |
| `filings[].insider` | Who filed: name, role, and whether a director, an officer or a 10% owner |
| `filings[].trades[]` | Each trade: `date`, `action`, `shares`, `pricePerShare`, `valueUsd` |
| `totalBuyUsd`, `totalSellUsd` | Dollar totals of the buys and the sells in the filing |
| `labels.plan10b5_1` | The trade followed a pre-set 10b5-1 schedule. It says less than a trade chosen on the day |
| `labels.exerciseAndSell` | An option exercise paired with a sale |
| `labels.privateDealPurchase` | A purchase made in a private deal, not on the market |

Grants, awards, gifts and tax withholding on their own are not recorded.

## Insider clusters (Pro)

`GET /api/v1/insiders/clusters`

| Field | Meaning |
| - | - |
| `insiders` | How many different insiders filed. Insiders are told apart by their SEC CIK |
| `filings` | How many filings |
| `filingsUnderPlan` | How many of those were under a 10b5-1 plan |
| `firstFiledAt`, `lastFiledAt` | The first and last filing dates in the window |
| `insiderList` | Who filed |
| `tradesPath` | The address that lists every trade |

A cluster is a plain count. It is not a score, a ranking or a prediction.

## Funds (13F)

Used by `funds`, `holdings`, `changes` and `holders`.

| Field | Meaning |
| - | - |
| `fund.period` | The quarter end the filing covers |
| `fund.filedAt` | The day the 13F was filed |
| `fund.positionCount` | Positions the fund listed |
| `fund.reportedValueUsd` | The total value the filer reported on the cover page |
| `cusip` | The security's ID code |
| `ticker` | AlphaYou's mapping of the CUSIP. It is `null` when it could not be mapped |
| `shares`, `valueUsd` | As filed. A stock split changes `shares` with no trade |
| `vsPrior` | The change against the fund's previous filing: `status`, `sharesChange`, `sharesChangePct` |
| `comparedTo` | The earlier quarter end a change is measured against |
| `action` | In `changes`: `new` (not in the earlier filing), `exited` (not in the newer one), `added` or `trimmed` |
| `approxTradeValueUsd` | An estimate: shares changed times the quarter-end price. Not what the fund paid |

A 13F lists long positions in US-listed securities only. It shows a quarter end and is filed up to 45 days later, so it is not today's book. `holders` covers a curated set of about 130 managers, not every institution.

## Company 8-K disclosures

`GET /api/v1/tickers/{symbol}/disclosures`

| Field | Meaning |
| - | - |
| `form` | `8-K`, or `8-K/A` for an amended filing |
| `items[]` | The 8-K item number and its title, for example `2.02` Results of Operations and Financial Condition |
| `filedAt` | The day the company filed it |
| `acceptedAt` | When the SEC accepted it |
| `reportDate` | The date of the event the filing reports |
| `sourceUrl`, `filingIndexUrl` | The filing itself, and its index page on the SEC site |
| `windowDays`, `totalInWindow` | The look-back used, and how many filings exist in it, even if `limit` cut the list |

This is metadata only. It is not article text, news or sentiment.

## Top traders (Pro)

`GET /api/top-traders`

| Field | Meaning |
| - | - |
| `positions[].address` | The public Hyperliquid wallet |
| `coin` | The stock the contract is linked to, for example `AAPL` |
| `side` | `long` or `short` |
| `size`, `notionalUsd` | The position size and its dollar value |
| `entryPrice`, `markPrice` | The entry price and the current mark price |
| `unrealizedPnl` | Profit or loss not yet locked in |
| `observedAt` | When AlphaYou saw the position |
| `annualisedRoiPct` | An estimated yearly return. It is `null` when the estimate hits the 10,000% cap, and `roiCapped` says so |

These are contracts that follow a stock's price. They are not shares.


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