Filings and financials

The filings index and XBRL financial-statement facts as registrants filed them with the SEC, as known now or at an earlier instant. How a period's value is chosen among its filed assertions is on How filed values are resolved.

Routes

what	route
the filings index	GET /v1/securities/{symbol}/filings
financial-statement facts	GET /v1/securities/{symbol}/financials
insider transactions	GET /v1/securities/{symbol}/insider-transactions (Insider transactions)
institutional holdings	GET /v1/securities/{symbol}/institutional-holders (Institutional holdings)

curl "https://api.tauric.ai/v1/securities/AAPL/filings?form=10-K&limit=2" \
  -H "Authorization: Bearer $TAURIC_API_KEY"
curl "https://api.tauric.ai/v1/securities/AAPL/financials?concepts=us-gaap:NetIncomeLoss&period_type=annual&limit=4" \
  -H "Authorization: Bearer $TAURIC_API_KEY"

The last four quarters of revenue:

curl "https://api.tauric.ai/v1/securities/AAPL/financials?concepts=us-gaap:RevenueFromContractWithCustomerExcludingAssessedTax&period_type=quarterly&limit=4" \
  -H "Authorization: Bearer $TAURIC_API_KEY"

From Python: Python examples. A security whose issuer has no linked SEC registrant answers 404 not_supported, and its datasets do not list these.

The financials answer

Units and the instrument block

Both routes carry the shared instrument block; its currency and price_scale describe the listing's quotation. Each financial value is in its concept's own unit: the filing's reporting unit, exact and never rescaled.

Pagination and periods

limit and offset count values per concept, newest period first; each concept states values_total and has_more (Pagination). On the default set, each concept serves its newest value: offset continues it, or name the concepts and raise limit.

period_type filters on each value's period_class; the default, all, serves every class.

period_type and period_class	meaning
annual	a registrant fiscal year
ttm	a trailing twelve months ending between fiscal-year ends, as some registrants state in a 10-Q
quarterly	a period of about three months: a fiscal quarter
ytd	a period of about six or nine months: a year-to-date window an interim report states
instant	a balance-sheet date (no duration)
other	any other duration, such as a transition period
all (period_type only, the default)	every class

Under annual or quarterly, a balance-sheet (instant) value is also served when its date is that fiscal period's end. Newer balance-sheet dates at no fiscal period end are listed in the concept's instants_unplaced (present only when non-empty); ask with period_type=instant to read them.

Concepts and the registrant scope

Concepts are named taxonomy:Name (us-gaap:Revenues).

Every concept states fact_scope: registrant. A per-share figure or a share count (units USD/shares, shares) belongs to the whole registrant, not to the share class you asked for: BRK.B earnings per share are Berkshire Hathaway's Class A equivalents.

Provenance and point in time

Each value carries its accession, form, filer cik, and accepted_at (when the filing was accepted).

known_at=<instant> answers as the data was knowable at that instant; without it, the answer is as known now (Point in time).

The strict view and the continuity view

view=strict (the default) serves the registrant's own facts. view=continuity adds a predecessor registrant's history across a confirmed succession, each value carrying via (Succession and the continuity view).

Concepts a registrant stopped reporting

Each concept states its last_period_end: the latest observation end or as-of date of that concept alone, whatever period_type and limit select. It is not the registrant's latest fiscal period, and the maximum across concepts is not the latest fiscal quarter (a cover-page concept can end after the statements).

When the registrant's newer reports no longer carry a concept, field_states.last_period_end is no_longer_published. For example, AAPL's us-gaap:Revenues ends 2018-09-29, and the line continues as us-gaap:RevenueFromContractWithCustomerExcludingAssessedTax.

The default set (concepts=default) serves only the concepts the registrant still reports, and names a stopped one in missing as no_longer_published (also when it has nothing in the period asked, rather than none_in_period). Ask for it by name (concepts=us-gaap:Revenues) to read its history.

Overlapping concepts

Each concept is one taxonomy element, served as its own series. Concepts are never summed, substituted or derived (no D&A total, EBITDA, or capital-spending total): read each element's own scope before combining any.

Foreign filers

A convenience translation into USD (a 20-F in CNY that also states the year in USD) is not served; a concept left with nothing else is missing: basis_unclear. Own-currency facts are not converted.

IFRS facts are not served: for a registrant reporting under IFRS, each us-gaap concept is missing: not_published.

Gaps and quarterly values

Consecutive values of a concept are not always consecutive fiscal periods. Read each value's period_end; gaps are neither filled nor flagged. A fiscal fourth quarter is usually absent and is never derived.

Under period_type=quarterly, field_states.values is quarterly_ytd_only when the registrant reports the concept year-to-date only in its 10-Qs (usually cash-flow items): only the first fiscal quarters and any quarter an annual report states are served. Use period_type=ytd or all for the rest.

Missing and held facts

missing lists unserved concepts, each with its reason (reason codes).

A fact whose acceptance time is unknown is listed under held, never served.

The filings index

/filings lists the registrant's filings, newest first, paged by limit and after (lists). Each row carries its accession, form, filed date, accepted_at (when it was accepted), report_date, filer cik, its SEC EDGAR url, and items. form takes a csv of form types (10-K,10-Q,8-K), and known_at serves only the filings accepted at or before it.

8-K items

An 8-K-family filing carries items, its item numbers (a filing reporting items 2.02 and 9.01 lists both). When there are none, items is null. Item 4.02 is a non-reliance disclosure.

Registrants

registrants[] on /filings and /financials has one entry per SEC registrant answering for the instrument's issuer, in ascending CIK order. An issuer is not a registrant: a second CIK is its own entry.

Every field is described in the API reference. To use them:

• published_as_of is the age of the data the registrant's answer rests on, whatever status says.
• available_from and available_to are the span held as known at known_at, whatever the request's filters; available_to can be a cover-page date rather than a statement-period end.
• facts_pending (/financials) names the newest periodic filing that has contributed no facts yet; it is served on /filings meanwhile. concepts_pending names the concepts not yet available, each missing: temporarily_unavailable. No time is promised for either.

status	meaning
ok	complete and current, including (on /financials) the newest periodic report; published_as_of is its age
pending	/financials: the same, except that the served statements stop before the newest 10-K or 10-Q
possibly_incomplete	the newest filings may be missing; request it again later
temporarily_unavailable	no current data can be served yet; what is held is served
not_published	no XBRL financial data (/financials) or no filing index (/filings) is published for the registrant

Succession and the continuity view

lineage states the registrants' succession as known at known_at:

• status: not_assessed, none_found, candidates, confirmed, or disputed;
• edges: each succession, with its successor, predecessor, status, effective_date and evidence;
• unresolved: evidence naming a successor and no predecessor;
• uncovered_periods: [{from, to}], periods not assessed; none_found does not cover them.

The strict view serves no predecessor's history, whatever lineage says. Under view=continuity:

• continuity_coverage.chain lists the confirmed successions crossed, each with its effective_date and its registrants;
• stopped_at says where it stopped: ciks, reason, and the evidence naming that registrant as successor.

stopped_at.reason is succession_undetermined (reason codes). stopped_at is null only when nothing names the last registrant as successor; it does not claim the history is complete. The assertion selections view=continuity takes are on every filed value.