DFin API v1

Authentication

Ordinary API requests require an API key passed as a Bearer token in the Authorization header. Temporary artifact URLs are sensitive capability links and are the only documented exception; use them exactly as returned without adding the API key, and do not log or share them. Set DFIN_API_KEY once as a permanent environment variable before running authenticated examples.

Using an environment variable keeps the API key out of code, examples, and config text. The curl and Python examples use DFIN_API_KEY to send Authorization: Bearer ${DFIN_API_KEY}. You do not need to restart your computer; reload the shell session after setting the variable, and restart any already-running agent or app process that needs the key.

When prepaid API access is enabled, the first 250 core REST and MCP data requests per UTC month are free; after that, metered routes cost $0.0100 when they return an exact 200 response. The securities-search and billing-balance routes are free, and temporary artifact retrieval does not create another charge. Pending and failed requests are not charged. Identical successful requests replay for 90 seconds without another allowance request or charge. Polling the same processing task returns fresh progress and counts as one request for that task. A successful partial result can be charged once; later results from that task do not create another charge. If the wallet cannot fund a metered result, the API returns 402 with the balance, required amount, and retry guidance.

Get billing balance

GET /api/v1/billing/balance/

Return the authenticated account's current credit balance, billing mode, monthly free-request usage and reset, Notebook access, and rate limits without consuming allowance or credits.

{
  "billing_mode": "payg",
  "credit_balance_usd": "2.0000",
  "monthly_free_allowance": {
    "limit": 250,
    "used": 42,
    "reset_at": "2026-11-01T00:00:00+00:00"
  },
  "notebook_access": false,
  "rate_limits": {
    "minute": "60/min",
    "rolling_day": "5000/day",
    "bulk_document_search_minute": "10/min"
  }
}

Search filings

Search structured company filings using one or more natural-language queries. Use the latest-filings endpoint for browse-style discovery; queryless filing search is not supported. results_per_query is a per-query cap; maximum combined results are number of queries times results_per_query. Optional date_from/date_to bounds filter by filing date, not fiscal period. Ticker filters support .US, .T; non-U.S. filing searches are indexed-only. Eligible .US filing-search responses may include SEC evidence to complement indexed coverage. External database fallback can return temporary searchable document UUIDs backed by matched filing chunks; fallback rows match the ordinary filing-search result shape and identify their three-day expiry in agent_note. Fallback candidates are reranked on a best-effort basis and include reranking_score only when reranking succeeds. An eligible date-scoped .US covered-issuer request may search indexed DFin filings and SEC filings together when its range crosses reliable indexed coverage. The boundary day is searched through both sources and merged results are deduplicated and reranked once. fiscal_year and fiscal_period remain DFin filters but are omitted from the SEC branch, where filing dates are authoritative; this scope adjustment is reported as partial. A lone date_from normally extends through today, while a lone date_to normally extends from 2000-01-01. A pre-2000 upper-only or future lower-only range is collapsed to its explicit day rather than reversed, and two explicit dates are preserved. Covered searches without date bounds remain indexed-only. Generated analysis-report documents are excluded by default using case-insensitive filing_type exact exclusions for analysis_report and stock_analysis_report. Transcripts are excluded by default using a case-insensitive filing_type prefix exclusion for transcript.

Parameters

queries array of string Required

One to 12 queries, each up to 300 characters. Filing search requires a query; use list_latest_filings for browse-style discovery.

ticker string Optional

Optional exchange-qualified ticker from the supported filing exchanges (.US, .T). Eligible .US searches may use SEC EDGAR fallback; other supported exchanges are indexed-only. Max 40 characters.

exclude_tickers array of string Optional

One to 100 ticker values to exclude from ranked results. Use keyword search for literal company-name mentions in other issuers. Results are bounded ranked chunks, not an exhaustive issuer census.

fiscal_year integer or array of integers Optional

Accepts one year or up to 10 years from 1900 through 2050. Results are ranked across all selected years.

fiscal_period string Optional

Optional fiscal period filter.

Allowed Q1Q2Q3Q4H1H2FY

filing_type string Optional

Optional filing type, for example 10-K. Max 30 characters.

date_from value Optional

Optional inclusive lower date bound in YYYY-MM-DD format. Filing search uses filing_date; transcript search uses event_date; report search uses published_date.

date_to value Optional

Optional inclusive upper date bound in YYYY-MM-DD format. Filing search uses filing_date; transcript search uses event_date; report search uses published_date.

results_per_query integer Optional Default 5

Maximum result chunks per query. Defaults to 5, min 1, max 25. For N queries, the maximum combined result count is N * results_per_query; actual returned results may be lower after deduplication, filtering, empty matches, or backend errors.

rerank boolean Optional Default false

Defaults to false for REST search. Initial SEC EDGAR fallback results and mixed permanent/temporary document results always attempt best-effort reranking after keyword candidate selection. Temporary-only document search follows this flag. reranking_score is returned only when reranking succeeds.

searchtype string Optional Default "hybrid"

Retrieval strategy. hybrid blends semantic and keyword search; vector is semantic only; keyword is exact-term matching.

Allowed hybridvectorkeyword

Response

