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

# How Otto reads SEC filings

> The filing sources, completeness rules, and caveats behind Otto's SEC data.

Otto reads public SEC EDGAR filings and returns the filing links with the data. The endpoints below share one rule: if a filing does not support a number or interpretation, Otto discloses the gap instead of filling it.

To choose an endpoint and prepare a request, start with [SEC filings and company fundamentals API](/intelligence-guides/sec-filings-api). This page explains how to interpret the filing data after delivery.

| Endpoint                    | Filing data                                                   |
| --------------------------- | ------------------------------------------------------------- |
| `/insider-trades`           | Form 4 transactions for one company                           |
| `/institutional-holdings`   | Form 13F positions for one investment manager                 |
| `/equity-smart-money`       | Form 4 activity and reported fundamentals for one company     |
| `/equity-smart-money-brief` | The same data, plus 13D/13G filing events and a written brief |
| `/form-144-filings`         | Notices of proposed insider sales                             |
| `/13d-activist-watch`       | Schedule 13D/13G filing events about one company              |
| `/form-4-feed`              | A recent slice of Form 4 filings across US issuers            |
| `/8k-material-events`       | Item-coded Form 8-K events for one company                    |
| `/financial-statements`     | Annual and quarterly statements plus a filing index           |

Most responses include a short `note`, a `methodology` link to this page, and structured `caveats[]`. Each structured caveat has:

* `code`: a stable key for programmatic handling;
* `plain`: the reading rule in plain English;
* `affects`: the response fields governed by that rule.

`/financial-statements` uses a plain-text `caveats[]` list because its rules apply at cell and line level. Its values carry provenance directly.

## Rules that apply across the family

* **Null means unknown or not reported, not zero.** Missing values are not estimated. Coverage fields explain what was read or omitted.
* **Amendments are handled by filing type.** Form 4 windows with a detected amendment are withheld uncharged; 13F amendments are composed; Form 144 totals are withheld while individual notices remain visible; an 8-K/A remains a separate filing.
* **Freshness comes from the response.** Read `generatedAt` or the response metadata. These are filing snapshots, not market-data feeds.
* **The filing controls the language.** For example, Form 4 codes `P` and `S` cover both open-market and private transactions, so Otto does not relabel them as open-market activity or infer motive.

## Shared caveats

| Code                     | How to read it                                                                                                                                    |
| ------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------- |
| `hourly_snapshot`        | An hourly filing snapshot. Read the response timestamp for freshness.                                                                             |
| `snapshot_not_live_feed` | A cached snapshot; response metadata states its age and whether it is degraded.                                                                   |
| `nulls_over_fabrication` | A missing value makes the affected total null. Companion counts describe the missing rows.                                                        |
| `amendment_withheld`     | A corrected Form 4 window is withheld until the amendment leaves the window; the refused call is not charged. Detection can lag by about an hour. |

## Form 4 transactions

| Code                        | How to read it                                                                                                     |
| --------------------------- | ------------------------------------------------------------------------------------------------------------------ |
| `no_transactions_in_window` | No qualifying transaction appeared in the window, so activity totals are null rather than a measured zero.         |
| `non_derivative_only`       | Only Table I non-derivative transactions are counted. An option exercise still appears as code `M`.                |
| `owner_side_excluded`       | Filings where the company is the owner of another issuer are excluded and counted in coverage.                     |
| `purchase_sale_codes`       | `P` and `S` mean purchase and sale, including private transactions.                                                |
| `mixed_security_classes`    | Share totals are null when a window mixes security classes; individual rows remain available.                      |
| `filing_level_attribution`  | `filedBy` and `filerRoles` describe the filing, while each row carries its own direct or indirect ownership field. |
| `transaction_code_legend`   | `P` purchase; `S` sale; `A` award; `G` gift; `M` option exercise; `F` shares withheld for tax.                     |

## Fundamentals

| Code                        | How to read it                                                                                                            |
| --------------------------- | ------------------------------------------------------------------------------------------------------------------------- |
| `ttm_where_reconstructable` | Figures are trailing twelve months when the filings support reconstruction; otherwise the labelled annual figure is used. |
| `yoy_positive_prior_only`   | A percentage change appears only when the prior period was positive. Sign changes are described in words.                 |
| `one_time_items_ttm_only`   | Impairments, restructuring, and disposals are screened only on the trailing-twelve-month basis.                           |

## Form 13F holdings

| Code                      | How to read it                                                                                                                       |
| ------------------------- | ------------------------------------------------------------------------------------------------------------------------------------ |
| `as_reported_by_manager`  | Positions are reproduced as filed and are not independently audited.                                                                 |
| `quarterly_rear_view`     | A 13F can arrive up to 45 days after quarter end and is not live positioning.                                                        |
| `amendments_composed`     | A restatement replaces the original; a new-holdings amendment appends. Pre-2023 values are normalized from thousands by filing date. |
| `options_are_underlying`  | Put/call rows report the underlying quantity and value, not option premium or ordinary long stock.                                   |
| `partial_portfolio_slice` | A COMBINATION report or confidential treatment can leave part of the portfolio outside the public filing.                            |
| `quantity_type_sh_prn`    | `SH` is shares; `PRN` is principal amount.                                                                                           |

