| 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 |
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 house rules
We return null rather than guess. If a filing omits a value, the affected total isnull 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. |