Returns the normalized filing-search result payload shared by REST and MCP. At least one query is required; use the latest-filings endpoint for browse-style discovery. results_per_query is a per-query cap, so the maximum combined result count is the number of queries multiplied by results_per_query; actual returned results may be lower after deduplication, filtering, empty matches, or service errors. If DFin is still processing the search, the endpoint returns 202 with status_code, message, and retry_after_seconds; repeat the identical request after that interval. A date-scoped covered-issuer request may search indexed DFin filings and SEC filings together when its range crosses reliable indexed coverage. The boundary day is searched through both sources, and the combined evidence is deduplicated and reranked once. A lone date_from normally extends through today; a lone date_to normally extends from 2000-01-01. Explicit earlier dates are preserved. Fiscal filters remain on indexed evidence and are omitted from the SEC branch; when this broadens the fiscal scope, the response is partial. The SEC branch independently selects up to 20 HTML attachments, validates them against their filing attachment lists, stores successfully parsed documents, and runs the standard hybrid search. Non-HTML formats do not consume the allowance, and reaching the allowance produces a partial result. One inaccessible attachment does not discard surviving evidence. An incomplete required scope with no surviving evidence returns 502; 200 with an empty result is reserved for a genuine zero-hit or completely searched no-match result.

Bulk search filings

Search indexed filing text across two to 25 companies on supported filing exchanges (.US, .T). The complete inclusive filing-date range can span at most five calendar years. by_ticker preserves independent ticker/query rankings and reports indexed coverage; by_query returns one global ranking and does not report per-ticker counts.

Parameters

queries array of string Required

One to five ordered queries, each up to 300 characters.

tickers array of string Required

Two to 25 distinct exchange-qualified tickers from the supported filing exchanges (.US, .T). Values are uppercased, deduplicated, and sorted.

fiscal_year integer or array of integers Optional

Accepts one year or up to 10 years from 1900 through 2050. Results are ranked across all selected years.

fiscal_period string Optional

Optional fiscal period filter.

Allowed Q1Q2Q3Q4H1H2FY

date_from value Required

Required inclusive filing-date lower bound in YYYY-MM-DD format.

date_to value Required

Required inclusive filing-date upper bound in YYYY-MM-DD format. The complete interval may span at most five calendar years.

results_per_query integer Optional Default 5

Maximum result chunks for each ticker/query pair in by_ticker mode or each global query in by_query mode. Defaults to 5, min 1, max 10.

searchtype string Optional Default "hybrid"

Retrieval strategy. hybrid blends semantic and keyword search; vector is semantic only; keyword is exact-term matching.

Allowed hybridvectorkeyword

result_format string Optional Default "by_ticker"

by_ticker preserves independent company rankings and coverage; by_query ranks each query across the combined ticker set.

Allowed by_tickerby_query

filing_type string Optional

Optional filing type, for example 10-K, 20-F, S-1, or 424B4. Omit it to search all indexed filing types.

Response

Responses always identify the canonical tickers and queries, use coverage_mode: indexed_only, and preserve every ticker and query in by_ticker mode. Use by_query only when a global ranking is sufficient: it cannot establish per-ticker coverage. A capacity response is 413; unavailable indexed search is 503; malformed or connectivity failures are 502.

Search transcripts

Search public transcript documents using natural-language queries. results_per_query is a per-query cap; maximum combined results are number of queries times results_per_query. Optional date_from/date_to bounds filter transcript event_date. The endpoint is scoped to filing_type transcript and does not accept a public filing_type parameter.

Parameters

queries array of string Required

One to 12 queries, each up to 300 characters. Filing search requires a query; use list_latest_filings for browse-style discovery.

ticker string Optional

Optional ticker filter. Max 40 characters.

exclude_tickers array of string Optional

One to 100 ticker values to exclude from ranked results. Use keyword search for literal company-name mentions in other issuers. Results are bounded ranked chunks, not an exhaustive issuer census.

fiscal_year integer or array of integers Optional

Accepts one year or up to 10 years from 1900 through 2050. Results are ranked across all selected years.

fiscal_period string Optional

Optional fiscal period filter.

Allowed Q1Q2Q3Q4H1H2FY

date_from value Optional

Optional inclusive lower date bound in YYYY-MM-DD format. Filing search uses filing_date; transcript search uses event_date; report search uses published_date.

date_to value Optional

Optional inclusive upper date bound in YYYY-MM-DD format. Filing search uses filing_date; transcript search uses event_date; report search uses published_date.

results_per_query integer Optional Default 5

Maximum result chunks per query. Defaults to 5, min 1, max 25. For N queries, the maximum combined result count is N * results_per_query; actual returned results may be lower after deduplication, filtering, empty matches, or backend errors.

rerank boolean Optional Default false

Defaults to false for REST search. Initial SEC EDGAR fallback results and mixed permanent/temporary document results always attempt best-effort reranking after keyword candidate selection. Temporary-only document search follows this flag. reranking_score is returned only when reranking succeeds.

searchtype string Optional Default "hybrid"

Retrieval strategy. hybrid blends semantic and keyword search; vector is semantic only; keyword is exact-term matching.

Allowed hybridvectorkeyword

Response

Returns the current filing-search result payload from transcript documents only. results_per_query is a per-query cap, so the maximum combined result count is the number of queries multiplied by results_per_query; actual returned results may be lower after deduplication, filtering, empty matches, or service errors. If DFin is still processing the search, the endpoint returns 202 with status_code, message, and retry_after_seconds; the Retry-After header mirrors the returned retry interval. When date_from or date_to is supplied, the date range is inclusive and filters transcript event_date. Each matched DFin transcript uses doc_uuid for follow-up tools and exposes its website link as meta_data.source_uri; document hashes, internal identifiers, and storage locations are omitted.

Bulk search transcripts

Search indexed transcript text across two to 25 globally listed companies. The complete inclusive event-date range can span at most five calendar years. by_ticker preserves independent ticker/query rankings and reports indexed coverage; by_query returns one global ranking and does not report per-ticker counts.

