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

# Recipes

> 3 working examples: insider buys this week, which funds hold a stock, and the latest 8-K in an AI chat.

Each recipe gives you something you can run today. The example responses are shortened samples, so dates and numbers will differ when you run them.

## Recipe 1: insider buys this week

**Needs:** a Free key. **Costs:** 3 units a call.

Insiders such as executives and directors must report their open-market trades on SEC Form 4. This pulls the buys filed in the last 7 days.

```bash curl theme={null}
curl -H "x-api-key: $ALPHAYOU_API_KEY" \
  "https://api.alphayou.net/api/v1/insiders/trades?side=buy&days=7"
```

```python Python theme={null}
import os
import requests

response = requests.get(
    "https://api.alphayou.net/api/v1/insiders/trades",
    params={"side": "buy", "days": 7},
    headers={"x-api-key": os.environ["ALPHAYOU_API_KEY"]},
    timeout=20,
)
response.raise_for_status()
for filing in response.json()["filings"]:
    who = filing["insider"]
    print(filing["filedAt"], filing["ticker"], who["name"], who["role"],
          round(filing["totalBuyUsd"]), filing["sourceUrl"])
```

A sample filing from the response. This one is a sale, shown for its shape. With `side=buy`, every filing is a buy.

```json theme={null}
{
  "ticker": "NTRA",
  "issuer": "Natera, Inc.",
  "filedAt": "2026-11-05",
  "side": "sell",
  "insider": { "name": "Sheena Jonathan", "role": "Director" },
  "trades": [
    { "date": "2026-11-02", "action": "sell", "shares": 109, "pricePerShare": 400.2942, "valueUsd": 43632.07 }
  ],
  "totalBuyUsd": 0,
  "totalSellUsd": 44796.67,
  "labels": { "plan10b5_1": true, "exerciseAndSell": false, "privateDealPurchase": false },
  "sourceUrl": "https://www.sec.gov/Archives/edgar/data/1646649/000164664926000043/0001646649-26-000043-index.htm"
}
```

How to read it:

* `side` is the filing's main direction by dollar value.
* `plan10b5_1` means the trade followed a pre-set schedule. It says less than a trade the insider chose on the day.
* `filedAt` is the filing date. The trade date is inside `trades`.
* A Free key returns the 5 newest filings from the last 90 days and no more pages. A Pro key pages through 365 days with `limit` and `cursor`. See [Conventions](https://docs.alphayou.net/api/conventions.md).
* An empty list means no open-market trade is on file. It does not mean nobody filed.

## Recipe 2: which funds hold a stock

**Needs:** a Pro key. **Costs:** 3 units a call.

13F filings show what big funds held at the end of each quarter. Start from a stock, then look at one fund's changes.

**1. Find the funds that hold NVDA**

```bash theme={null}
curl -H "x-api-key: $ALPHAYOU_API_KEY" \
  "https://api.alphayou.net/api/v1/tickers/NVDA/holders?limit=5"
```

A sample holder from the response:

```json theme={null}
{
  "cik": 2012383,
  "fund": "BlackRock, Inc.",
  "period": "2026-06-30",
  "filedAt": "2026-08-07",
  "shares": 1941918386,
  "valueUsd": 388558449933,
  "vsPrior": { "status": "added", "sharesChange": 16385212, "sharesChangePct": 0.85 },
  "sourceUrl": "https://www.sec.gov/Archives/edgar/data/2012383/000201238326003238/"
}
```

**2. See what one fund changed**

Use the `cik` from the step above.

```bash theme={null}
curl -H "x-api-key: $ALPHAYOU_API_KEY" \
  "https://api.alphayou.net/api/v1/funds/1067983/changes?limit=5"
```

A sample change from the response:

```json theme={null}
{
  "ticker": "GOOGL",
  "issuer": "ALPHABET INC",
  "action": "added",
  "sharesBefore": 54249798,
  "sharesNow": 78791167,
  "sharesChangePct": 45.24,
  "approxTradeValueUsd": 8770349040
}
```

Read these with care:

* `period` is the quarter end. The filing is public up to 45 days later. This is not what the fund holds today.
* The holders list covers the funds we track, not every investor. An empty list does not prove nobody holds the stock.
* `approxTradeValueUsd` is an estimate from quarter-end prices. It is not a price anyone paid, and nothing inside the quarter is visible.

## Recipe 3: the latest 8-K, in an AI chat

**Needs:** no key. Works in [Claude](https://docs.alphayou.net/api/connect-claude.md) or [ChatGPT](https://docs.alphayou.net/api/connect-chatgpt.md) with the research connector added.

Paste this into a new chat:

```text theme={null}
Use AlphaYou to show NVIDIA's most recent 8-K filings, with filing dates and original SEC links.
```

Behind the scenes the assistant calls `get_company_disclosures` with `ticker` set to `NVDA`. A sample of what comes back:

```json theme={null}
{
  "ticker": "NVDA",
  "source": "SEC EDGAR",
  "status": "available",
  "disclosures": [
    {
      "formType": "8-K",
      "filingItem": "8.01",
      "filingItemTitle": "Other Events",
      "filedAt": "2026-09-03T00:00:00.000Z",
      "sourceUrl": "https://www.sec.gov/Archives/edgar/data/1045810/000104581026000078/nvda-20260902.htm"
    },
    {
      "formType": "8-K",
      "filingItem": "2.02",
      "filingItemTitle": "Results of Operations and Financial Condition",
      "filedAt": "2026-08-26T00:00:00.000Z",
      "sourceUrl": "https://www.sec.gov/Archives/edgar/data/1045810/000104581026000073/nvda-20260826.htm"
    }
  ]
}
```

Good follow-ups to ask:

* "Which of these was the earnings release?" The item `2.02` is the earnings result.
* "Compare this with the insider trades in the same weeks." This one calls a second tool, so ask it in the same chat.

An 8-K item number alone does not tell you what happened. Always open the linked filing before you act on it.


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