API reference · v1.0.0

US SEC Filings & Financial Data API

Download OpenAPI (sec.yaml) · Base URL https://api.olympus.new-odyssey.com

SEC EDGAR company data, served by the Olympus Go gateway: company lookup by CIK and ticker, company profiles, 10-K / 10-Q filing metadata, and selected standardised XBRL financial metrics with annual and quarterly history and cross-company comparison.

Sources. SEC EDGAR submissions and XBRL companyfacts (nightly bulk archives, refreshed from the JSON APIs for selected companies). Values are as filed by registrants; nothing is estimated or derived. Not included: real-time streaming, full-text search of filings, insider trading, ownership, recommendations.

CIK. Path and query CIKs accept 1-10 digits with or without leading zeros and an optional CIK prefix (320193, 0000320193, CIK0000320193). Responses always use the canonical form: 10 digits, zero padded (0000320193).

Ticker lookup. Use GET /v1/sec/companies/search?ticker=AAPL. It is an exact, case-insensitive match against every ticker the SEC maps to a company and returns a list, because a ticker can be shared during a reorganisation (each match carries its CIK). /companies/{cik} accepts CIKs only, so the two never collide.

Provenance. Every record (company, filing, metric value) carries a provenance block: where its value came from (source_url, source_date), when this version was published, the dataset and schema version, and the validation status of the publication. Responses list the active publication of each dataset they read in meta.datasets.

Metrics. revenue, net_income, total_assets, total_liabilities, stockholders_equity, operating_cash_flow, eps_diluted, shares_outstanding. Annual values come from 10-K / 10-K/A (fiscal period FY); quarterly values from 10-Q / 10-Q/A (Q1-Q3, no Q4). Quarterly operating cash flow is usually reported year-to-date only; such values have is_ytd: true and a period_start at the start of the fiscal year. When a later filing restates a value, the latest filed value is served and the first reported value is shown alongside (is_restated).

Authenticate with an API key in X-API-Key or Authorization: Bearer. The organization's plan must include sec; requests count against its monthly quota. Every response carries X-Request-Id. Errors share the Error body.

Companies

Search companies by name or ticker, or resolve a ticker

GET/v1/sec/companies/search

Exactly one of q or ticker is required.

ticker: exact, case-insensitive ticker match (the ticker resolver).
q: fuzzy company-name match (trigram similarity) plus ticker prefix match, ordered by relevance (exact ticker, ticker prefix, then name similarity). The ticker prefix is matched against each company's primary ticker. Name matches are ranked among at most 1,000 candidates, so very broad terms (holdings) return good but not necessarily the globally best name matches.

No match returns 200 with an empty data list.

Authentication: API key (X-API-Key or Bearer)

Parameters

Name	In	Type	Description
q	query	string	Free text, 2-100 characters after trimming leading and trailing whitespace (inner runs of whitespace count as one). Shorter or longer answers 400 `VALIDATION_ERROR` on `q`. Example: `apple`
ticker	query	string	Ticker symbol, e.g. `AAPL` or `BRK-B`. Example: `AAPL`
limit	query	integer

Responses

200	Matching companies.	CompanySearchResponse
400	Invalid parameter (`VALIDATION_ERROR`; `details.fields` maps each parameter to the reason) or malformed request (`BAD_REQUEST`).	Error
401	Missing or invalid API key (`UNAUTHORIZED`), or a disabled, expired or revoked one (`API_KEY_DISABLED`, `API_KEY_EXPIRED`, `API_KEY_REVOKED`).	Error
403	Organization suspended (`ORGANIZATION_SUSPENDED`), no live subscription (`NO_ACTIVE_SUBSCRIPTION`) , `sec` not on the plan (`PRODUCT_NOT_ENABLED`) or a key scoped to another product (`API_KEY_PRODUCT_SCOPE`).	Error
429	Per-minute rate limit exceeded (`RATE_LIMIT_EXCEEDED`) or monthly quota exhausted (`QUOTA_EXCEEDED`).	Error
503	A dataset this endpoint reads has no active publication yet (`SERVICE_UNAVAILABLE`, `details.dataset_id`).	Error