Parameters

queries array of string Required

One to five ordered queries, each up to 300 characters.

tickers array of string Required

Two to 25 distinct globally exchange-qualified tickers, including one-character exchange codes such as 9984.T. Values are uppercased, deduplicated, and sorted.

fiscal_year integer or array of integers Optional

Accepts one year or up to 10 years from 1900 through 2050. Results are ranked across all selected years.

fiscal_period string Optional

Optional fiscal period filter.

Allowed Q1Q2Q3Q4H1H2FY

date_from value Required

Required inclusive transcript event-date lower bound in YYYY-MM-DD format.

date_to value Required

Required inclusive transcript event-date upper bound in YYYY-MM-DD format. The complete interval may span at most five calendar years.

results_per_query integer Optional Default 5

Maximum result chunks for each ticker/query pair in by_ticker mode or each global query in by_query mode. Defaults to 5, min 1, max 10.

searchtype string Optional Default "hybrid"

Retrieval strategy. hybrid blends semantic and keyword search; vector is semantic only; keyword is exact-term matching.

Allowed hybridvectorkeyword

result_format string Optional Default "by_ticker"

by_ticker preserves independent company rankings and coverage; by_query ranks each query across the combined ticker set.

Allowed by_tickerby_query

Response

Responses always identify the canonical tickers and queries, use coverage_mode: indexed_only, and preserve every ticker and query in by_ticker mode. Use by_query only when a global ranking is sufficient: it cannot establish per-ticker transcript coverage. Missing transcripts are not retrieved on demand. A capacity response is 413; unavailable indexed search is 503; malformed or connectivity failures are 502.

Search reports

Search public stock analysis reports using natural-language queries. results_per_query is a per-query cap; maximum combined results are number of queries times results_per_query. Optional date_from/date_to bounds filter report published_date. The endpoint is currently scoped to stock_analysis_report only. Set include_references=true only when every matched report should include provenance metadata; otherwise keep search lean and use report details for one selected report. General analysis_report support is a high-priority follow-up.

Parameters

queries array of string Required

One to 12 queries, each up to 300 characters. Filing search requires a query; use list_latest_filings for browse-style discovery.

ticker string Optional

Optional ticker filter. Max 40 characters.

exclude_tickers array of string Optional

One to 100 ticker values to exclude from ranked results. Use keyword search for literal company-name mentions in other issuers. Results are bounded ranked chunks, not an exhaustive issuer census.

fiscal_year integer or array of integers Optional

Accepts one year or up to 10 years from 1900 through 2050. Results are ranked across all selected years.

fiscal_period string Optional

Optional fiscal period filter.

Allowed Q1Q2Q3Q4H1H2FY

date_from value Optional

Optional inclusive lower date bound in YYYY-MM-DD format. Filing search uses filing_date; transcript search uses event_date; report search uses published_date.

date_to value Optional

Optional inclusive upper date bound in YYYY-MM-DD format. Filing search uses filing_date; transcript search uses event_date; report search uses published_date.

results_per_query integer Optional Default 5

Maximum result chunks per query. Defaults to 5, min 1, max 25. For N queries, the maximum combined result count is N * results_per_query; actual returned results may be lower after deduplication, filtering, empty matches, or backend errors.

rerank boolean Optional Default false

Defaults to false for REST search. Initial SEC EDGAR fallback results and mixed permanent/temporary document results always attempt best-effort reranking after keyword candidate selection. Temporary-only document search follows this flag. reranking_score is returned only when reranking succeeds.

searchtype string Optional Default "hybrid"

Retrieval strategy. hybrid blends semantic and keyword search; vector is semantic only; keyword is exact-term matching.

Allowed hybridvectorkeyword

include_references boolean Optional Default false

When true, append report reference metadata to each matched report result. Defaults to false; use report details for one report after a lean search.

Response

Returns the current filing-search result payload from stock analysis report documents only. results_per_query is a per-query cap, so the maximum combined result count is the number of queries multiplied by results_per_query; actual returned results may be lower after deduplication, filtering, empty matches, or service errors. If DFin is still processing the search, the endpoint returns 202 with status_code, message, and retry_after_seconds; the Retry-After header mirrors the returned retry interval. When date_from or date_to is supplied, the date range is inclusive and filters report published_date. Each matched report uses doc_uuid for follow-up tools and exposes its website link as meta_data.source_uri; document hashes, internal identifiers, and storage locations are omitted. When include_references is true, each matched report result includes a references array with the transcripts, filings, and related reports used to build that already source-grounded report.

Search documents

Search within explicit DFin document UUIDs using natural-language queries. Use this for follow-up evidence search after another search, latest-document, or report-details response has returned the document UUIDs to inspect.

Parameters

queries array of string Required

One to 12 queries, each up to 300 characters. Filing search requires a query; use list_latest_filings for browse-style discovery.

doc_uuids array of string Required

One to 500 document UUIDs returned by search, latest-document, or report-details results. At most 20 may be temporary SEC document IDs.

results_per_query integer Optional Default 5

Maximum result chunks per query. Defaults to 5, min 1, max 25. For N queries, the maximum combined result count is N * results_per_query; actual returned results may be lower after deduplication, filtering, empty matches, or backend errors.

rerank boolean Optional Default false

Defaults to false for REST search. Initial SEC EDGAR fallback results and mixed permanent/temporary document results always attempt best-effort reranking after keyword candidate selection. Temporary-only document search follows this flag. reranking_score is returned only when reranking succeeds.

searchtype string Optional Default "hybrid"

