Resources
Each filing family is an attribute on the client (client.insiders,
client.filings, ...). List methods return one raw page as a dict; the
iter*() variants follow pagination and yield rows. See the
pagination guide for how the two relate.
Master index
py3spread.resources.Filings
Filings(client: 'Client')
Bases: Resource
Cross-cutting master filings index.
list
list(*, cik: str | None = None, ticker: str | None = None, form_type: str | None = None, sic: str | None = None, is_valid: bool | None = None, accepted_start: str | None = None, accepted_end: str | None = None, limit: int | None = None, cursor: str | None = None) -> dict[str, Any]
One page of the filings index. Needs an identity filter or a bounded window.
iter
iter(**filters: Any) -> Iterator[dict[str, Any]]
Iterate filings across pages. Same filters as list().
Insiders (Forms 3, 4, 5)
py3spread.resources.Insiders
Insiders(client: 'Client')
Bases: Resource
Forms 3, 4, 5: insider beneficial ownership filings.
list
list(*, cik: str | None = None, ticker: str | None = None, issuer_cik: str | None = None, form_type: str | None = None, is_amendment: bool | None = None, period_start: str | None = None, period_end: str | None = None, accepted_start: str | None = None, accepted_end: str | None = None, role: str | None = None, limit: int | None = None, cursor: str | None = None) -> dict[str, Any]
One page of insider filings. Needs an identity filter or a bounded window.
iter
iter(**filters: Any) -> Iterator[dict[str, Any]]
Iterate insider filings across pages. Same filters as list().
get
get(filing_id: str) -> dict[str, Any]
Full detail for one filing, with all reporting owners and transactions.
transactions
transactions(*, transaction_kind: str | None = None, issuer_cik: str | None = None, issuer_ticker: str | None = None, rpt_owner_cik: str | None = None, transaction_code: str | None = None, transaction_acquired_disposed_code: str | None = None, transaction_start: str | None = None, transaction_end: str | None = None, min_value: float | str | None = None, max_value: float | str | None = None, role: str | None = None, limit: int | None = None, offset: int | None = None) -> dict[str, Any]
One page of the cross-filing transaction stream.
Requires an identity filter (issuer_cik, issuer_ticker, or rpt_owner_cik) plus transaction_start and/or transaction_end. A single bound gives a 1-day window; both bounds allow up to 730 days.
iter_transactions
iter_transactions(**filters: Any) -> Iterator[dict[str, Any]]
Iterate transactions across pages. Same filters as transactions().
owners
owners(rpt_owner_cik: str, *, limit: int | None = None, offset: int | None = None, sort: str | None = None, order: str | None = None) -> dict[str, Any]
Filings by one reporting owner.
biography
biography(rpt_owner_cik: str) -> dict[str, Any]
Reporting-owner biography.
buy_sell_ratio
buy_sell_ratio(*, cik: str | None = None, ticker: str | None = None, sic: str | None = None, window_days: int | None = None) -> dict[str, Any]
Buy/sell ratio over a trailing window.
entities
entities(*, limit: int | None = None, offset: int | None = None, search: str | None = None, sort: str | None = None, order: str | None = None) -> dict[str, Any]
Issuer rollup. Accepts limit, offset, search, sort, order.
Institutional holdings (13F)
py3spread.resources.InstitutionalHoldings
InstitutionalHoldings(client: 'Client')
Bases: Resource
Form 13F: institutional investment manager quarterly holdings.
list
list(*, cik: str | None = None, ticker: str | None = None, filing_manager_cik: str | None = None, report_type: str | None = None, is_amendment: bool | None = None, period_start: str | None = None, period_end: str | None = None, accepted_start: str | None = None, accepted_end: str | None = None, limit: int | None = None, cursor: str | None = None) -> dict[str, Any]
One page of 13F filings. Needs an identity filter or a bounded window.
iter
iter(**filters: Any) -> Iterator[dict[str, Any]]
Iterate 13F filings across pages. Same filters as list().
get
get(filing_id: str) -> dict[str, Any]
Full detail for one 13F filing.
holdings
holdings(*, cusip: str | None = None, name_of_issuer: str | None = None, filing_manager_cik: str | None = None, filing_id: str | None = None, period_start: str | None = None, period_end: str | None = None, period: str | None = None, min_value: float | str | None = None, limit: int | None = None, offset: int | None = None, sort: str | None = None, order: str | None = None) -> dict[str, Any]
One page of the cross-filing holdings stream.
iter_holdings
iter_holdings(**filters: Any) -> Iterator[dict[str, Any]]
Iterate holdings across pages. Same filters as holdings().
Private offerings (Form D)
py3spread.resources.PrivateOfferings
PrivateOfferings(client: 'Client')
Bases: Resource
Form D: Regulation D exempt offering notices.
list
list(*, cik: str | None = None, ticker: str | None = None, is_amendment: bool | None = None, industry_group_type: str | None = None, investment_fund_type: str | None = None, min_offering_amount: float | str | None = None, max_offering_amount: float | str | None = None, min_amount_sold: float | str | None = None, max_amount_sold: float | str | None = None, accepted_start: str | None = None, accepted_end: str | None = None, period_start: str | None = None, period_end: str | None = None, limit: int | None = None, cursor: str | None = None) -> dict[str, Any]
One page of Form D filings. Needs an identity filter or a bounded window.
iter
iter(**filters: Any) -> Iterator[dict[str, Any]]
Iterate Form D filings across pages. Same filters as list().
get
get(filing_id: str, *, include_form_data: bool | None = None) -> dict[str, Any]
Full detail for one Form D filing.
entities
entities(*, limit: int | None = None, offset: int | None = None, search: str | None = None, sort: str | None = None, order: str | None = None) -> dict[str, Any]
Filer rollup. Accepts limit, offset, search, sort, order.
Fund portfolios (N-PORT)
py3spread.resources.FundPortfolios
FundPortfolios(client: 'Client')
Bases: Resource
Form N-PORT: registered investment company monthly portfolio holdings.
list
list(*, registrant_cik: str | None = None, series_id: str | None = None, class_id: str | None = None, is_confidential: bool | None = None, is_final_filing: bool | None = None, report_period_start: str | None = None, report_period_end: str | None = None, accepted_start: str | None = None, accepted_end: str | None = None, limit: int | None = None, offset: int | None = None, sort: str | None = None, order: str | None = None) -> dict[str, Any]
One page of N-PORT filings (offset paged).
iter
iter(**filters: Any) -> Iterator[dict[str, Any]]
Iterate N-PORT filings across pages. Same filters as list().
get
get(filing_id: str, *, include_form_data: bool | None = None) -> dict[str, Any]
Full detail for one N-PORT filing.
holdings
holdings(*, cusip: str | None = None, isin: str | None = None, lei: str | None = None, name: str | None = None, registrant_cik: str | None = None, filing_id: str | None = None, series_id: str | None = None, asset_cat: str | None = None, issuer_cat: str | None = None, inv_country: str | None = None, min_val_usd: float | str | None = None, is_restricted_sec: bool | None = None, fair_val_level: int | None = None, period_start: str | None = None, period_end: str | None = None, period: str | None = None, limit: int | None = None, offset: int | None = None, sort: str | None = None, order: str | None = None) -> dict[str, Any]
One page of the cross-filing holdings stream.
iter_holdings
iter_holdings(**filters: Any) -> Iterator[dict[str, Any]]
Iterate holdings across pages. Same filters as holdings().
entities
entities(*, limit: int | None = None, offset: int | None = None, search: str | None = None, sort: str | None = None, order: str | None = None) -> dict[str, Any]
Registrant rollup. Accepts limit, offset, search, sort, order.
Beneficial ownership (13D/13G)
py3spread.resources.BeneficialOwnership
BeneficialOwnership(client: 'Client')
Bases: Resource
Schedule 13D / 13G: 5%+ beneficial ownership reports.
list
list(*, cik: str | None = None, ticker: str | None = None, schedule_type: str | None = None, issuer_cusip: str | None = None, issuer_name: str | None = None, amendment_no: str | None = None, event_date_start: str | None = None, event_date_end: str | None = None, accepted_start: str | None = None, accepted_end: str | None = None, limit: int | None = None, cursor: str | None = None) -> dict[str, Any]
One page of 13D/13G filings. Needs an identity filter or a bounded window.
iter
iter(**filters: Any) -> Iterator[dict[str, Any]]
Iterate 13D/13G filings across pages. Same filters as list().
get
get(filing_id: str) -> dict[str, Any]
Full detail for one 13D/13G filing.
entities
entities(*, limit: int | None = None, offset: int | None = None, search: str | None = None, sort: str | None = None, order: str | None = None) -> dict[str, Any]
Filer rollup. Accepts limit, offset, search, sort, order.
Proposed sales (Form 144)
py3spread.resources.ProposedSales
ProposedSales(client: 'Client')
Bases: Resource
Form 144: notices of proposed sale under Rule 144.
list
list(*, cik: str | None = None, ticker: str | None = None, issuer_cik: str | None = None, seller_name: str | None = None, broker_name: str | None = None, securities_class_title: str | None = None, min_aggregate_market_value: float | str | None = None, max_aggregate_market_value: float | str | None = None, min_units_sold: float | str | None = None, max_units_sold: float | str | None = None, nothing_to_report_past_3_months: bool | None = None, approx_sale_start: str | None = None, approx_sale_end: str | None = None, accepted_start: str | None = None, accepted_end: str | None = None, limit: int | None = None, cursor: str | None = None) -> dict[str, Any]
One page of Form 144 filings. Needs an identity filter or a bounded window.
iter
iter(**filters: Any) -> Iterator[dict[str, Any]]
Iterate Form 144 filings across pages. Same filters as list().
get
get(filing_id: str) -> dict[str, Any]
Full detail for one Form 144 filing.
entities
entities(*, limit: int | None = None, offset: int | None = None, search: str | None = None, sort: str | None = None, order: str | None = None) -> dict[str, Any]
Issuer rollup. Accepts limit, offset, search, sort, order.
Fund census (N-CEN)
py3spread.resources.FundCensus
FundCensus(client: 'Client')
Bases: Resource
Form N-CEN: annual investment company census reports.
list
list(*, cik: str | None = None, ticker: str | None = None, registrant_cik: str | None = None, registrant_lei: str | None = None, investment_company_type: str | None = None, is_report_period_lt_12: bool | None = None, period_start: str | None = None, period_end: str | None = None, accepted_start: str | None = None, accepted_end: str | None = None, limit: int | None = None, cursor: str | None = None) -> dict[str, Any]
One page of N-CEN filings. Needs an identity filter or a bounded window.
iter
iter(**filters: Any) -> Iterator[dict[str, Any]]
Iterate N-CEN filings across pages. Same filters as list().
get
get(filing_id: str, *, include_form_data: bool | None = None) -> dict[str, Any]
Full detail for one N-CEN filing.
entities
entities(*, limit: int | None = None, offset: int | None = None, search: str | None = None, sort: str | None = None, order: str | None = None) -> dict[str, Any]
Registrant rollup. Accepts limit, offset, search, sort, order.
Money market funds (N-MFP)
py3spread.resources.MoneyMarketFunds
MoneyMarketFunds(client: 'Client')
Bases: Resource
Form N-MFP2: money market fund monthly portfolio reports.
list
list(*, cik: str | None = None, ticker: str | None = None, registrant_cik: str | None = None, series_id: str | None = None, money_market_fund_category: str | None = None, is_final_filing: bool | None = None, feeder_fund_flag: bool | None = None, master_fund_flag: bool | None = None, retail_money_market_fund_flag: bool | None = None, period_start: str | None = None, period_end: str | None = None, accepted_start: str | None = None, accepted_end: str | None = None, limit: int | None = None, cursor: str | None = None) -> dict[str, Any]
One page of N-MFP2 filings. Needs an identity filter or a bounded window.
iter
iter(**filters: Any) -> Iterator[dict[str, Any]]
Iterate N-MFP2 filings across pages. Same filters as list().
get
get(filing_id: str, *, include_form_data: bool | None = None) -> dict[str, Any]
Full detail for one N-MFP2 filing.
securities
securities(*, cusip_member: str | None = None, isin_id: str | None = None, lei_id: str | None = None, name_of_issuer: str | None = None, registrant_cik: str | None = None, filing_id: str | None = None, investment_category: str | None = None, security_eligibility_flag: str | None = None, daily_liquid_asset_security_flag: bool | None = None, weekly_liquid_asset_security_flag: bool | None = None, illiquid_security_flag: bool | None = None, min_value: float | str | None = None, period_start: str | None = None, period_end: str | None = None, limit: int | None = None, offset: int | None = None, sort: str | None = None, order: str | None = None) -> dict[str, Any]
One page of the cross-filing securities stream.
iter_securities
iter_securities(**filters: Any) -> Iterator[dict[str, Any]]
Iterate securities across pages. Same filters as securities().
series_nav
series_nav(*, registrant_cik: str | None = None, series_id: str | None = None, filing_id: str | None = None, date_start: str | None = None, date_end: str | None = None, granularity: str | None = None, limit: int | None = None, offset: int | None = None, sort: str | None = None, order: str | None = None) -> dict[str, Any]
Series-level NAV series. No classes_id — that is class-level only.
liquid_assets
liquid_assets(*, registrant_cik: str | None = None, series_id: str | None = None, filing_id: str | None = None, date_start: str | None = None, date_end: str | None = None, granularity: str | None = None, limit: int | None = None, offset: int | None = None, sort: str | None = None, order: str | None = None) -> dict[str, Any]
Series-level liquid-assets series. Same filters as series_nav().
class_nav
class_nav(*, registrant_cik: str | None = None, series_id: str | None = None, classes_id: str | None = None, filing_id: str | None = None, date_start: str | None = None, date_end: str | None = None, granularity: str | None = None, limit: int | None = None, offset: int | None = None, sort: str | None = None, order: str | None = None) -> dict[str, Any]
Class-level NAV series. Same filters as series_nav() plus classes_id.
class_flows
class_flows(*, registrant_cik: str | None = None, series_id: str | None = None, classes_id: str | None = None, filing_id: str | None = None, date_start: str | None = None, date_end: str | None = None, granularity: str | None = None, limit: int | None = None, offset: int | None = None, sort: str | None = None, order: str | None = None) -> dict[str, Any]
Class-level subscriptions/redemptions series. Same filters as class_nav().
entities
entities(*, limit: int | None = None, offset: int | None = None, search: str | None = None, sort: str | None = None, order: str | None = None) -> dict[str, Any]
Registrant rollup. Accepts limit, offset, search, sort, order.
Proxy votes (N-PX)
py3spread.resources.ProxyVotes
ProxyVotes(client: 'Client')
Bases: Resource
Form N-PX: annual proxy voting record reports.
list
list(*, cik: str | None = None, ticker: str | None = None, report_type: str | None = None, report_calendar_year: int | None = None, is_amendment: bool | None = None, confidential_treatment: bool | None = None, registrant_type: str | None = None, accepted_start: str | None = None, accepted_end: str | None = None, limit: int | None = None, cursor: str | None = None) -> dict[str, Any]
One page of N-PX filings. Needs an identity filter or a bounded window.
iter
iter(**filters: Any) -> Iterator[dict[str, Any]]
Iterate N-PX filings across pages. Same filters as list().
get
get(filing_id: str, *, include_form_data: bool | None = None) -> dict[str, Any]
Full detail for one N-PX filing, with vote records.
entities
entities(*, limit: int | None = None, offset: int | None = None, search: str | None = None, sort: str | None = None, order: str | None = None) -> dict[str, Any]
Fund rollup. Accepts limit, offset, search, sort, order.
Reg A+ offerings
py3spread.resources.RegAOfferings
RegAOfferings(client: 'Client')
Bases: Resource
Regulation A+ offerings: Forms 1-A / 1-K / 1-U / 1-Z.
list
list(*, cik: str | None = None, ticker: str | None = None, tier: str | None = None, audit_status: str | None = None, issuer_industry_group: str | None = None, jurisdiction_of_organization: str | None = None, min_aggregate_offering: float | str | None = None, max_aggregate_offering: float | str | None = None, min_total_assets: float | str | None = None, max_total_assets: float | str | None = None, accepted_start: str | None = None, accepted_end: str | None = None, limit: int | None = None, cursor: str | None = None) -> dict[str, Any]
One page of Reg A+ offerings. Needs an identity filter or a bounded window.
iter
iter(**filters: Any) -> Iterator[dict[str, Any]]
Iterate Reg A+ offerings across pages. Same filters as list().
get
get(filing_id: str) -> dict[str, Any]
Full detail for one Reg A+ filing.
entities
entities(*, limit: int | None = None, offset: int | None = None, search: str | None = None, sort: str | None = None, order: str | None = None) -> dict[str, Any]
Issuer rollup. Accepts limit, offset, search, sort, order.
Registration statements
py3spread.resources.RegistrationStatements
RegistrationStatements(client: 'Client')
Bases: Resource
Registration statements with pre-segmented text sections.
list
list(*, cik: str | None = None, ticker: str | None = None, form_type: str | None = None, is_valid: bool | None = None, period_start: str | None = None, period_end: str | None = None, accepted_start: str | None = None, accepted_end: str | None = None, limit: int | None = None, offset: int | None = None, sort: str | None = None, order: str | None = None) -> dict[str, Any]
One page of registration statements (offset paged).
iter
iter(**filters: Any) -> Iterator[dict[str, Any]]
Iterate registration statements across pages. Same filters as list().
get
get(filing_id: str) -> dict[str, Any]
Full detail for one registration statement.
sections
sections(*, filing_id: str | None = None, cik: str | None = None, ticker: str | None = None, form_type: str | None = None, section_title: str | None = None, min_text_length: int | None = None, max_text_length: int | None = None, period_start: str | None = None, period_end: str | None = None, accepted_start: str | None = None, accepted_end: str | None = None, include_text: bool | None = None, limit: int | None = None, offset: int | None = None, sort: str | None = None, order: str | None = None) -> dict[str, Any]
One page of the sections stream.
iter_sections
iter_sections(**filters: Any) -> Iterator[dict[str, Any]]
Iterate sections across pages. Same filters as sections().
get_section
get_section(section_id: str) -> dict[str, Any]
One text section by UUID.
entities
entities(*, limit: int | None = None, offset: int | None = None, search: str | None = None, sort: str | None = None, order: str | None = None) -> dict[str, Any]
Issuer rollup. Accepts limit, offset, search, sort, order.
Financials (10-K / 10-Q)
py3spread.resources.Financials
Financials(client: 'Client')
Bases: Resource
Financial statements, metrics, ratios, and quant factors from 10-K/10-Q filings.
This family is not part of the FAMILIES changefeed enum — it has its
own discovery and detail endpoints rather than fitting the filing-family
list/iter/get pattern. version is required on the series endpoints
(statements, metrics, ratios, factors): pass "latest",
"original", or "as_of:YYYY-MM-DD".
list
list(*, cik: str | None = None, ticker: str | None = None, form_type: str | None = None, fiscal_year: int | None = None, is_valid: bool | None = None, accepted_start: str | None = None, accepted_end: str | None = None, limit: int | None = None, cursor: str | None = None) -> dict[str, Any]
One page of validated 10-K / 10-Q filings. Needs cik/ticker or a bounded window.
iter
iter(**filters: Any) -> Iterator[dict[str, Any]]
Iterate financials filings across pages. Same filters as list().
get
get(filing_id: str) -> dict[str, Any]
The filing plus every block it reported, including comparative columns.
statements
statements(*, version: str, cik: str | None = None, ticker: str | None = None, statement_type: str | None = None, fiscal_year: int | None = None, fiscal_quarter: int | None = None, period_length: int | None = None, fiscal_year_start: int | None = None, fiscal_year_end: int | None = None, is_valid: bool | None = None, derived: bool | None = None, limit: int | None = None, cursor: str | None = None) -> dict[str, Any]
One page of validated statement blocks (bs / inc / cf).
version is required: "latest", "original", or
"as_of:YYYY-MM-DD".
iter_statements
iter_statements(**filters: Any) -> Iterator[dict[str, Any]]
Iterate statement blocks across pages. Same filters as statements().
get_statement
get_statement(block_id: str) -> dict[str, Any]
Point read of a single statement block by UUID.
metrics
metrics(*, version: str, cik: str | None = None, ticker: str | None = None, category: str | None = None, statement_type: str | None = None, currency: str | None = None, fiscal_year: int | None = None, fiscal_quarter: int | None = None, period_length: int | None = None, fiscal_year_start: int | None = None, fiscal_year_end: int | None = None, min_value: float | str | None = None, max_value: float | str | None = None, is_valid: bool | None = None, derived: bool | None = None, sort: str | None = None, order: str | None = None, limit: int | None = None, cursor: str | None = None) -> dict[str, Any]
One page of canonical line-item metrics as a time-series.
Requires cik or ticker. version is required.
iter_metrics
iter_metrics(**filters: Any) -> Iterator[dict[str, Any]]
Iterate metrics across pages. Same filters as metrics().
ratios
ratios(*, version: str, cik: str | None = None, ticker: str | None = None, ratio_name: str | None = None, ratio_category: str | None = None, spine: str | None = None, fiscal_year: int | None = None, fiscal_quarter: int | None = None, period_length: int | None = None, fiscal_year_start: int | None = None, fiscal_year_end: int | None = None, min_value: float | str | None = None, max_value: float | str | None = None, include_low_materiality: bool | None = None, derived: bool | None = None, sort: str | None = None, order: str | None = None, limit: int | None = None, cursor: str | None = None) -> dict[str, Any]
One page of precomputed ratio time-series.
Requires cik or ticker. version is required.
iter_ratios
iter_ratios(**filters: Any) -> Iterator[dict[str, Any]]
Iterate ratios across pages. Same filters as ratios().
ratio_names
ratio_names() -> dict[str, Any]
The canonical ratio_name vocabulary (31 taxonomy-defined keys).
factors
factors(*, version: str, cik: str | None = None, ticker: str | None = None, factor_name: str | None = None, period_type: str | None = None, spine: str | None = None, fiscal_year: int | None = None, fiscal_year_start: int | None = None, fiscal_year_end: int | None = None, period_end: str | None = None, value_min: float | str | None = None, value_max: float | str | None = None, pctile_min: float | str | None = None, pctile_max: float | str | None = None, sort: str | None = None, order: str | None = None, limit: int | None = None, latest_only: bool | None = None, cursor: str | None = None) -> dict[str, Any]
One page of the quant factor library (90 factors).
Two modes: per-entity series (pass cik/ticker) or cross-company screen
(omit identity, pass factor_name + period). version is required.
iter_factors
iter_factors(**filters: Any) -> Iterator[dict[str, Any]]
Iterate factors across pages. Same filters as factors().
factor_names
factor_names() -> dict[str, Any]
The 90-key factor vocabulary.
factor_percentile
factor_percentile(*, factor_name: str, period_end: str, as_of: str, cik: str | None = None, ticker: str | None = None, period_type: str | None = None) -> dict[str, Any]
Dynamic point-in-time percentile rank for one factor / period / as-of date.
factor_name, period_end, and as_of are required.
categories
categories() -> dict[str, Any]
The canonical metric category vocabulary (177 taxonomy-defined keys).
Entities
py3spread.resources.Entities
Entities(client: 'Client')
Bases: Resource
Master CIK directory.
get
get(cik: str) -> dict[str, Any]
Registry metadata for one CIK (person or company).
Coverage
py3spread.resources.Coverage
Coverage(client: 'Client')
Bases: Resource
What does 3spread know, and how fresh is it.
by_issuer
by_issuer(cik_or_ticker: str) -> dict[str, Any]
Per-family coverage matrix for a single issuer.
by_family
by_family() -> dict[str, Any]
Global per-family coverage aggregates.
intake
intake(*, period: str | None = None, lookback_days: int | None = None) -> dict[str, Any]
Filing intake histogram.
data_as_of
data_as_of() -> dict[str, Any]
Per-family freshness snapshot.
Changes
py3spread.resources.Changes
Changes(client: 'Client')
Bases: Resource
Per-family changefeed over accepted_time.
list
list(family: str, *, since: str | None = None, until: str | None = None, limit: int | None = None, offset: int | None = None, order: str | None = None, cursor: str | None = None) -> dict[str, Any]
One page of change events for a family (see FAMILIES).
The changefeed is cursor-walked (see iter()); offset is the spec's alternate paginator on /v1/changes/{family} and is accepted here for completeness (omitted from the query when None).
iter
iter(family: str, **filters: Any) -> Iterator[dict[str, Any]]
Iterate change events across pages. Same filters as list().