/screener/initial-holdings

Full-library screening of initial holdings (Form 3). Holding-level conditions plus company-level aggregate gates; returns the matching holdings. Requires Pro or higher.

POST/api/v1/screener/initial-holdings

Credits65–920Rate limit10 per minute

Request:

start_date, as_of_dateISO date

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

tickers, exclude_tickersstring[]

≤ 100 each.

Default omitted

sectorsstring[]

The 12 canonical buckets (Industry classification (Pro+)).

Default omitted

holding_filtersobject

See below.

Default omitted

aggregate_filtersobject[]

≤ 8. Company-level gates — see below.

Default omitted

group_by_tickerbool

true → grouped by company. false → flat rows.

Default true

sort_bystring

Grouped: ticker, holdings_count, shares_owned_total. Flat: filing_date, shares_owned, split_adjusted_shares_owned, underlying_security_shares, conversion_or_exercise_price.

sort_order"desc" | "asc"

Default "desc"

pageint ≥ 1

Default 1

page_sizeint 1–100

Counts holdings in both modes: with group_by_ticker=true a page holds that many holdings, however few companies they come from.

Default 50

detailstring

"light" leaves out each row's footnote_refs and the start_date_applied echo; "minimal" also leaves out accession_number and company_id. See Response detail.

Default "full"

Pagination cap: page × page_size ≤ 500 (422 above it). When the next page would pass the cap, has_more is false, next_page is null, and _warnings says the limit was reached.

holding_filters:

relationshipstring[]

is_director, is_officer, is_ten_percent_owner, is_other. OR semantics.

is_derivativebool

direct_or_indirect"D" | "I"

include_anomaliesbool

Default false.

exclude_likely_mergedbool

Default false.

include_unresolved_amendmentsbool

Default false.

conditionsobject[]

≤ 8. {field, op, value}. field ∈ shares_owned, split_adjusted_shares_owned, underlying_security_shares, split_adjusted_underlying_security_shares, conversion_or_exercise_price.

aggregate_filters: {metric, op, value}, metric ∈ filing_count, no_securities_filing_count, distinct_insiders, holdings_count, shares_owned_total. filing_count and no_securities_filing_count count filings, including filings that report no holdings; holdings_count and shares_owned_total are measured on the matching holdings.

Operators (both filter types): >, >=, <, <=, between ([lo, hi], lo ≤ hi).

Response:

page, page_size, has_more, next_page

Pagination.

as_of_date_applied, start_date_applied

Window actually used.

results

group_by_ticker=true. Each entry: ticker, issuer, issuer_cik, holdings_count and shares_owned_total (the company's full hit values), holdings.

holdings

group_by_ticker=false. Flat rows, each additionally carrying ticker, issuer, issuer_cik and company_id.

anomalies_excluded_count

Holdings excluded by the consistency checks; 0 when holding_filters.include_anomalies=true.

credits_used, _warnings

Every row carries accession_number, filing_date, period_of_report, no_securities_owned, source_url_prefix, insiders, and the holding object.

Credits: the Credit formula (/screener/ownership) formula, with conditions = holding conditions + aggregate filters. Range 65–920.

Errors: 422 VALIDATION_ERROR, 402 CREDITS_INSUFFICIENT, 403 PLAN_TIER_INSUFFICIENT below Pro, 504 QUERY_TIMEOUT at the 30-second server timeout (charged).