curl

curl -s "https://api.olympus.new-odyssey.com/v1/sec/companies/search" \
  -H "X-API-Key: $OLYMPUS_API_KEY"

Company profile

GET/v1/sec/companies/{cik}

Profile of one SEC registrant, with its most recent 10-K and 10-Q.

Authentication: API key (X-API-Key or Bearer)

Parameters

Name	In	Type	Description
cikrequired	path	CIKInput	CIK with or without leading zeros or a `CIK` prefix. Invalid formats answer 400 `VALIDATION_ERROR`. Example: `320193`

Responses

200	The company.	CompanyResponse
400	The CIK is not 1-10 digits (`VALIDATION_ERROR`).	Error
401	Missing or invalid API key (`UNAUTHORIZED`), or a disabled, expired or revoked one (`API_KEY_DISABLED`, `API_KEY_EXPIRED`, `API_KEY_REVOKED`).	Error
403	Organization suspended (`ORGANIZATION_SUSPENDED`), no live subscription (`NO_ACTIVE_SUBSCRIPTION`) , `sec` not on the plan (`PRODUCT_NOT_ENABLED`) or a key scoped to another product (`API_KEY_PRODUCT_SCOPE`).	Error
404	No company with this CIK in the current publication (`NOT_FOUND`).	Error
429	Per-minute rate limit exceeded (`RATE_LIMIT_EXCEEDED`) or monthly quota exhausted (`QUOTA_EXCEEDED`).	Error
503	A dataset this endpoint reads has no active publication yet (`SERVICE_UNAVAILABLE`, `details.dataset_id`).	Error

curl

curl -s "https://api.olympus.new-odyssey.com/v1/sec/companies/320193" \
  -H "X-API-Key: $OLYMPUS_API_KEY"

Filings

10-K and 10-Q filings of a company

GET/v1/sec/companies/{cik}/filings

Filing metadata (no document text), newest first: ordered by filed_date descending, then accession_number descending. Paginate with cursor: pass meta.pagination.next_cursor from the previous page and keep the other parameters unchanged.

Authentication: API key (X-API-Key or Bearer)

Parameters

Name	In	Type	Description
cikrequired	path	CIKInput	CIK with or without leading zeros or a `CIK` prefix. Invalid formats answer 400 `VALIDATION_ERROR`. Example: `320193`
form	query	array of FormType	Forms to include (repeat the parameter or separate with commas). Default: all four. `10-K` matches only originals unless `include_amendments` is true, in which case `10-K` also matches `10-K/A` (likewise for `10-Q`). Example: `["10-K"]`
include_amendments	query	boolean
filed_from	query	string (date)	First filing date (inclusive).
filed_to	query	string (date)	Last filing date (inclusive).
limit	query	integer
cursor	query	string	Opaque cursor from `meta.pagination.next_cursor`. Invalid or tampered cursors answer 400.

Responses

200	One page of filings.	FilingListResponse
400	Invalid parameter (`VALIDATION_ERROR`; `details.fields` maps each parameter to the reason) or malformed request (`BAD_REQUEST`).	Error
401	Missing or invalid API key (`UNAUTHORIZED`), or a disabled, expired or revoked one (`API_KEY_DISABLED`, `API_KEY_EXPIRED`, `API_KEY_REVOKED`).	Error
403	Organization suspended (`ORGANIZATION_SUSPENDED`), no live subscription (`NO_ACTIVE_SUBSCRIPTION`) , `sec` not on the plan (`PRODUCT_NOT_ENABLED`) or a key scoped to another product (`API_KEY_PRODUCT_SCOPE`).	Error
404	No company with this CIK in the current publication (`NOT_FOUND`).	Error
429	Per-minute rate limit exceeded (`RATE_LIMIT_EXCEEDED`) or monthly quota exhausted (`QUOTA_EXCEEDED`).	Error
503	A dataset this endpoint reads has no active publication yet (`SERVICE_UNAVAILABLE`, `details.dataset_id`).	Error