Retrieval strategy. hybrid blends semantic and keyword search; vector is semantic only; keyword is exact-term matching.

Allowed hybridvectorkeyword

result_format string Optional Default "flat"

Response layout. Document search accepts flat or by_query. Screener endpoints accept rows or tickers.

Allowed flatby_query

max_results_per_doc_uuid integer Optional

Optional per-document chunk cap for each query, from 1 through 10. Capped semantic document search uses exact retrieval.

Response

Returns the current document-scoped search result payload from the provided doc_uuids only. doc_uuids is required and accepts between 1 and 20 document UUIDs. This endpoint does not accept ticker, filing type, fiscal, or date filters. Results use the same public projection as the source searches. Database-resident temporary temp_ IDs returned by SEC fallback use the standard DFin search path; a compatibility path is used only when the temporary document is absent there. Temporary IDs remain usable only while their backing documents are available. If DFin is still processing the search, the endpoint returns 202 with status_code, message, and retry_after_seconds; the Retry-After header mirrors the returned retry interval.

Get report details

Return one stock analysis report ID, document UUID when indexed, public source URL, and source-reference metadata.

Query parameters

doc_uuid string Optional

DFin document UUID returned by report search or browsing. Provide exactly one of doc_uuid or report_id; never pass a report ID here.

report_id string Optional

Case-sensitive 8-12 character Base62 DFin report ID returned by report details or note relationships. Provide exactly one of report_id or doc_uuid; never pass a document UUID here.

Provide exactly one lookup identifier: doc_uuid from report search or browsing, or report_id from report details or note relationships. A document UUID identifies indexed content; a report ID identifies the report resource and its note relationships, so do not interchange them. If the selected report has not been indexed as a document, report.doc_uuid is null and document-content tools are unavailable for that report. The legacy public_id and report_public_id names are not supported. Missing reports return 404 with identifier-specific corrective guidance.

Response

References show what was used to build an already source-grounded report. Agents do not need to re-check every referenced document unless the user asks or the task is specifically verification.

Get document content

Return full raw text content or one selected chunk for a document UUID.

Query parameters

doc_uuid string Required

Document UUID returned by search or latest-document results.

chunk_num integer Optional

Optional zero-based chunk number from search results. Use it like a page-like index; search result meta_data.total_chunks gives the total chunk count for the doc_uuid.

Response

Use a doc_uuid returned by filing search, transcript search, report search, document search, latest filings, latest transcripts, or latest reports. Temporary temp_ IDs from external results expire within three days. IDs returned by latest filings hydrate from their SEC source on first use without extending that original expiry.

Successful responses are raw text/plain content, not JSON and not a metadata envelope. Error responses remain JSON with a detail field.

List latest filings

List recent filing documents without searching filing text. Filings are ordered and filtered by filing_date.

Query parameters

ticker string Optional

Optional exchange-qualified ticker, for example AAPL.US. DFin reconciles locally known .US companies with SEC EDGAR at request time, and SEC-mapped external companies are also supported.

filing_types array of string Optional Default []

Optional array of 1 to 20 filing-type prefixes, for example 10-K, 8-K, or 424. Repeat filing_types in the query string for each value. Required without ticker.

limit integer Optional Default 50

Optional maximum number of returned rows. Defaults to 50; use 1 through 100, or -1 for all results in the bounded days window.

days integer Optional

Optional with ticker and required without ticker. The maximum is 90 with ticker, 31 without ticker for finite limits, and 7 without ticker when limit=-1.

data_in_db_only boolean Optional Default false

Optional boolean that defaults to false. When true, enumerate only filings stored by DFin. When false, include eligible filings from the complete public-company enumeration path.

result_level string Optional Default "document"

Optional result purpose. document returns search-compatible rows with permanent or temporary doc_uuid values. accession returns one metadata-only row per SEC accession for enumeration and does not guarantee a searchable doc_uuid. Defaults to document.

Allowed documentaccession

• With ticker, filing_types and days are optional. Without ticker, both are required.
• Repeat filing_types for multiple REST values. Use result_level=accession for one row per accession.
• Use result_level=document when returned filings must feed document-search or content tools. Accession results are metadata-only and do not guarantee a searchable doc_uuid.
• Forms 3, 4, 5, and 144 (including /A amendments) are available only with an SEC-mapped .US ticker. Form 144 is a notice of a proposed sale, not a completed transaction.
• Accession rows retain scalar issuer fields for compatibility and include issuers with every SEC-listed CIK association on a joint filing. A ticker-scoped request keeps the requested issuer primary; a global request uses the first listed SEC CIK in source order.
• total_count is measured before limit. Treat it as a complete population only when coverage.complete=true.
• coverage.as_of identifies the observed population snapshot. Current-day global scans compare complete filing identities across bounded verification passes; continued changes return coverage.complete=false rather than chasing the live feed indefinitely.
• coverage.source_accounting separates raw SEC hits, listed issuer associations, output accessions, non-listed exclusions, malformed or unexpected-form hits, and unavailable primary documents. Stable issues distinguish malformed records, unexpected forms, unavailable documents, timeouts, rate limits, upstream availability, and a changing source.

Document results include permanent DFin document UUIDs when available and temporary document UUIDs for eligible primary filings not yet stored by DFin. Accession results remain usable when document storage is unavailable, do not guarantee document-search compatibility, and never include a potentially partial exhibit collection. Optional primary_document metadata in an accession row may omit doc_uuid. Census completeness covers source integrity and available primary-document URLs; it does not guarantee thematic recall, image-only evidence, or exhibits that search did not surface.