## Ownership filings and written briefs

| Code                          | How to read it                                                                                                                        |
| ----------------------------- | ------------------------------------------------------------------------------------------------------------------------------------- |
| `ownership_events_not_census` | 13D/13G rows are filing events about a company, not a current-holder census or company-indexed 13F data.                              |
| `schedule_13d_vs_13g`         | A 13G uses a qualifying short-form certification; a 13D does not. The form alone does not prove activism, stake direction, or motive. |
| `ownership_events_capped`     | Up to 20 filings are checked. If more fall inside the window, the read is refused uncharged instead of serving a partial count.       |
| `regime_aware_cadence`        | Expected cadence follows the issuer's reporting regime, including foreign filers.                                                     |
| `no_recommendation`           | The brief cannot add a recommendation, verdict, or inferred motive.                                                                   |
| `ai_synthesis`                | The brief is generated from the structured data in the response. If they conflict, use the structured data.                           |

## Form 144 proposed sales

| Code                                    | How to read it                                                                                                                               |
| --------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------- |
| `form_144_is_a_notice_not_a_trade`      | A Form 144 announces a proposed sale. It does not prove that a sale happened.                                                                |
| `form_144_value_is_filer_estimate`      | The value is the filer's estimate at notice time, not an executed price or Otto calculation.                                                 |
| `form_144_latest_n_window`              | The response returns the latest 20 notices inside its lookback and discloses the window and truncation.                                      |
| `form_144_totals_withheld_on_amendment` | A 144/A makes aggregate unit and value totals null because the amendment cannot be safely paired to the original. Individual notices remain. |
| `form_144_other_issuer_excluded`        | Notices about a different issuer are excluded after checking the filing cover page, with the count disclosed.                                |

## Cross-issuer Form 4 feed

| Code                                    | How to read it                                                                                                                    |
| --------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------- |
| `feed_is_a_recency_slice`               | The feed is a recent slice, not a census. Coverage distinguishes unresolved accessions from entries that had no usable accession. |
| `feed_no_table_i_transactions_excluded` | A filing with no Table I transaction produces no row. It may still contain Table I holdings or derivative activity.               |
| `feed_business_day_calendar`            | SEC filing days follow the business-day calendar. `meta.dataAsOf` is the newest filing's acceptance time.                         |

## Form 8-K material events

| Code                                         | How to read it                                                                                                              |
| -------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------- |
| `eight_k_item_codes_not_contents`            | The endpoint reports which item codes were filed and when. It does not extract the filing narrative or deal terms.          |
| `eight_k_item_codes_are_the_sec_taxonomy`    | Codes and titles come from the SEC taxonomy and retain EDGAR's order.                                                       |
| `eight_k_unknown_item_codes_are_not_guessed` | An unknown SEC code is returned with `title: null` and `known: false`.                                                      |
| `eight_k_earnings_excluded`                  | A filing containing only item 2.02 is excluded for `/earnings-flash`; 2.02 alongside another substantive item remains.      |
| `eight_k_event_date_vs_filing_date`          | `eventDate` is the reported event date; `filedAt` is when the SEC received the filing.                                      |
| `eight_k_amendments_not_merged`              | An 8-K/A is returned separately because EDGAR does not provide a safe pairing rule.                                         |
| `eight_k_latest_n_window`                    | At most 20 material-event filings are returned inside the stated lookback, with coverage disclosed.                         |
| `eight_k_index_reach_limited`                | If EDGAR's index does not reach the full lookback, `window.start` gives the actual start and coverage is marked incomplete. |

## Financial-statement reading rules

`/financial-statements` returns five annual and five quarterly periods for the income statement, balance sheet, and cash-flow statement, where filings support them.

* Every value names its XBRL concept and source filing. A directly filed cell is marked `filed`; a reconstructed quarter is `derived-from-cumulative`; the limited arithmetic lines are `computed` and name their operands.
* A later filing that changes a period sets `restated: true` and retains the earlier value in `priorValue`.
* A period not reported under the selected concept is null. Conflicting derivation paths are null with `withheld: "conflicting-filings"`.
* One concept is used across each line so periods stay comparable. Per-share and weighted-share figures are never reconstructed because they are not additive.
* Gross profit, when untagged, and free cash flow are the only computed lines. Balance-sheet values use the same period ends as the flow statements.
* A fund with no issuer XBRL, or a filer reporting only in a non-USD currency, returns `statementsAvailable: false` with a reason while the filing index remains available. Transient EDGAR failures do not replace a previous good result.
* The filing index includes periodic and current-report variants, including amendments, transitions, and foreign-filer forms. It returns the newest 40 matching rows and applies the same 8-K item-code rules above.

## Source and use

The filing source is [SEC EDGAR](https://www.sec.gov/edgar), whose filings are public records. Otto adds parsing, validation, coverage metadata, and, only where stated, generated synthesis. These endpoints provide research data, not investment advice.