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

> ## Agent Instructions
> API requests use the base URL https://api.unusualwhales.com and require a bearer token in the `Authorization` header (`Authorization: Bearer <API_KEY>`). Create and manage API tokens at https://unusualwhales.com/dashboard/api.
> For live market data inside an AI tool, use the Unusual Whales MCP server at https://unusualwhales.com/public-api/mcp.
> Instructions for agents using Unusual Whales tools: https://unusualwhales.com/skill.md

# SEC filings

> Receive SEC EDGAR filings as they are processed: every filing, insider trades, 13F reports, 13D/G ownership reports, company financial reports and Rule 497 filings.

**NOTE:**
This is the documentation for the websocket channels `sec:filings`, `sec:insider_trades`, `sec:13f_alerts`, `sec:13f_filings`, `sec:13dg_filings`, `sec:company_reports` and `sec:497_filings`.
Websocket access for personal use is only available through the [Advanced plan](https://unusualwhales.com/pricing?product=api).

You can find fully-functional examples that stream data from many channels here:

* Python: [https://github.com/unusual-whales/api-examples/tree/main/examples/ws-multi-channel-multi-output](https://github.com/unusual-whales/api-examples/tree/main/examples/ws-multi-channel-multi-output)
* Javascript: [https://github.com/unusual-whales/api-examples/tree/main/examples/ws-multi-channel-multi-output-nodejs](https://github.com/unusual-whales/api-examples/tree/main/examples/ws-multi-channel-multi-output-nodejs)

Connect to the websocket URI:

`wss://api.unusualwhales.com/socket?token=<YOUR_API_TOKEN>`

then `join` one or more of the channels below. Each channel streams one type of SEC filing
message for every ticker and filer at once. The part after `sec:` names the filing type,
not a ticker. There is no per-ticker form, so a channel such as `sec:filings:AAPL` is
rejected.

### Channels

Each channel has its own page with a payload example and a description of every field.

<div className="channel-table">
  | Channel | Content |
  | - | - |
  | [`sec:filings`](/docs/websocket/sec-filings/filings) | Every filing published to SEC EDGAR, including the filings that the other channels carry in more detail. |
  | [`sec:insider_trades`](/docs/websocket/sec-filings/insider-trades) | Insider trades (forms 3, 4, 5 and 144). The transactions that a reporting person files for a ticker on one day are aggregated by type. |
  | [`sec:13f_alerts`](/docs/websocket/sec-filings/13f-alerts) | A summary of an institution's quarterly 13F report: position counts, bought and sold values, and the top holdings by category. |
  | [`sec:13f_filings`](/docs/websocket/sec-filings/13f-filings) | Every 13F filing (13F-HR, 13F-NT, 13F-CTR and their amendments), with the holdings totalled per security type. |
  | [`sec:13dg_filings`](/docs/websocket/sec-filings/13dg-filings) | Beneficial ownership reports (Schedule 13D, 13G and their amendments). |
  | [`sec:company_reports`](/docs/websocket/sec-filings/company-reports) | Annual and quarterly company reports (10-Q, 10-K, 20-F, 40-F and their amendments) with the financial statements parsed from the filing's XBRL data. |
  | [`sec:497_filings`](/docs/websocket/sec-filings/497-filings) | Rule 497 prospectus and summary filings of funds and securities issuers (497, 497J and 497K). |
</div>

Every channel carries the messages published to the Kafka topic
[`sec-filings`](/docs/kafka/topics/sec-filings) under one message key. Each channel page names
its Kafka message and key.

These channels stream every filing of their type. They are separate from the SEC filing,
insider trade and 13F notifications of [`custom_alerts`](/docs/websocket/custom-alerts), which
only deliver filings that match the alert configurations on your account.

### Payload

Every message is a two-element array: the channel name, then the payload object.

```
["sec:filings", { ... }]
```

Each payload carries the fields of its Kafka message under the same names and with the
values the producer published. Field names keep the spelling of the Kafka message, for
example `deffered_income_tax`, `date_excercisable` and `natureofownership`.

A field that the filing does not provide keeps its protobuf default: an empty string, `0`,
`false` or an empty array. A `0` can therefore mean either zero or not reported. No field
is ever `null`.

Dates are strings in `YYYY-MM-DD` format.

### Delivery characteristics

* **Updates are event driven.** A channel stays silent until a filing of its type is
  processed. There is no heartbeat and no fixed schedule.
* **Messages are not filtered by date.** Every message is forwarded when it arrives, so a
  message can describe a filing from an earlier day.
* **Messages are not deduplicated.** If the same filing is published twice, or is
  redelivered after a server restart, you receive it twice. Each channel page names the
  fields that identify a message.
* **Missed messages are not replayed.** Messages sent while you are disconnected are lost.
  The Kafka topic [`sec-filings`](/docs/kafka/topics/sec-filings)
  keeps them for its retention period.