curl

curl -s "https://api.olympus.new-odyssey.com/v1/sec/companies/320193/filings" \
  -H "X-API-Key: $OLYMPUS_API_KEY"

Financials

Financial metric history of a company

GET/v1/sec/companies/{cik}/financials

Annual or quarterly history of the selected metrics, one series per metric, values ordered by period_end ascending. Metrics the company does not report are returned as empty series. Fiscal years are the company's own (Apple's fiscal 2024 ends 2024-09-28).

Authentication: API key (X-API-Key or Bearer)

Parameters

Name	In	Type	Description
cikrequired	path	CIKInput	CIK with or without leading zeros or a `CIK` prefix. Invalid formats answer 400 `VALIDATION_ERROR`. Example: `320193`
metric	query	array of MetricName	Metrics to return (comma separated or repeated). Default all eight. Example: `["revenue","net_income"]`
period	query	PeriodType
fiscal_year_from	query	integer	First fiscal year (inclusive). Defaults to a 10-fiscal-year window ending at `fiscal_year_to`.
fiscal_year_to	query	integer	Last fiscal year (inclusive). Defaults to the latest available. The window may span at most 30 years.

Responses

200	Metric series.	FinancialsResponse
400	Invalid parameter (`VALIDATION_ERROR`; `details.fields` maps each parameter to the reason) or malformed request (`BAD_REQUEST`).	Error
401	Missing or invalid API key (`UNAUTHORIZED`), or a disabled, expired or revoked one (`API_KEY_DISABLED`, `API_KEY_EXPIRED`, `API_KEY_REVOKED`).	Error
403	Organization suspended (`ORGANIZATION_SUSPENDED`), no live subscription (`NO_ACTIVE_SUBSCRIPTION`) , `sec` not on the plan (`PRODUCT_NOT_ENABLED`) or a key scoped to another product (`API_KEY_PRODUCT_SCOPE`).	Error
404	No company with this CIK in the current publication (`NOT_FOUND`).	Error
429	Per-minute rate limit exceeded (`RATE_LIMIT_EXCEEDED`) or monthly quota exhausted (`QUOTA_EXCEEDED`).	Error
503	A dataset this endpoint reads has no active publication yet (`SERVICE_UNAVAILABLE`, `details.dataset_id`).	Error

curl

curl -s "https://api.olympus.new-odyssey.com/v1/sec/companies/320193/financials" \
  -H "X-API-Key: $OLYMPUS_API_KEY"

Compare one metric across companies

GET/v1/sec/financials/compare

One metric for 2-10 companies over the same fiscal-year window, one series per company in the order requested. Values are aligned by each company's own fiscal year and fiscal period (FY, Q1-Q3), not by calendar date; compare period_end when fiscal year ends differ. Unknown CIKs are reported in data.not_found instead of failing the request; duplicates (after canonicalisation) count once.

Authentication: API key (X-API-Key or Bearer)

Parameters

Name	In	Type	Description
cikrequired	query	array of CIKInput	2-10 CIKs, comma separated or repeated. Example: `["320193","789019"]`
metricrequired	query	MetricName
period	query	PeriodType
fiscal_year_from	query	integer	First fiscal year (inclusive). Defaults to a 10-fiscal-year window ending at `fiscal_year_to`.
fiscal_year_to	query	integer	Last fiscal year (inclusive). Defaults to the latest available. The window may span at most 30 years.

Responses