Supported U.S. filing forms

Domestic company profiles support 10-K, 10-K405, 10-KT, 8-K, S-1, 10-Q, 10-QT, NT 10-K, NT 10-Q, S-3, S-3ASR, S-3D, S-3DPOS, S-3MEF, S-4, S-4 POS, S-4EF, S-4MEF, S-8, S-8 POS, S-11, S-11MEF, S-1MEF, POS AM, POS EX, POS462B, POS462C, POSASR, RW, RW WD, AW, AW WD, 425, 424A, 424B1, 424B2, 424B3, 424B4, 424B5, 424B7, 424B8, 424H, 424I, FWP, DEF 14A. ADR and foreign-private-issuer profiles support 20-F, 40-F, 6-K, NT 20-F, F-1, F-1MEF, F-3, F-3ASR, F-3D, F-3DPOS, F-3MEF, F-4, F-4 POS, F-4EF, F-4MEF, F-10, F-10EF, F-10POS, F-6, F-6EF, F-6 POS, F-7, F-7 POS, F-8, F-8 POS, F-80, F-80POS, S-8, S-8 POS, POS AM, POS EX, POS462B, POS462C, POSASR, RW, RW WD, AW, AW WD, 425, 424A, 424B1, 424B2, 424B3, 424B4, 424B5, 424B7, 424B8, 424H, 424I, FWP, 20FR12B, 20FR12G, 40FR12B, 40FR12G. Amendments of these forms are also eligible. Financial-company profiles exclude 424B2, 424B3, 424B4, 424B5, and FWP.

For companies whose ADR classification is unavailable, DFin uses the combined domestic and ADR profile. An explicit unsupported prefix returns 400. Standalone ownership forms 3, 4, and 5 are not accepted; use 424 to select supported 424B* filings.

days uses an exact inclusive UTC calendar window ending on the current UTC date. limit=-1 requires days and permits at most 7 days without a ticker or 90 days with a ticker.

List filing comparison options

List up to the ten latest comparison-supported filings for one company and required exact filing type, ordered newest first.

Query parameters

ticker string Required

Required exchange-qualified DFin ticker, for example AAPL.US.

filing_type string Required

Required exact supported filing type, for example 10-K.

Allowed 10-K10-K/A10-Q10-Q/A20-F20-F/A40-F40-F/ADEF 14A

before value Optional

Optional exclusive filing-date boundary in YYYY-MM-DD format for loading older history.

cursor string Optional

Opaque next_cursor from the preceding comparison-options response.

Use this endpoint as the authoritative DFin source for comparison accession numbers. It returns up to the ten latest filings of the required exact type, ordered newest first. Choose the older/newer pair from these results; next_cursor loads another page of up to ten older filings.

Compare filings

Return deterministic section and before/after change records for one validated ordered accession pair, with a verified browser comparison link when available.

Parameters

ticker string Required

Required exchange-qualified DFin ticker, for example AAPL.US.

older_accession_number string Required

Older SEC accession number returned by the comparison-options endpoint.

newer_accession_number string Required

Newer SEC accession number returned by the comparison-options endpoint.

Both accessions must belong to the requested ticker, use the exact same supported filing type, and be ordered from older to newer filing date. A first request may return 202 with Retry-After: 30 and no browser link; repeat the identical body after that interval. Only a successfully reserved new global job consumes the dedicated account-level 1 RPM allowance. Same-pair joins, polls, and completed reuse remain under normal API limits.

Completed results contain structured change records with aggregate counts, section metadata, before_text, and after_text; they are not a rendered redline document. When present, comparison_url opens the authenticated side-by-side, redline, or changes-only browser view. The field is omitted unless a completed artifact and the browser route have been verified.

List latest transcripts

List recent transcript documents without searching transcript text. Transcripts are ordered and filtered by call_date.

Query parameters

ticker string Optional

Optional full DFin ticker including exchange suffix, for example AAPL.US. Omit for global latest documents.

limit integer Optional Default 10

Optional maximum number of documents to return. Defaults to 10 and must be between 1 and 30.

days integer Optional

Optional recent-day window. Must be between 1 and 90. The cutoff uses UTC math with an extra 12-hour grace window for U.S. and Canadian time zones.

When days is supplied, the call-date window is applied first and the result is capped by limit. The cutoff retains the 12-hour U.S. and Canadian time-zone grace window.

List latest reports

List recent stock analysis report documents without searching report text. Reports are ordered and filtered by published_at.

Query parameters

ticker string Optional

Optional full DFin ticker including exchange suffix, for example AAPL.US. Omit for global latest documents.

limit integer Optional Default 10

Optional maximum number of documents to return. Defaults to 10 and must be between 1 and 30.

days integer Optional

Optional recent-day window. Must be between 1 and 90. The cutoff uses UTC math with an extra 12-hour grace window for U.S. and Canadian time zones.

When days is supplied, the publication-date window is applied first and the result is capped by limit. The cutoff retains the 12-hour U.S. and Canadian time-zone grace window.

Get screener options

Return metadata for the current screener contract. Defaults to mode=all; use ?mode=basic for the basic-only contract.

A discovery endpoint. It does not run a screen; it returns the current public screener contract so clients can build valid requests.

Query parameters

mode string Optional in query string Default "all"

all returns the full contract including both basic and advanced metadata. basic returns a smaller contract limited to the basic filter set. There is no mode=advanced; use mode=all when you need advanced metadata.

Allowed allbasic

Response modes

There is no mode=advanced; use mode=all when you need advanced metadata.

Request envelope and shared controls

