Docs
PricingSupportSign Up

/ownership/initial-holdings/stats

Aggregate statistics over the Form 3 filings of one company and/or one insider, plus the ids of every holding that contributed.

POST/api/v1/ownership/initial-holdings/stats
Rate limit120 per minute

Request:

tickerstring
cikstring

The company's CIK, instead of ticker.

insider_cikstring
start_date, as_of_dateISO date

Window on filing_date. as_of_date ≤ today; start_date ≤ as_of_date.

include_anomaliesbool

Default false

relationshipstring[]

Any of is_director, is_officer, is_ten_percent_owner, is_other. OR semantics, evaluated per filing.

Default omitted

is_derivativebool

Restricts the holding totals; filing counts are unaffected.

Default omitted

exclude_likely_mergedbool

Default false

include_unresolved_amendmentsbool

Default false

ids_pageint ≥ 1

Paginates holding_ids only.

Default 1

ids_page_sizeint 1–1000

Default 200

detailstring

"light" leaves out the start_date_applied echo. See Response detail.

Default "full"

At least one of ticker / cik / insider_cik is required, and not both ticker and cik.

Response: stats, start_date_applied, as_of_date_applied, anomalies_excluded_count, credits_used, optional corporate_actions, optional _warnings, then ids_page, ids_has_more, ids_next_page (null on the last page), holding_ids.

filing_count

Form 3 filings in scope.

no_securities_filing_count

Of those, filings that report no holdings.

distinct_insiders

Distinct reporting owners in scope.

filings_with_multiple_filers

Joint filings in scope.

holdings_count, holdings_count_non_derivative, holdings_count_derivative

Holding rows in scope.

shares_owned_total

Sum of shares_owned over non-derivative rows, on the split-adjusted basis.

underlying_shares_total

Sum of underlying_security_shares over derivative rows, on the split-adjusted basis.

earliest_filing_date, latest_filing_date

Range actually covered.

corporate_action_crossing

true when the window spans a corporate action.

corporate_actions is present when the request names a company (ticker or cik) that has corporate actions on file, except with detail="minimal": an array of {ex_date, ratio, type, event_type}.

_warnings names the count and the parameter that changes it whenever holdings were excluded.

Credits: 40 base, plus ceil(n / 1000) × 5 where n is the number of participating holdings. Both charges are recorded as one usage entry.

Errors: 404 OWNERSHIP_COMPANY_NOT_FOUND (charged), 403 PLAN_TIER_INSUFFICIENT_COVERAGE when the company is outside your plan's coverage scope (charged), 422 VALIDATION_ERROR, 402 CREDITS_INSUFFICIENT.