> ## 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. # SEC Filing Endpoints — Methodology > How Otto reads SEC filings, what each caveat code means, and where we return null instead of guessing. Four Otto endpoints read SEC filings directly from EDGAR: | Endpoint | What it reads | | --------------------------- | ---------------------------------------------------------------- | | `/insider-trades` | Form 4 insider transactions for one company | | `/institutional-holdings` | Form 13F positions for one investment manager | | `/equity-smart-money` | Form 4 activity + reported fundamentals for one company | | `/equity-smart-money-brief` | The above, plus 13D/13G ownership filings, written up as a brief | Every response carries a one-line `note`, a machine-readable `caveats[]` array, and a `methodology` link back to this page. ## Why caveats are structured Each caveat is `{ code, plain, affects }`: * **`code`** — a stable key you can branch on in code. It does not change without a version bump. * **`plain`** — the caveat in plain English, for a human (or an LLM writing for one). * **`affects`** — the exact response fields the caveat governs, so you know *which numbers* it applies to instead of guessing. The point is that you can tell **when a number is safe to use**. A null is never silent, and a caveat always names the fields it touches. ## The house rules **We return null rather than guess.** If a filing omits a value, the affected total is `null` and a companion count tells you how many rows were missing it. A partial sum presented as a precise figure is a wrong number, and a wrong number is worse than no number. **We withhold rather than serve a figure we know is stale.** If the filing window contains an amendment, we withhold the whole window until the amendment ages out — and you are **not charged** for that call. Amendments restate only the corrected lines, so there is no safe way to automatically compose one; serving the superseded original would be quietly wrong. **We don't dress up what the filing doesn't say.** The clearest example: SEC codes `P` and `S` cover **both open-market and privately negotiated** transactions. The filing does not distinguish them, so we never label them "open-market" and never call them "conviction" buying. ## Caveat reference ### Shared | Code | Meaning | | ------------------------ | ----------------------------------------------------------------------------------------------------------------------------- | | `hourly_snapshot` | An hourly snapshot of filings, not a live feed. Freshness is in `meta.generatedAt`. | | `amendment_withheld` | A window containing an amendment is withheld until it ages out. That call is not charged. Detection can lag by about an hour. | | `nulls_over_fabrication` | Missing values null the affected total instead of being estimated. Companion counts tell you how many rows were missing. | ### Insider transactions (Form 4) | Code | Meaning | | -------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `non_derivative_only` | Only non-derivative rows (Table I) — the shares themselves. An option *exercise* still shows as code `M`. | | `owner_side_excluded` | Filings where this company reports owning a stake in a *different* company are excluded, and counted in `coverage.filingsSkippedOwnerSide`. | | `purchase_sale_codes` | Purchases and sales are codes `P` and `S`, which cover open-market **and** private transactions. | | `mixed_security_classes` | Share totals only add within one class of stock. If the window mixes classes, share totals are null and `distinctSecurityTitles` tells you how many appeared. | | `filing_level_attribution` | `filedBy` / `filerRoles` describe who *filed*, not who owns each row. Per-row ownership is the row's own direct/indirect field. | | `transaction_code_legend` | `P` purchase · `S` sale · `A` award/grant · `G` gift · `M` option exercise · `F` shares withheld for tax. | ### Fundamentals (XBRL) | Code | Meaning | | --------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `ttm_where_reconstructable` | Trailing-twelve-month figures where the quarterlies allow it; otherwise the annual figure, with the basis labelled. | | `yoy_positive_prior_only` | A year-over-year percentage appears only when the prior period was positive. When the sign flips, `netIncomeTransition` names the transition in words — a percentage there would be meaningless. | | `one_time_items_ttm_only` | Impairments, restructuring, and disposals are screened on the TTM basis only. | ### Institutional holdings (13F) | Code | Meaning | | ------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------- | | `as_reported_by_manager` | Reproduced as filed, not independently audited. | | `quarterly_rear_view` | A 13F can be filed up to 45 days after quarter end. It is a rear-view mirror, not live positioning. | | `amendments_composed` | Restatements replace; new-holdings amendments append. Each filing is unit-normalized by its own date (pre-2023 filings report thousands). | | `options_are_underlying` | A row with a put/call flag is an **option**: value and quantity describe the underlying shares, not the premium. Never read it as long stock. | | `partial_portfolio_slice` | A COMBINATION report type, or confidential treatment, means the rows and total cover only the publicly reported slice of the book. | | `quantity_type_sh_prn` | `quantity` is a share count only when `quantityType` is `SH`. `PRN` means a principal amount. | ### Ownership filings and the written brief | Code | Meaning | | ----------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `ownership_events_not_census` | The ownership section lists 13D/13G filing **events** about this company, each validated against the filing's own cover page. It is not a census of holders, and not 13F data — EDGAR indexes 13F by manager, not by company. The schedule type alone tells you neither the filer's type, nor their intent, nor the direction of their stake. | | `regime_aware_cadence` | Expected filing cadence adapts to the reporting regime (a 10-K filer files more often than a 20-F/40-F filer), so a "missing" filing is judged against the right calendar. | | `no_recommendation` | The brief describes what the filings show. Recommendation, verdict, and motive language is rejected before the brief is ever served. | | `ai_synthesis` | The prose is AI-written from the structured data in the same response. **The structured numbers are the source of truth** — if the two ever disagree, trust the numbers. | ## Source and licensing All four endpoints read **public-domain SEC EDGAR** data. Otto adds parsing, validation, and (for the brief) synthesis. Nothing here is investment advice.