Both screener POST endpoints share the same top-level request envelope. The difference is which filter keys each endpoint accepts.

Fields

filters object Optional Default {}

Filter payload keyed by screener filter name.

sort object Optional Default {}

Sort object with field and optional desc direction. Valid sort fields come from options.sort.fields.

page object Optional Default {}

Accepts limit and offset. Maximum limit is 1000.

fields array of string Optional

Output fields for rows responses. Valid field names come from options.fields.

result_format string Optional Default "rows"

Response layout. Document search accepts flat or by_query. Screener endpoints accept rows or tickers.

Allowed rowstickers

Pagination, sorting, fields, and result format

Both screener POST endpoints share the same pagination, sorting, field selection, and result_format behavior. The default page is {"limit": 100, "offset": 0}. page.limit must be between 1 and 1000. result_format accepts either rows or tickers.

Building screener requests

Filter payload grammar

Each entry in filters is keyed by a filter name from options.filters. The filter's input_type supplies the default payload shape; field-specific metadata can define an exception.

Using option values

For filters with options_source, submit values from the matching list in options.option_values. These are accepted request values, not browser display labels. For filters with inline options, submit one of those listed values. For growth metrics, derive valid currency_basis values from the keys under metric.value_fields[value_type]; for example, if a metric has value_fields.cagr.reported and value_fields.cagr.usd, both reported and usd are valid for CAGR.

Units and thresholds

Request snippets

These snippets show only the relevant part of the request body. Put filter examples under the top-level filters object when sending a screener POST request.

{
  "country": {
    "operator": "include",
    "values": [
      "United States"
    ]
  }
}

{
  "databaseCoverage": {
    "relation": "or",
    "values": [
      "filings",
      "transcripts"
    ]
  }
}

{
  "databaseCoverage": {
    "relation": "and",
    "values": [
      "filings",
      "transcripts",
      "reports"
    ]
  }
}

{
  "marketCap_usd": {
    "min": 10000000000
  }
}

{
  "description_keywords": {
    "fts": "cloud software"
  }
}

{
  "returnOnInvestedCapital": {
    "missing_policy": "strict",
    "rules": [
      {
        "kind": "range",
        "operand": {
          "kind": "average",
          "years": 3,
          "anchor": {
            "scope": "fy",
            "offset": 0
          }
        },
        "min": 0.15
      }
    ]
  }
}

{
  "incomeStatementGrowth": {
    "rules": [
      {
        "metric": "revenue",
        "horizon_years": 5,
        "value_type": "cagr",
        "currency_basis": "reported",
        "min": 0.1
      }
    ]
  }
}

{
  "volatility": {
    "rules": [
      {
        "kind": "range",
        "field": "daily_return_vol_1y_annualized",
        "max": 0.4
      }
    ]
  }
}

{
  "sort": {
    "field": "marketCap_usd",
    "desc": true
  },
  "fields": [
    "full_ticker",
    "companyName",
    "marketCap_usd"
  ]
}

Run a basic screener

Accepts business profile filters, database coverage, market and valuation ranges, returns, volatility ranges, common TTM shorthand fields, and net income. See options.modes.basic for the current filter list.

Run an advanced screener

Accepts every basic filter plus the full advanced contract: metric rule groups, growth/CAGR/multiple filters, composite metric member filters, and volatility rule groups. See options.modes.advanced for the current filter list.

Screener usage notes

For a browser reference to the same screener concepts, see the DFin stock screener.

Get financial statements

Return exact-year or latest annual issuer-presented packages, or explicitly requested standardized statements.

Provide either statements or a bundle, then choose year from 1990 through 2050 for exact FY data or duration from 1 through 20 for latest annual data. Omitting both time selectors returns five periods. period_type accepts annual. Bundles and fields require explicit source=standardized; bundles cannot be combined with fields. REST responses default to ordered rows, and standardized requests may use format=field_map.

The former /financials/single-statement/ and /financials/statement-options/ routes have been retired. Send exact-year requests to this endpoint using a one-item statements array and year. Its response retains the same collection shape for one year and multiple years. The standardized field and bundle catalog follows below.

JSON request fields

ticker string Required

Full DFin ticker including exchange suffix, for example AAPL.US.

statements array of string Optional

Ordered list of one to three statement names. Aliases is, bs, and cf are accepted, deduplicated by first occurrence, and returned canonically.

bundle string Optional

Named compact standardized statement bundle. Set source=standardized; definitions appear in the financial statement catalog.

Allowed marginsearningscost_structurecash_generationcapital_returnsworking_capitalliquidityleverageearnings_qualityroic_inputs

source string Optional Default "as_reported"

Defaults to as_reported individual filing packages. Specify standardized for DFin's normalized UI-visible statement fields.

Allowed standardizedas_reported

format string Optional Default "rows"

Defaults to rows. field_map remains available for standardized statements when a canonical-keyed map is required.

Allowed field_maprows

include_sources boolean Optional Default false

When true, include public-safe SEC references. Standardized responses use compact source_documents references; as_reported packages expose their own safe statement and primary-filing URLs. Defaults to false.

year integer Optional

Exact annual fiscal year from 1990 through 2050. Cannot be combined with duration.

duration integer Optional

Latest-N annual period count, from 1 through 20. Defaults to 5 when year is omitted; cannot be combined with year.

period_type string Optional Default "annual"

Use annual for either source. as_reported returns independent filing packages rather than a shared period axis.

Allowed annual

fields object Optional

Statement-keyed object of non-empty canonical field arrays, available only for custom standardized requests.

Response shape