200	One series per company.	CompareResponse
400	Invalid parameter (`VALIDATION_ERROR`; `details.fields` maps each parameter to the reason) or malformed request (`BAD_REQUEST`).	Error
401	Missing or invalid API key (`UNAUTHORIZED`), or a disabled, expired or revoked one (`API_KEY_DISABLED`, `API_KEY_EXPIRED`, `API_KEY_REVOKED`).	Error
403	Organization suspended (`ORGANIZATION_SUSPENDED`), no live subscription (`NO_ACTIVE_SUBSCRIPTION`) , `sec` not on the plan (`PRODUCT_NOT_ENABLED`) or a key scoped to another product (`API_KEY_PRODUCT_SCOPE`).	Error
429	Per-minute rate limit exceeded (`RATE_LIMIT_EXCEEDED`) or monthly quota exhausted (`QUOTA_EXCEEDED`).	Error
503	A dataset this endpoint reads has no active publication yet (`SERVICE_UNAVAILABLE`, `details.dataset_id`).	Error

curl

curl -s "https://api.olympus.new-odyssey.com/v1/sec/financials/compare?cik=320193%2C789019" \
  -H "X-API-Key: $OLYMPUS_API_KEY"

Schemas

Error object

The error body shared by every Olympus service.

Field	Type	Description
error *	string	Human-readable message.
code *	string	Stable machine-readable code.
product	string	Product that produced the error, when applicable.
details	object

CIKInput string

CIK as accepted in requests.

CIK string

Canonical CIK, 10 digits, zero padded.

AccessionNumber string

FormType enum: 10-K | 10-Q | 10-K/A | 10-Q/A

10-K10-Q10-K/A10-Q/A

MetricName enum: revenue | net_income | total_assets | total_liabilities | stockholders_equity | operating_cash_flow | eps_diluted | shares_outstanding

revenuenet_incometotal_assetstotal_liabilitiesstockholders_equityoperating_cash_floweps_dilutedshares_outstanding

PeriodType enum: annual | quarterly

annualquarterly

FiscalPeriod enum: FY | Q1 | Q2 | Q3

FYQ1Q2Q3

Unit enum: USD | USD/shares | shares

USDUSD/sharesshares

Provenance object

Where this record came from and which publication introduced this version of it.

Field	Type	Description
dataset_id *	enum: delphi.companies \| delphi.filings \| delphi.financial_metrics
source_id	enum: sec.submissions_bulk \| sec.submissions_api \| sec.companyfacts_bulk \| sec.companyfacts_api	Registered upstream source.
source_url *	string (uri)	The record's upstream document (per-company SEC JSON URL).
source_version	string	Snapshot of the source this value was read from (`sha256:<16 hex>` for SEC snapshots).
source_date *	string (date) \| null	Publisher as-of date of that snapshot (SEC archive build date, New York time).
published_at *	string (date-time)	When this version of the record was first published. Unchanged records keep their original time.
schema_version *	string
validation_status *	enum: passed \| passed_with_warnings
record_id	string	Stable record key within the dataset.

DatasetPublication object

Field	Type	Description
dataset_id *	string
publication_id	integer (int64)
published_at *	string (date-time)
freshness *	enum: fresh \| stale	`stale` when the active publication is older than the dataset's expected maximum age (3 days).

Meta object

Field	Type	Description
request_id	string
datasets *	DatasetPublication []	Active publication of each dataset this response read.

Field	Type	Description
limit *	integer
has_more *	boolean
next_cursor	string \| null	Pass as `cursor` to get the next page; null on the last page.

Ticker object

Field	Type	Description
ticker *	string
exchange	string \| null

Address object

Field	Type	Description
street1	string \| null
street2	string \| null
city	string \| null
state_or_country	string \| null	Two-letter state or SEC country code.
postal_code	string \| null
state_or_country_description	string \| null

FormerName object

Field	Type	Description
name *	string
from	string (date-time) \| null
to	string (date-time) \| null

CompanySummary object

Field	Type	Description
cik *	CIK
name *	string
tickers *	Ticker []
primary_ticker	string \| null
sic_code	string \| null
state_of_incorporation	string \| null
match	enum: ticker_exact \| ticker_prefix \| name	How the company matched a search.
score	number (float)	Relevance for `q` searches (0-1).
provenance *	Provenance

Company object

