/ownership/stats

Aggregate statistics over one company and/or one insider, plus the ids of every transaction that contributed.

POST/api/v1/ownership/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 transaction_date; as_of_date also excludes filings submitted after it. as_of_date ≤ today; start_date ≤ as_of_date.

transaction_codestring[]

≤ 20 entries.

Default omitted

method"ad" | "ps"

ad splits on acquired_disposed_code. ps treats P as a buy and S as a sell, and narrows the scope to those two codes.

Default "ad"

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

Default omitted

exclude_likely_mergedbool

Default false

include_unresolved_amendmentsbool

Default false

ids_pageint ≥ 1

Paginates transaction_ids only.

Default 1

ids_page_sizeint 1–1000

Default 200

detailstring

"light" leaves out the method_applied and start_date_applied echoes. See Response detail.

Default "full"

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

Response: stats, method_applied, 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), transaction_ids.

Key names inside stats follow method: acquired / disposed for ad, bought / sold for ps.

value_acquired, value_disposed, net_value

Cash value totals. Transactions with no cash value contribute 0.

shares_acquired, shares_disposed, net_shares

Share totals on the split-adjusted basis, excluding rows where principal_amount_not_shares is true.

avg_price_acquired, avg_price_disposed

Total value ÷ total split-adjusted shares over the transactions that have a cash value, on the same basis as shares_*. null when there are none.

txn_count, txn_count_acquired, txn_count_disposed

Counts.

txn_count_with_value

Transactions carrying a non-zero cash value.

no_value_txn_count

Transactions with no cash value.

ad_code_missing_count

Transactions counted in neither direction.

principal_amount_txn_count

Debt-principal rows excluded from shares_* and avg_price_*.

distinct_insiders

Distinct reporting owners in scope.

filings_with_multiple_filers

Joint filings in scope.

max_txn_value_acquired, max_txn_value_disposed

Largest single transaction per side. null when the side is empty.

avg_value_per_txn_acquired, avg_value_per_txn_disposed

Mean over transactions that have a cash value.

earliest_transaction_date, latest_transaction_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 transactions were excluded, skipped, or carry no value.

Credits: 40 base, plus ceil(n / 1000) × 5 where n is the number of participating transactions. 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.