Standardized responses have one newest-first periods axis. Every standardized row value aligns to it. With source=as_reported, each entry in individual_periods is an independent filing package with its own rows and provenance.

With include_sources=true, standardized references resolve through the response-wide source_documents table. Missing document and type keys inherit aligned period_documents and default_source_type; explicit null suppresses inheritance. A null array entry means no source, while an empty object can still inherit meaningful defaults. Each as-reported package instead exposes its own allowlisted statement_url and primary_filing_url in sources.

For as-reported packages, year is the stored reporting-year label and may differ from the calendar year of period_end; existing records retain their original labels. Latest-N selection follows reporting dates, with stored-year ordering for undated legacy records. Row label and displayed value preserve submitted text, including whitespace and empty labels. Treat them as plain text and escape them when rendering HTML.

Standardized field catalog

These public-visible fields can be selected only with source=standardized. Omit fields to return all available rows.

income_statement

revenue, costOfRevenue, grossProfit, researchAndDevelopmentExpenses, sellingGeneralAndAdministrativeExpenses, depreciationAndAmortization, otherOperatingExpense, operatingIncome, interestAndInvestmentIncome, interestExpense, otherIncome, incomeBeforeTax, incomeTaxExpense, otherIncomeLossNetOfTax, netIncome, minorityInterest, otherNetIncome, netIncomeAvailableToCommon, weightedAverageShsOut, weightedAverageShsOutDil, eps, epsDiluted

balance_sheet

cashAndShortTermInvestments, accountsReceivable, financingReceivablesCurrent, inventories, otherCurrentAssets, totalCurrentAssets, propertyPlantEquipmentNet, operatingLeaseRightOfUseAssets, financingReceivablesNoncurrent, goodwill, otherNoncurrentAssets, totalNoncurrentAssets, totalAssets, shortTermDebtAndCurrentMaturities, accountsPayable, currentLeaseLiabilities, deferredRevenueCurrent, otherCurrentLiabilities, totalCurrentLiabilities, longTermDebt, noncurrentLeaseLiabilities, deferredRevenueNoncurrent, deferredTaxPensionAndAssetRetirementObligations, otherNoncurrentLiabilities, totalNoncurrentLiabilities, totalLiabilities, mezzanineEquity, commonStockAndAdditionalPaidInCapital, retainedEarnings, accumulatedOtherComprehensiveIncomeLoss, noncontrollingInterests, otherEquity, totalEquity, totalLiabilitiesAndEquity

cash_flow

cashFlowStartingLine, depreciationAndAmortization, impairments, cashInterestPaid, cashIncomeTaxesPaid, stockBasedCompensation, receivablesMovement, inventoryMovement, payablesAccrualsMovement, deferredRevenueMovement, otherWorkingCapital, otherOperatingAdjustments, netCashProvidedByOperatingActivities, netCapitalExpenditure, softwareAndIntangibleInvestmentsNet, acquisitionsAndDivestituresNet, investmentIncomeCash, otherInvestingActivities, netCashProvidedByInvestingActivities, netDebtIssuance, netStockIssuance, netDividendsPaid, financeLeasePayments, otherFinancingActivities, netCashProvidedByFinancingActivities, netCashChangeBeforeFx, effectOfForexChangesOnCash, netChangeInCash

Standardized bundles

margins

Core income-statement inputs for gross, operating, and net margin analysis.

• income_statement: revenue, costOfRevenue, grossProfit, operatingIncome, netIncome

earnings

Revenue, earnings, and per-share inputs for earnings analysis.

• income_statement: revenue, netIncome, netIncomeAvailableToCommon, eps, epsDiluted

cost_structure

Visible revenue and operating-cost lines for cost-structure analysis.

• income_statement: revenue, costOfRevenue, researchAndDevelopmentExpenses, sellingGeneralAndAdministrativeExpenses, depreciationAndAmortization, otherOperatingExpense, operatingIncome

cash_generation

Public cash-flow inputs for operating cash generation and reinvestment analysis.

• cash_flow: depreciationAndAmortization, stockBasedCompensation, netCashProvidedByOperatingActivities, netCapitalExpenditure, softwareAndIntangibleInvestmentsNet

capital_returns

Net debt, stock, and dividend cash-flow lines for capital-return analysis.

• cash_flow: netDebtIssuance, netStockIssuance, netDividendsPaid

working_capital

Cash-flow movements in the principal working-capital accounts.

• cash_flow: receivablesMovement, inventoryMovement, payablesAccrualsMovement, deferredRevenueMovement, otherWorkingCapital

liquidity

Current balance-sheet assets and liabilities for liquidity analysis.

• balance_sheet: cashAndShortTermInvestments, accountsReceivable, inventories, totalCurrentAssets, accountsPayable, totalCurrentLiabilities

leverage

Cash, debt, asset, and equity inputs for leverage analysis.

• balance_sheet: cashAndShortTermInvestments, totalAssets, shortTermDebtAndCurrentMaturities, longTermDebt, totalEquity

earnings_quality

Income and cash-flow inputs for comparing earnings with cash generation.

• income_statement: depreciationAndAmortization, netIncome
• cash_flow: depreciationAndAmortization, stockBasedCompensation, netCashProvidedByOperatingActivities

roic_inputs

Operating-profit, tax, cash, debt, and equity inputs for calculated ROIC.

• income_statement: operatingIncome, incomeBeforeTax, incomeTaxExpense
• balance_sheet: cashAndShortTermInvestments, shortTermDebtAndCurrentMaturities, longTermDebt, totalEquity

Get financial ratios

Return annual financial ratio metrics for a stock and fiscal year.

