Docs
PricingSupportSign Up

/screener/ownership

Full-library transaction screening. Trade-level conditions plus company-level aggregate gates; returns the matching transactions.

POST/api/v1/screener/ownership
Credits65–920Rate limit10 per minute

Request:

start_date, as_of_dateISO date

Window on transaction_date; as_of_date also excludes filings submitted after it. 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

trade_filtersobject

See Filters (/screener/ownership).

Default omitted

aggregate_filtersobject[]

≤ 8. Company-level gates — see Filters (/screener/ownership).

Default omitted

group_by_tickerbool

true → grouped by company. false → flat rows.

Default true

sort_bystring

Grouped: ticker, txn_count. Flat: transaction_date, filing_date, transaction_value, shares, price_per_share, own_pct_change, split_adjusted_shares, split_adjusted_price.

sort_order"desc" | "asc"

Default "desc"

pageint ≥ 1

Default 1

page_sizeint 1–100

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

Default 50

detailstring

"light" leaves out each row's footnote_refs and computed.*.fact_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.

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, txn_count (the company's full hit count), transactions.

transactions

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

anomalies_excluded_count

Transactions excluded by the consistency checks; 0 when trade_filters.include_anomalies=true.

credits_used, _warnings

Every row carries accession_number, filing_date, source_url_prefix, insiders, the transaction object, and computed.

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

#Filters (/screener/ownership)

trade_filters:

transaction_codestring[]

≤ 20. Unknown codes dropped with a warning.

relationshipstring[]

is_director, is_officer, is_ten_percent_owner, is_other. OR semantics.

is_derivativebool
principal_amount_not_sharesbool

Omit for no filter, true for debt-principal rows only, false to exclude them.

include_anomaliesbool

Default false.

exclude_likely_mergedbool

Default false.

include_unresolved_amendmentsbool

Default false.

conditionsobject[]

≤ 8. {field, op, value}. field ∈ transaction_value, price_per_share, shares, own_pct_change, split_adjusted_shares, split_adjusted_price.

aggregate_filters: {metric, op, value}, metric ∈ value_acquired, value_disposed, net_value, shares_acquired, shares_disposed, net_shares, txn_count, txn_count_acquired, txn_count_disposed, max_txn_value_acquired, max_txn_value_disposed, distinct_insiders.

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

#Credit formula (/screener/ownership)

POST /screener/ownership charges per call:

Formula
credits = max(65, 200
              − tickerDiscount        // 100 − min(n_tickers, 100); 0 when tickers is omitted
              − shortWindowDiscount   // 40 when the window is ≤ 90 days
              + fullHistorySurcharge  // 80 when start_date is omitted
              + 40 × conditions)      // trade conditions + aggregate filters

Range 65–920. Charged even when the result set is empty, and on 504 QUERY_TIMEOUT. No charge on 422 VALIDATION_ERROR, 402 CREDITS_INSUFFICIENT, or 403 PLAN_TIER_INSUFFICIENT (all rejected before any deduction).