# Filings and trades (SEC EDGAR, US Congress)

> Companies, filings, XBRL facts, fundamentals, insider transactions, fails-to-deliver, 13F holdings, 8-K news and Congress trades.

Page: https://docs.aggre.org/api/data/filings · Section: API reference · All pages: https://docs.aggre.org/llms.txt

SEC EDGAR datasets and US Congress stock-trade disclosures. See the [filings guide](https://docs.aggre.org/datasets/filings.md).

On this page:

- [SEC companies on the coverage list](#listFilingsCompanies): `GET /v1/finance/filings/companies`
- [A company's filings](#listFilings): `GET /v1/finance/filings/filings`
- [As-filed XBRL facts of a company](#listFilingsCompanyFacts): `GET /v1/finance/filings/company_facts`
- [Normalized fundamentals per fiscal period](#listFilingsFundamentals): `GET /v1/finance/filings/fundamentals`
- [Form 4 insider transactions of an issuer](#listFilingsInsiderTransactions): `GET /v1/finance/filings/insider_transactions`
- [SEC fails-to-deliver balances of a symbol](#listFilingsFailsToDeliver): `GET /v1/finance/filings/fails_to_deliver`
- [SEC Form 13F holdings of a covered company](#listFilingsHoldings13f): `GET /v1/finance/filings/holdings_13f`
- [SEC 8-K current reports of a covered company, with the file names of their press releases](#listFilingsNews8k): `GET /v1/finance/filings/news_8k`
- [Stock trades of US members of Congress (Periodic Transaction Reports)](#listFilingsCongressTrades): `GET /v1/finance/filings/congress_trades`

## SEC companies on the coverage list {#listFilingsCompanies}

`GET /v1/finance/filings/companies`

Ordered by `cik`. [the filings guide](https://docs.aggre.org/datasets/filings.md).

**Parameters**

| Name | In | Required | Type | Description |
|---|---|---|---|---|
| `cik` | query | no | string, pattern `^[0-9]{1,10}$` | SEC CIK, one to ten digits, with or without leading zeros (returned padded). |
| `ticker` | query | no | string | Letters, digits, `.` or `-`, at most 12; case-insensitive. |
| `sic` | query | no | integer | Standard Industrial Classification code. |
| `cursor` | query | no | string | The previous page's `next_cursor`, unchanged. Opaque; a cursor from another route is 400. |
| `limit` | query | no | integer, 1–1000, default `100` | Rows per page. |

**Example**

```bash
curl -s "https://api.aggre.org/v1/finance/filings/companies?limit=3" \
  -H "Authorization: Bearer $AGGRE_API_KEY"
```

**Response** `200`: the envelope `{ "data": [...], "meta": {...}, "next_cursor": ... }` (see [Response format](https://docs.aggre.org/concepts/response-format.md)); each row of `data` follows the schema [`filings_company`](https://docs.aggre.org/api/schemas.md#filings_company).

**Errors**: `400`, `401`, `403`, `429`, `503`, in the shared envelope ([Errors](https://docs.aggre.org/concepts/errors.md)).

## A company's filings {#listFilings}

`GET /v1/finance/filings/filings`

Ordered by `filed_on`, `accession`. [the filings guide](https://docs.aggre.org/datasets/filings.md).

**Parameters**

| Name | In | Required | Type | Description |
|---|---|---|---|---|
| `cik` | query | yes | string, pattern `^[0-9]{1,10}$` | SEC CIK, one to ten digits, with or without leading zeros (returned padded). |
| `form` | query | no | string | Comma list of at most 20 form names, e.g. 10-K,8-K. |
| `from` | query | no | string, date | YYYY-MM-DD on `filed_on`, inclusive. |
| `to` | query | no | string, date | YYYY-MM-DD on `filed_on`, exclusive. |
| `order` | query | no | `asc` \| `desc` (default `desc`) | Sort direction (default newest first). |
| `cursor` | query | no | string | The previous page's `next_cursor`, unchanged. Opaque; a cursor from another route is 400. |
| `limit` | query | no | integer, 1–1000, default `100` | Rows per page. |

**Example**

```bash
curl -s "https://api.aggre.org/v1/finance/filings/filings?cik=<cik>&limit=3" \
  -H "Authorization: Bearer $AGGRE_API_KEY"
```

**Response** `200`: the envelope `{ "data": [...], "meta": {...}, "next_cursor": ... }` (see [Response format](https://docs.aggre.org/concepts/response-format.md)); each row of `data` follows the schema [`filings_filing`](https://docs.aggre.org/api/schemas.md#filings_filing).

**Errors**: `400`, `401`, `403`, `429`, `503`, in the shared envelope ([Errors](https://docs.aggre.org/concepts/errors.md)).

## As-filed XBRL facts of a company {#listFilingsCompanyFacts}

`GET /v1/finance/filings/company_facts`

Facts are as filed, never overwritten; `value` is a decimal string. [the filings guide](https://docs.aggre.org/datasets/filings.md).

**Parameters**

| Name | In | Required | Type | Description |
|---|---|---|---|---|
| `cik` | query | yes | string, pattern `^[0-9]{1,10}$` | SEC CIK, one to ten digits, with or without leading zeros (returned padded). |
| `concept` | query | no | string | Comma list of at most 20 concept names, e.g. Revenues,Assets. |
| `unit` | query | no | string |  |
| `period_from` | query | no | string, date | YYYY-MM-DD on the period end, inclusive. |
| `period_to` | query | no | string, date | YYYY-MM-DD on the period end, exclusive. |
| `fiscal_year` | query | no | integer | The filing's own label. |
| `fiscal_period` | query | no | `FY` \| `Q1` \| `Q2` \| `Q3` \| `Q4` |  |
| `latest` | query | no | boolean, default `true` | `true` (default): the latest-filed value of each period; `false`: every filed value. |
| `cursor` | query | no | string | The previous page's `next_cursor`, unchanged. Opaque; a cursor from another route is 400. |
| `limit` | query | no | integer, 1–1000, default `100` | Rows per page. |

**Example**

```bash
curl -s "https://api.aggre.org/v1/finance/filings/company_facts?cik=<cik>&limit=3" \
  -H "Authorization: Bearer $AGGRE_API_KEY"
```

**Response** `200`: the envelope `{ "data": [...], "meta": {...}, "next_cursor": ... }` (see [Response format](https://docs.aggre.org/concepts/response-format.md)); each row of `data` follows the schema [`filings_fact`](https://docs.aggre.org/api/schemas.md#filings_fact).

**Errors**: `400`, `401`, `403`, `429`, `503`, in the shared envelope ([Errors](https://docs.aggre.org/concepts/errors.md)).

## Normalized fundamentals per fiscal period {#listFilingsFundamentals}

`GET /v1/finance/filings/fundamentals`

Computed by Aggre's normalizer from as-filed facts, not published by the SEC (`meta.message` says how). No cursor. [the filings guide](https://docs.aggre.org/datasets/filings.md).

**Parameters**

| Name | In | Required | Type | Description |
|---|---|---|---|---|
| `cik` | query | yes | string, pattern `^[0-9]{1,10}$` | SEC CIK, one to ten digits, with or without leading zeros (returned padded). |
| `fiscal_period` | query | no | `FY` \| `Q` | `FY` or `Q` (any quarter). |
| `limit` | query | no | integer, 1–1000, default `12` | Periods returned, newest first. |

**Example**

```bash
curl -s "https://api.aggre.org/v1/finance/filings/fundamentals?cik=<cik>&limit=3" \
  -H "Authorization: Bearer $AGGRE_API_KEY"
```

**Response** `200`: the envelope `{ "data": [...], "meta": {...}, "next_cursor": ... }` (see [Response format](https://docs.aggre.org/concepts/response-format.md)); each row of `data` follows the schema [`filings_fundamental`](https://docs.aggre.org/api/schemas.md#filings_fundamental).

**Errors**: `400`, `401`, `403`, `429`, `503`, in the shared envelope ([Errors](https://docs.aggre.org/concepts/errors.md)).

## Form 4 insider transactions of an issuer {#listFilingsInsiderTransactions}

`GET /v1/finance/filings/insider_transactions`

`cik` is the ISSUER's. Newest transaction first. `price` is a decimal string, `shares` and `owned_after` are numbers; names of people are served as filed. [the filings guide](https://docs.aggre.org/datasets/filings.md) (and section 6.5 for the caveats).

**Parameters**

| Name | In | Required | Type | Description |
|---|---|---|---|---|
| `cik` | query | yes | string, pattern `^[0-9]{1,10}$` | SEC CIK, one to ten digits, with or without leading zeros (returned padded). |
| `from` | query | no | string, date | YYYY-MM-DD on `transaction_date`, inclusive. |
| `to` | query | no | string, date | YYYY-MM-DD on `transaction_date`, exclusive. |
| `code` | query | no | string, pattern `^[A-Z]$` | One capital letter: the Form 4 transaction code, e.g. P (purchase) or S (sale). |
| `amendments` | query | no | `collapse` \| `all` (default `collapse`) | `collapse`: a line a later 4/A of the same filer restates unchanged is shown once; `all`: every line. |
| `cursor` | query | no | string | The previous page's `next_cursor`, unchanged. Opaque; a cursor from another route is 400. |
| `limit` | query | no | integer, 1–1000, default `100` | Rows per page. |

**Example**

```bash
curl -s "https://api.aggre.org/v1/finance/filings/insider_transactions?cik=<cik>&limit=3" \
  -H "Authorization: Bearer $AGGRE_API_KEY"
```

**Response** `200`: the envelope `{ "data": [...], "meta": {...}, "next_cursor": ... }` (see [Response format](https://docs.aggre.org/concepts/response-format.md)); each row of `data` follows the schema [`filings_insider_transaction`](https://docs.aggre.org/api/schemas.md#filings_insider_transaction).

**Errors**: `400`, `401`, `403`, `429`, `503`, in the shared envelope ([Errors](https://docs.aggre.org/concepts/errors.md)).

## SEC fails-to-deliver balances of a symbol {#listFilingsFailsToDeliver}

`GET /v1/finance/filings/fails_to_deliver`

The aggregate net balance of shares that failed to be delivered, by settlement date; a fail can arise on a long or a short sale and is not evidence of abusive or naked short selling (`meta.message` says so). `quantity` is an integer, `price` the SEC's previous-day close as a decimal string. No CUSIP is stored or served. [the filings guide](https://docs.aggre.org/datasets/filings.md).

**Parameters**

| Name | In | Required | Type | Description |
|---|---|---|---|---|
| `symbol` | query | yes | string, pattern `^[A-Za-z0-9.-]{1,15}$` | The ticker symbol, upper-cased by the API: 1 to 15 of letters, digits, `.` and `-`. |
| `from` | query | no | string, date | YYYY-MM-DD on `settlement_date`, inclusive. |
| `to` | query | no | string, date | YYYY-MM-DD on `settlement_date`, exclusive. |
| `order` | query | no | `asc` \| `desc` (default `desc`) | Sort direction (default newest first). |
| `cursor` | query | no | string | The previous page's `next_cursor`, unchanged. Opaque; a cursor from another route is 400. |
| `limit` | query | no | integer, 1–1000, default `100` | Rows per page. |

**Example**

```bash
curl -s "https://api.aggre.org/v1/finance/filings/fails_to_deliver?symbol=<symbol>&limit=3" \
  -H "Authorization: Bearer $AGGRE_API_KEY"
```

**Response** `200`: the envelope `{ "data": [...], "meta": {...}, "next_cursor": ... }` (see [Response format](https://docs.aggre.org/concepts/response-format.md)); each row of `data` follows the schema [`filings_ftd`](https://docs.aggre.org/api/schemas.md#filings_ftd).

**Errors**: `400`, `401`, `403`, `429`, `503`, in the shared envelope ([Errors](https://docs.aggre.org/concepts/errors.md)).

## SEC Form 13F holdings of a covered company {#listFilingsHoldings13f}

`GET /v1/finance/filings/holdings_13f`

One institution's holding of the company in one quarter, from the SEC's Form 13F data sets (originals and combination reports; options and bonds left out; the lines of one filing for one issuer summed). **Matched by the issuer's name** (the CUSIP is neither read nor stored), so a row may include another class of the same issuer and a differently spelled one may be missing: `meta.message` always says so. Newest quarter first, the largest holding first within a quarter. `consistent` is false when the reported price (`value_usd` / `shares`) is more than 5 times away from that quarter's median for the stock; such rows are hidden unless `consistent=all`. Give `ticker` or `issuer_cik`, not both. [the filings guide](https://docs.aggre.org/datasets/filings.md).

**Parameters**

| Name | In | Required | Type | Description |
|---|---|---|---|---|
| `ticker` | query | no | string, pattern `^[A-Za-z0-9.-]{1,12}$` | A coverage ticker, upper-cased by the API: letters, digits, `.` and `-`, at most 12. Give this or `issuer_cik`. |
| `issuer_cik` | query | no | string, pattern `^[0-9]{1,10}$` | The issuer's CIK, with or without leading zeros; returned padded to ten digits. Give this or `ticker`. |
| `period` | query | no | string, date | A quarter end, YYYY-MM-DD. |
| `consistent` | query | no | `true` \| `all` (default `true`) | `true` (default) hides rows whose price is out of line; `all` shows them too. |
| `cursor` | query | no | string | The previous page's `next_cursor`, unchanged. Opaque; a cursor from another route is 400. |
| `limit` | query | no | integer, 1–1000, default `100` | Rows per page. |

**Example**

```bash
curl -s "https://api.aggre.org/v1/finance/filings/holdings_13f?limit=3" \
  -H "Authorization: Bearer $AGGRE_API_KEY"
```

**Response** `200`: the envelope `{ "data": [...], "meta": {...}, "next_cursor": ... }` (see [Response format](https://docs.aggre.org/concepts/response-format.md)); each row of `data` follows the schema [`filings_holding_13f`](https://docs.aggre.org/api/schemas.md#filings_holding_13f).

**Errors**: `400`, `401`, `403`, `429`, `503`, in the shared envelope ([Errors](https://docs.aggre.org/concepts/errors.md)).

## SEC 8-K current reports of a covered company, with the file names of their press releases {#listFilingsNews8k}

`GET /v1/finance/filings/news_8k`

The company's 8-K and 8-K/A reports, newest first, with their items and, where the report came with a press release, the Exhibit 99 documents' file names and the company's own short descriptions (an `EX-99.1` description that only repeats the type is `null`). **No text of a release or of any filing is stored or served**: open `url` (the report on EDGAR) or the exhibit's file in the same EDGAR folder. `exhibits_complete` is false while the report may carry a release (items 2.02, 7.01, 8.01) and its EDGAR header page has not been read yet (the worker reads at most 5 per company per day and 200 per hour, and gives up on a page after 5 tries); a report that cannot carry one is complete with no exhibits. Reports filed before the worker's window (90 days by default) are listed but were never asked about. Give `cik` or `ticker`, not both. [the filings guide](https://docs.aggre.org/datasets/filings.md).

**Parameters**

| Name | In | Required | Type | Description |
|---|---|---|---|---|
| `cik` | query | no | string, pattern `^[0-9]{1,10}$` | The company's CIK, with or without leading zeros; returned padded to ten digits. Give this or `ticker`. |
| `ticker` | query | no | string, pattern `^[A-Za-z0-9.-]{1,12}$` | A coverage ticker, upper-cased by the API: letters, digits, `.` and `-`, at most 12. Give this or `cik`. |
| `from` | query | no | string, date | First filing day (inclusive), YYYY-MM-DD. |
| `to` | query | no | string, date | Last filing day (exclusive), YYYY-MM-DD; must be after `from`. |
| `item` | query | no | string, pattern `^[0-9]{1,2}\.[0-9]{2}$` | Only reports that list this 8-K item number, e.g. `2.02` (results of operations), `7.01` (Regulation FD), `8.01` (other events). |
| `cursor` | query | no | string | The previous page's `next_cursor`, unchanged. Opaque; a cursor from another route is 400. |
| `limit` | query | no | integer, 1–1000, default `100` | Rows per page. |

**Example**

```bash
curl -s "https://api.aggre.org/v1/finance/filings/news_8k?limit=3" \
  -H "Authorization: Bearer $AGGRE_API_KEY"
```

**Response** `200`: the envelope `{ "data": [...], "meta": {...}, "next_cursor": ... }` (see [Response format](https://docs.aggre.org/concepts/response-format.md)); each row of `data` follows the schema [`filings_news_8k`](https://docs.aggre.org/api/schemas.md#filings_news_8k).

**Errors**: `400`, `401`, `403`, `429`, `503`, in the shared envelope ([Errors](https://docs.aggre.org/concepts/errors.md)).

## Stock trades of US members of Congress (Periodic Transaction Reports) {#listFilingsCongressTrades}

`GET /v1/finance/filings/congress_trades`

Stock trades that members of Congress reported under the STOCK Act, newest trade first. **Disclosed weeks after the trade**: `transaction_date` is the trade, `disclosure_date` the day it was reported. **Amounts are the value ranges the report uses** (`amount_low`, `amount_high`, and the text as filed), never the size of a trade; `owner` says whose trade it is (a spouse's or a child's too). Rows with `source` `senate_stock_watcher` are a community aggregate's reading of the Senate's reports, not the Senate's own data. Use of financial disclosure reports is restricted by law and whether that bears on this service has not been reviewed; the dataset is off until a person has read its source's terms, and `meta.message` says so while they are unread. Not a recommendation. `meta.source` is the rows' source when they share one, else `aggre`; `meta.dataset.sources` lists the terms of each source in the page. The API records the dataset asked for, never the query. [the filings guide](https://docs.aggre.org/datasets/filings.md).

**Parameters**

| Name | In | Required | Type | Description |
|---|---|---|---|---|
| `politician` | query | no | string | Case-insensitive substring of the member's name, 2 to 100 characters; percent, underscore and backslash are literal. |
| `ticker` | query | no | string, pattern `^[A-Za-z0-9.-]{1,12}$` | Exact ticker, upper-cased by the API: letters, digits, `.` and `-`, at most 12. |
| `chamber` | query | no | `Senate` \| `House` | Only this chamber. |
| `type` | query | no | `buy` \| `sell` \| `exchange` | Only this kind of transaction (`transaction_type`). |
| `from` | query | no | string, date | First transaction day (inclusive), YYYY-MM-DD. |
| `to` | query | no | string, date | Last transaction day (exclusive), YYYY-MM-DD; must be after `from`. |
| `disclosed_from` | query | no | string, date | First disclosure day (inclusive), YYYY-MM-DD; rows without a disclosure date never match. |
| `disclosed_to` | query | no | string, date | Last disclosure day (exclusive), YYYY-MM-DD; must be after `disclosed_from`. |
| `cursor` | query | no | string | The previous page's `next_cursor`, unchanged. Opaque; a cursor from another route is 400. |
| `limit` | query | no | integer, 1–1000, default `100` | Rows per page. |

**Example**

```bash
curl -s "https://api.aggre.org/v1/finance/filings/congress_trades?limit=3" \
  -H "Authorization: Bearer $AGGRE_API_KEY"
```

**Response** `200`: the envelope `{ "data": [...], "meta": {...}, "next_cursor": ... }` (see [Response format](https://docs.aggre.org/concepts/response-format.md)); each row of `data` follows the schema [`filings_congress_trade`](https://docs.aggre.org/api/schemas.md#filings_congress_trade).

**Errors**: `400`, `401`, `403`, `429`, `503`, in the shared envelope ([Errors](https://docs.aggre.org/concepts/errors.md)).