Use this endpoint when the user asks for annual ratio metrics such as margins, returns, leverage, turnover, per-share values, or cash conversion metrics for a specific fiscal year. In v1, ratios are annual only, so period must be FY. Omit fields to return every supported ratio, or provide a comma-separated subset such as grossProfitMargin,returnOnEquity.

Query parameters

ticker string Required

Full DFin ticker including exchange suffix, for example AAPL.US.

year integer Required

Fiscal year for the ratio row.

period string Required

Only FY is accepted in v1 because the current ratio source is annual.

Allowed FY

fields string Optional

Optional comma-separated ratio field names. Omit to return all supported ratio fields.

Response shape

Responses include identity metadata plus a ratios object keyed by ratio field name. When fields is provided, keys follow the requested order after duplicate removal. When fields is omitted, keys follow the canonical annual historical metrics registry order. Decimal values are returned as strings; float ratios are returned as JSON numbers; unavailable values remain null.

Get stock context

Return cached DFin stock context for one ticker.

Use this endpoint to retrieve the cached DFin context for a single company. Submit only the public ticker parameter.

Query parameters

ticker string Required

Ticker must use the ticker.exchange format, for example MSFT.US.

histogram boolean Optional Default false

Defaults to false. Set true only for daily through annual return-distribution analysis; compact return figures remain the default.

Response shape

Responses use stable snake-case public keys while preserving the source values and their existing formatting. Unavailable objects are null, unavailable record lists are empty arrays, and unavailable period-keyed earnings sections are empty objects. Filing, transcript, and research-report availability are reported independently. Owner-specific note status is not included in this REST response.

Get fund movers

Return cached fund movers for one fund ticker.

Use this endpoint for daily or trailing-period movers within the fund's holdings or linked index analytics. Omit delta for daily movers, or send a period such as mtd, 52w, or 3y.

Query parameters

ticker string Required

Full DFin fund ticker including exchange suffix, for example SPY.US.

delta string Optional

Optional trailing period. Omit or leave blank for daily movers. Accepts wtd, mtd, qtd, ytd, or values such as 30d, 52w, 3y, and 10y.

Response shape

Responses mirror the cached fund movers JSON payload. Cache misses may return 202 with {"Processing": "Please try again later."}; retry the same request later to read the prepared cache result.

Get fund high/low

Return cached fund high/low analytics for one fund ticker and trailing period.

Use this endpoint to find holdings or linked-index members near trailing-period highs or lows. Send a required delta; common warmed periods include 7d, 30d, 52w, 2y, 3y, 5y, and 10y.

Query parameters

ticker string Required

Full DFin fund ticker including exchange suffix, for example SPY.US.

delta string Required

Required trailing period. Common warmed periods include 7d, 30d, 52w, 2y, 3y, 5y, and 10y.

margin number Optional Default 0.0

Optional fractional tolerance applied to the high/low thresholds. Use 0.05 for 5%. Accepts finite values from 0 inclusive to less than 1 and defaults to 0.

Response shape

Responses mirror the cached fund high/low JSON payload. Cache misses may return 202 with {"Processing": "Please try again later."}; retry the same request later to read the prepared cache result.

Search securities

Search stocks, funds, ETFs, and indices by name or ticker.

Submit the documented public parameter names, such as securitytype, search_tickers_only, and maxresults. Reverse holdings search is not available in public v1, so build security lookup requests from the parameters documented below.

Query parameters

query string Required

Search text for security lookup, for example Apple, MSFT, or SPY.

securitytype string Optional Default "all"

Security universe to search. Defaults to all.

Allowed allstockfundetfindex

exchange string Optional

Optional exchange filter. Values are uppercased; in ticker-only mode an explicit value overrides a qualified query suffix.

search_tickers_only boolean Optional Default false

When true, search bare or exchange-qualified ticker symbols only and rank exact matches before prefixes.

consolidateduplicatenames boolean Optional Default false

For stocks, select a research-covered representative from equivalent listings while retaining any primary listing that would otherwise be dropped and preserving distinct share classes. Fund behavior is unchanged.

stockisprimaryticker boolean Optional Default false

When true, limit stock results to primary tickers.

fast_search boolean Optional Default false

Optional faster stock-only lookup; valid only with securitytype=stock.

maxresults integer Optional

Optional maximum result count. Use -1 to request all available matching results; 0 and values below -1 are rejected.

Response shape

A successful search returns a JSON result list. Stock rows include identity, country, ISIN, sector, primary-listing and DFin filing/transcript coverage, plus local price, USD market cap, and USD traded volume when available; unavailable local market values are null. Fund and ETF rows include identity, country, ISIN, and fund type. A 204 status means no useful result body is available. Non-200 statuses are passed through with their original status so integrations can diagnose request or lookup issues.

Retrieve artifact

Retrieve a temporary artifact produced by an authenticated DFin operation. Omit index to download the complete artifact or provide one zero-based index when the originating response says indexed access is supported. The token is the authorization capability for the temporary result; do not add an API key, alter the returned URL, or expose the token in logs. Document-search artifacts are reusable until their 60-minute expiry. For note-search artifacts, each index is available once and the original complete package is available once; a complete download invalidates all remaining indexes. Stock-context artifacts are complete single-use JSON packages and do not support indexed access. Retrieval never extends the lifetime.

Query parameters

index integer Optional

min 0

Response shape

Omit index to download the complete JSON package. Supply a zero-based index only when the originating result says indexed access is supported; the response is then that result object directly. The endpoint accepts no other query parameters and uses Cache-Control: no-store.