Field	Type	Description
cik *	CIK
name *	string
entity_type	string \| null
tickers *	Ticker []
primary_ticker	string \| null
sic_code	string \| null
sic_description	string \| null
filer_category	string \| null
state_of_incorporation	string \| null
fiscal_year_end	string \| null	Month and day the fiscal year ends (MMDD).
ein	string \| null
phone	string \| null
business_address	Address \| null
mailing_address	Address \| null
former_names *	FormerName []
latest_10k	Filing \| null	Most recent 10-K or 10-K/A.
latest_10q	Filing \| null	Most recent 10-Q or 10-Q/A.
links *	object
provenance *	Provenance

Filing object

Field	Type	Description
cik *	CIK
accession_number *	AccessionNumber
form *	FormType
is_amendment *	boolean
filed_date *	string (date)
accepted_at	string (date-time) \| null
report_date	string (date) \| null	End of the period the filing reports on.
primary_document	string \| null
primary_doc_description	string \| null
file_number	string \| null
film_number	string \| null
size_bytes	integer (int64) \| null
is_xbrl	boolean \| null
is_inline_xbrl	boolean \| null
document_url	string (uri) \| null
filing_index_url *	string (uri)	EDGAR filing index (evidence link).
provenance *	Provenance

MetricValue object

Field	Type	Description
metric *	MetricName
period_type *	PeriodType
fiscal_year *	integer
fiscal_period *	FiscalPeriod
period_start	string (date) \| null	Null for point-in-time metrics (assets, liabilities, equity, shares).
period_end *	string (date)
as_of_date	string (date) \| null	Point-in-time metrics only - the measurement date. For `shares_outstanding` from the cover page this is after `period_end`.
duration_days	integer \| null
is_ytd *	boolean	True for a quarterly value reported year-to-date (6 or 9 months), not for the quarter alone.
value *	number	As filed, in `unit` (whole dollars, not thousands).
unit *	Unit
taxonomy	enum: us-gaap \| dei
concept *	string	XBRL concept the value was taken from (see the mapping table in the pipeline docs).
form *	enum: 10-K \| 10-K/A \| 10-Q \| 10-Q/A	Form of the filing the value was taken from.
filed_date *	string (date)
accession_number *	AccessionNumber
evidence_url *	string (uri)	EDGAR index of the filing the value was taken from.
is_restated *	boolean	The value differs from the first value reported for this period.
first_reported	object \| null
provenance *	Provenance

MetricSeries object

Field	Type	Description
metric *	MetricName
unit *	Unit
values *	MetricValue []

CompanySearchResponse object

Field	Type	Description
data *	CompanySummary []
meta *	Meta

CompanyResponse object

Field	Type	Description
data *	Company
meta *	Meta

FilingListResponse object

Field	Type	Description
data *	Filing []
meta *	Meta + object

FinancialsResponse object

Field	Type	Description
data *	object
meta *	Meta

CompareResponse object

Field	Type	Description
data *	object
meta *	Meta

* required field

US SEC Filings & Financial Data API

Companies

Search companies by name or ticker, or resolve a ticker

Parameters

Responses

Company profile

Parameters

Responses

Filings

10-K and 10-Q filings of a company

Parameters

Responses

Financials

Financial metric history of a company

Parameters

Responses

Compare one metric across companies

Parameters

Responses

Schemas

Error object

CIKInput string

CIK string

AccessionNumber string

FormType enum: 10-K | 10-Q | 10-K/A | 10-Q/A

MetricName enum: revenue | net_income | total_assets | total_liabilities | stockholders_equity | operating_cash_flow | eps_diluted | shares_outstanding

PeriodType enum: annual | quarterly

FiscalPeriod enum: FY | Q1 | Q2 | Q3

Unit enum: USD | USD/shares | shares

Provenance object

DatasetPublication object

Meta object

Pagination object

Ticker object

Address object

FormerName object

CompanySummary object

Company object

Filing object

MetricValue object

MetricSeries object

CompanySearchResponse object

CompanyResponse object

FilingListResponse object

FinancialsResponse object

CompareResponse object