REST reference

Soon[28 endpoints · 5 restricted for public keys]View as Markdown

Stocks

US public equity markets — fundamentals, filings, prices, and corporate actions sourced from SEC EDGAR and market data providers.

Paths are relative to https://api.agentdatasets.com. Every endpoint mirrors an MCP tool over the same service layer — the tool catalog documents the same operations for MCP clients.

GET/v1/stocks/balance-sheets

Balance Sheets

Normalized balance sheets for one company, newest period first.

ticker_or_cik takes a ticker symbol or a numeric SEC CIK; a CIK reaches a filer whose symbol was later reused by another listing, and data.ticker is then that company's active symbol or null.

period=ttm is rejected (bad_parameter): a balance sheet is a point-in-time snapshot, so a trailing-twelve-month frame is undefined. data.reporting_standard is us-gaap, ifrs-full, or null when legacy rows have not observed the taxonomy yet. currency rides on every value as filed; IFRS filers report in their home currency and values are never silently converted to USD.

Parameters

NameTypeRequiredDefaultConstraintsDescription
ticker_or_cikstringYes—min length 1Ticker symbol (AAPL, BRK.B) or SEC CIK (320193)
period"annual" | "quarterly" | "ttm"No"annual"—Fiscal frame: annual (FY) or quarterly (Q1-Q4); ttm is rejected. Known IFRS 20-F/FPI filers are annual-only: quarterly returns out_of_coverage.
limitintegerNo4min 1, max 12Fiscal periods to return, newest first
cursorstring | nullNo——Opaque pagination cursor from a previous response's pagination.next_cursor; omit to start from the newest.
as_reportedbooleanNofalse—Serve as-originally-reported values instead of latest restated values. Keep as_reported constant while paging. Before the next statement ingest, this mode raises out_of_coverage. In meta.restatements, reported lines carry original and superseding accessions; arithmetic-derived Q4, non-fiscal-year TTM, YTD-difference, and FCF lines carry null lineage, while a TTM matching a reported fiscal year carries the annual accessions.

Example request

Required parameters only, with values taken from the schema. Optional parameters are in the table above.

[ BASH ]
curl --fail --silent --show-error \
  --header "X-API-KEY: adk_..." \
  "https://api.agentdatasets.com/v1/stocks/balance-sheets?ticker_or_cik=TICKER_OR_CIK"

Response

200 Successful Response · expand a branch to see its fields.

  • dataBalanceSheetsDatarequiredBalance-sheet ``data``: identity + the bounded, newest-first list.
    • tickerstringrequirednullable
    • cikintegerrequired
    • company_namestringrequired
    • period_type"annual" | "quarterly" | "ttm"required
    • reporting_standard"us-gaap" | "ifrs-full"requirednullable
    • statementsarray<BalanceSheet>required
      • fiscal_yearintegerrequired
      • fiscal_period"FY" | "Q1" | "Q2" | "Q3" | "Q4"required
      • period_type"annual" | "quarterly" | "ttm"required
      • period_startstring (date)required
      • period_endstring (date)required
      • linesmap<string, StatementValue>required
        • [key: string]StatementValueOne line's value with its own attribution. ``as_of`` is when we last saw this value (restatements refresh it in place, ADR 0001); ``accession_number`` is the EDGAR filing the value was taken from, so an agent can cite or fetch the source document.
          • valuestringrequiredpattern ^(?!^[-+.]*$)[+-]?0*\d*\.?\d*$
          • unitstringrequired
          • currencystringrequirednullable
          • as_ofstring (date-time)required
          • accession_numberstringrequirednullable
  • metaStatementsMetarequiredStatement provenance plus source-document view and restatement lineage.
    • sourcestringrequired
    • as_ofstring (date-time) | string (date)nullable
    • as_reportedbooleandefault false
    • restatementsarray<RestatedLine>nullable
      • fiscal_yearintegerrequired
      • fiscal_period"FY" | "Q1" | "Q2" | "Q3" | "Q4"required
      • period_type"annual" | "quarterly" | "ttm"required
      • line_keystringrequired
      • original_accession_numberstringrequirednullable
      • superseding_accession_numberstringrequirednullable
  • paginationPaginationnullable
    • limitintegerrequired
    • has_morebooleanrequired
    • next_cursorstringnullable

GET/v1/stocks/beneficial-owners

Beneficial Owners

Current >5% beneficial owners of one company, latest event per person.

Parameters

NameTypeRequiredDefaultConstraintsDescription
tickerstringYes—min length 1Ticker symbol (AAPL, BRK.B)
limitintegerNo20min 1, max 100Owners to return, newest first
cursorstring | nullNo——Opaque pagination cursor from a previous response's pagination.next_cursor; omit to start from the newest.

Example request

Required parameters only, with values taken from the schema. Optional parameters are in the table above.

[ BASH ]
curl --fail --silent --show-error \
  --header "X-API-KEY: adk_..." \
  "https://api.agentdatasets.com/v1/stocks/beneficial-owners?ticker=TICKER"

Response

200 Successful Response · expand a branch to see its fields.

  • dataBeneficialOwnersDatarequired
    • tickerstringrequirednullable
    • cikintegerrequired
    • company_namestringrequired
    • coverage_startstring (date)required
    • ownersarray<BeneficialOwner>required
      • namestringrequired
      • cikintegerrequirednullable
      • person_typestringrequirednullable
      • percent_of_classstringrequirednullablepattern ^(?!^[-+.]*$)[+-]?0*\d*\.?\d*$
      • shares_beneficially_ownedstringrequirednullablepattern ^(?!^[-+.]*$)[+-]?0*\d*\.?\d*$
      • schedule_typestringrequired
      • submission_typestringrequired
      • amendment_numberintegerrequirednullable
      • date_of_eventstring (date)requirednullable
      • filed_datestring (date)required
      • accession_numberstringrequired
  • metaMetarequiredResult-level provenance. ``source`` is a stable connector identifier (e.g. ``sec_edgar_companyfacts``); ``as_of`` is the freshest value-level ``as_of`` on the returned page, or ``None`` when the page is empty. Event-grained sources carry an aware datetime; date-grained sources (e.g. an SEC filing's report period) carry a plain date.
    • sourcestringrequired
    • as_ofstring (date-time) | string (date)nullable
  • paginationPaginationnullable
    • limitintegerrequired
    • has_morebooleanrequired
    • next_cursorstringnullable

GET/v1/stocks/cash-flow-statements

Cash Flow Statements

Normalized cash-flow statements for one company, newest period first.

ticker_or_cik takes a ticker symbol or a numeric SEC CIK; a CIK reaches a filer whose symbol was later reused by another listing, and data.ticker is then that company's active symbol or null.

data.reporting_standard is us-gaap, ifrs-full, or null when legacy rows have not observed the taxonomy yet. currency rides on every value as filed; IFRS filers report in their home currency and values are never silently converted to USD.

Parameters

NameTypeRequiredDefaultConstraintsDescription
ticker_or_cikstringYes—min length 1Ticker symbol (AAPL, BRK.B) or SEC CIK (320193)
period"annual" | "quarterly" | "ttm"No"annual"—Fiscal frame: annual (FY), quarterly (Q1-Q4), or ttm. Known IFRS 20-F/FPI filers are annual-only: quarterly returns out_of_coverage, while ttm returns an empty list.
limitintegerNo4min 1, max 12Fiscal periods to return, newest first
cursorstring | nullNo——Opaque pagination cursor from a previous response's pagination.next_cursor; omit to start from the newest.
as_reportedbooleanNofalse—Serve as-originally-reported values instead of latest restated values. Keep as_reported constant while paging. Before the next statement ingest, this mode raises out_of_coverage. In meta.restatements, reported lines carry original and superseding accessions; arithmetic-derived Q4, non-fiscal-year TTM, YTD-difference, and FCF lines carry null lineage, while a TTM matching a reported fiscal year carries the annual accessions.

Example request

Required parameters only, with values taken from the schema. Optional parameters are in the table above.

[ BASH ]
curl --fail --silent --show-error \
  --header "X-API-KEY: adk_..." \
  "https://api.agentdatasets.com/v1/stocks/cash-flow-statements?ticker_or_cik=TICKER_OR_CIK"

Response

200 Successful Response · expand a branch to see its fields.

  • dataCashFlowStatementsDatarequiredCash-flow ``data``: identity + the bounded, newest-first list.
    • tickerstringrequirednullable
    • cikintegerrequired
    • company_namestringrequired
    • period_type"annual" | "quarterly" | "ttm"required
    • reporting_standard"us-gaap" | "ifrs-full"requirednullable
    • statementsarray<CashFlowStatement>required
      • fiscal_yearintegerrequired
      • fiscal_period"FY" | "Q1" | "Q2" | "Q3" | "Q4"required
      • period_type"annual" | "quarterly" | "ttm"required
      • period_startstring (date)required
      • period_endstring (date)required
      • linesmap<string, StatementValue>required
        • [key: string]StatementValueOne line's value with its own attribution. ``as_of`` is when we last saw this value (restatements refresh it in place, ADR 0001); ``accession_number`` is the EDGAR filing the value was taken from, so an agent can cite or fetch the source document.
          • valuestringrequiredpattern ^(?!^[-+.]*$)[+-]?0*\d*\.?\d*$
          • unitstringrequired
          • currencystringrequirednullable
          • as_ofstring (date-time)required
          • accession_numberstringrequirednullable
  • metaStatementsMetarequiredStatement provenance plus source-document view and restatement lineage.
    • sourcestringrequired
    • as_ofstring (date-time) | string (date)nullable
    • as_reportedbooleandefault false
    • restatementsarray<RestatedLine>nullable
      • fiscal_yearintegerrequired
      • fiscal_period"FY" | "Q1" | "Q2" | "Q3" | "Q4"required
      • period_type"annual" | "quarterly" | "ttm"required
      • line_keystringrequired
      • original_accession_numberstringrequirednullable
      • superseding_accession_numberstringrequirednullable
  • paginationPaginationnullable
    • limitintegerrequired
    • has_morebooleanrequired
    • next_cursorstringnullable

GET/v1/stocks/company

Company

Public-key response

Provider-licensed price coverage is omitted for public keys (reported unavailable); omitted sources are disclosed via meta.restricted_omitted.

Identity + dataset-coverage profile for one company.

Parameters

NameTypeRequiredDefaultConstraintsDescription
ticker_or_cikstringYes——Exact ticker (AAPL, BRK.B) or numeric CIK

Example request

Required parameters only, with values taken from the schema. Optional parameters are in the table above.

[ BASH ]
curl --fail --silent --show-error \
  --header "X-API-KEY: adk_..." \
  "https://api.agentdatasets.com/v1/stocks/company?ticker_or_cik=TICKER_OR_CIK"

Response

200 Successful Response · expand a branch to see its fields.

  • dataCompanyFactsDatarequiredThe envelope ``data`` for a company profile. ``fiscal_year_end`` is the ``MM-DD`` of the company's most recent annual fiscal period (``None`` if we hold no annual statements yet — it is derived from data, not a static attribute). ``latest_filing_date`` is the newest filing we hold. ``coverage`` says which datasets exist for this company and over what span.
    • cikintegerrequired
    • namestringrequired
    • tickersarray<TickerListing>required
      • symbolstringrequired
      • exchangestringrequirednullable
      • activebooleanrequired
      • valid_fromstring (date)required
      • valid_tostring (date)requirednullable
    • exchangestringrequirednullable
    • sectorstringrequirednullable
    • sic_codestringrequirednullable
    • sic_descriptionstringrequirednullable
    • fiscal_year_endstringrequirednullable
    • latest_filing_datestring (date)requirednullable
    • coverageCoveragerequiredPer-dataset coverage for one company — the anti-hallucination summary. ``financials`` spans normalized statement lines (income/balance/cash-flow) by fiscal period; ``prices`` spans daily bars across the company's listings; ``filings`` spans SEC filing metadata by filed date.
      • financialsCoverageEntryrequiredWhether we hold one dataset for a company, and the span we hold. ``available`` is false when we hold nothing; ``since``/``through`` are then ``None``. When true, they bound the data we can actually serve — an agent should not ask for observations outside ``[since, through]``.
        • availablebooleanrequired
        • sincestring (date)nullable
        • throughstring (date)nullable
      • pricesCoverageEntryrequiredWhether we hold one dataset for a company, and the span we hold. ``available`` is false when we hold nothing; ``since``/``through`` are then ``None``. When true, they bound the data we can actually serve — an agent should not ask for observations outside ``[since, through]``.
        • availablebooleanrequired
        • sincestring (date)nullable
        • throughstring (date)nullable
      • filingsCoverageEntryrequiredWhether we hold one dataset for a company, and the span we hold. ``available`` is false when we hold nothing; ``since``/``through`` are then ``None``. When true, they bound the data we can actually serve — an agent should not ask for observations outside ``[since, through]``.
        • availablebooleanrequired
        • sincestring (date)nullable
        • throughstring (date)nullable
  • metaCompanyMetarequiredCompany-profile meta. ``restricted_omitted`` lists the distinct restricted source tags whose rows were excluded from the coverage summary on the public surface (``None`` on the internal surface or when nothing was excluded).
    • sourcestringrequired
    • as_ofstring (date-time) | string (date)nullable
    • restricted_omittedarray<string>nullable
  • paginationPaginationnullable
    • limitintegerrequired
    • has_morebooleanrequired
    • next_cursorstringnullable

GET/v1/stocks/company-events

Company Events

Typed 8-K material events for one company, newest first.

Parameters

NameTypeRequiredDefaultConstraintsDescription
ticker_or_cikstringYes—min length 1Ticker symbol (AAPL) or SEC CIK (320193)
categorystring | nullNo——Optional event category filter: results_announcement, ma_completion, material_agreement, leadership_change, non_reliance, auditor_change, bankruptcy, delisting_notice, impairment, restructuring, financial_obligation, change_in_control, reg_fd, or other
startstring (date) | nullNo——Earliest event date, inclusive (YYYY-MM-DD)
endstring (date) | nullNo——Latest event date, inclusive (YYYY-MM-DD)
limitintegerNo20min 1, max 100Events to return, newest first
cursorstring | nullNo——Opaque pagination cursor from a previous response's pagination.next_cursor; omit to start from the newest.

Example request

Required parameters only, with values taken from the schema. Optional parameters are in the table above.

[ BASH ]
curl --fail --silent --show-error \
  --header "X-API-KEY: adk_..." \
  "https://api.agentdatasets.com/v1/stocks/company-events?ticker_or_cik=TICKER_OR_CIK"

Response

200 Successful Response · expand a branch to see its fields.

  • dataCompanyEventsDatarequiredThe envelope ``data``: company identity + the bounded events list. ``events`` is newest-first by ``(event_date, accession_number, item_code)``. ``ticker`` is null when the subject was resolved by CIK and has no active ticker mapping — 8-K filers are not all listed.
    • tickerstringrequirednullable
    • cikintegerrequired
    • company_namestringrequired
    • eventsarray<EventSummary>required
      • event_datestring (date)required
      • filed_datestring (date)required
      • form_typestringrequired
      • item_codestringrequired
      • category"results_announcement" | "ma_completion" | "material_agreement" | "leadership_change" | "non_reliance" | "auditor_change" | "bankruptcy" | "delisting_notice" | "impairment" | "restructuring" | "financial_obligation" | "change_in_control" | "reg_fd" | "other"requiredDocumented buckets for 8-K item codes (issue #41 §4).
      • accession_numberstringrequired
      • primary_document_urlstringrequirednullable
      • index_urlstringrequired
      • sourcestringrequired
      • as_ofstring (date-time)required
  • metaMetarequiredResult-level provenance. ``source`` is a stable connector identifier (e.g. ``sec_edgar_companyfacts``); ``as_of`` is the freshest value-level ``as_of`` on the returned page, or ``None`` when the page is empty. Event-grained sources carry an aware datetime; date-grained sources (e.g. an SEC filing's report period) carry a plain date.
    • sourcestringrequired
    • as_ofstring (date-time) | string (date)nullable
  • paginationPaginationnullable
    • limitintegerrequired
    • has_morebooleanrequired
    • next_cursorstringnullable

GET/v1/stocks/corporate-actions

Corporate Actions

Public-key response

Provider-sourced dividend and split events are omitted for public keys; the response flags the omission via meta.restricted_omitted.

Typed corporate-action events for one company, newest first.

Parameters

NameTypeRequiredDefaultConstraintsDescription
ticker_or_cikstringYes—min length 1Ticker symbol (AAPL) or SEC CIK (320193)
action_typestring | nullNo——Optional event type filter: dividend, split, delisting, ticker_change, or merger_acquisition
start_datestring (date) | nullNo——Earliest event date, inclusive (YYYY-MM-DD)
end_datestring (date) | nullNo——Latest event date, inclusive (YYYY-MM-DD)
limitintegerNo100min 1, max 1000Corporate-action events to return, newest first
cursorstring | nullNo——Opaque pagination cursor from a previous response's pagination.next_cursor; omit to start from the newest.

Example request

Required parameters only, with values taken from the schema. Optional parameters are in the table above.

[ BASH ]
curl --fail --silent --show-error \
  --header "X-API-KEY: adk_..." \
  "https://api.agentdatasets.com/v1/stocks/corporate-actions?ticker_or_cik=TICKER_OR_CIK"

Response

200 Successful Response · expand a branch to see its fields.

  • dataCorporateActionsDatarequired
    • tickerstringrequirednullable
    • cikintegerrequired
    • company_namestringrequired
    • action_type"dividend" | "split" | "delisting" | "ticker_change" | "merger_acquisition"requirednullable
    • actionsarray<CorporateActionEvent>required
      • action_type"dividend" | "split" | "delisting" | "ticker_change" | "merger_acquisition"required
      • event_datestring (date)required
      • amountstringnullablepattern ^(?!^[-+.]*$)[+-]?0*\d*\.?\d*$
      • currencystringnullable
      • ratiostringnullablepattern ^(?!^[-+.]*$)[+-]?0*\d*\.?\d*$
      • record_datestring (date)nullable
      • pay_datestring (date)nullable
      • accession_numberstringnullable
      • detailsobjectnullable
      • sourcestringrequired
      • non_redistributablebooleanrequired
      • as_ofstring (date-time)required
  • metaCorporateActionsMetarequired
    • sourcestringrequired
    • as_ofstring (date-time) | string (date)nullable
    • non_redistributablebooleandefault false
    • restricted_omittedarray<string>nullable
  • paginationPaginationnullable
    • limitintegerrequired
    • has_morebooleanrequired
    • next_cursorstringnullable

GET/v1/stocks/earnings-dates

Earnings Dates

Announcement history plus an estimated next earnings window.

Estimates come from announcement cadence when possible and otherwise from an active filing-cadence fallback. They are never confirmed schedules.

Parameters

NameTypeRequiredDefaultConstraintsDescription
ticker_or_cikstringYes——Ticker symbol (AAPL, BRK.B) or CIK (320193, 0000320193)
limitintegerNo8min 1, max 40Announcement-history rows; default 8, max 40

Example request

Required parameters only, with values taken from the schema. Optional parameters are in the table above.

[ BASH ]
curl --fail --silent --show-error \
  --header "X-API-KEY: adk_..." \
  "https://api.agentdatasets.com/v1/stocks/earnings-dates?ticker_or_cik=TICKER_OR_CIK"

Response

200 Successful Response · expand a branch to see its fields.

  • dataEarningsDatesDatarequiredCompany identity, bounded announcement history, and the next estimate.
    • tickerstringrequirednullable
    • cikintegerrequired
    • company_namestringrequired
    • historyarray<EarningsAnnouncement>required
      • announced_onstring (date)required
      • filed_onstring (date)required
      • form_typestringrequired
      • accession_numberstringrequired
      • primary_document_urlstringrequirednullable
      • index_urlstringrequired
      • sourcestringrequired
      • as_ofstring (date-time)required
    • nextNextEarningsEstimaterequirednullable
      • window_startstring (date)required
      • window_endstring (date)required
      • basis"derived-from-announcement-cadence" | "derived-from-filing-cadence"required
      • cadence"quarterly" | "annual"required
      • observationsintegerrequired
      • median_gap_daysintegerrequirednullable
      • stalebooleanrequired
      • reasonstringrequirednullable
      • sourcestringrequired
      • as_ofstring (date-time)required
    • reasonstringrequirednullable
  • metaMetarequiredResult-level provenance. ``source`` is a stable connector identifier (e.g. ``sec_edgar_companyfacts``); ``as_of`` is the freshest value-level ``as_of`` on the returned page, or ``None`` when the page is empty. Event-grained sources carry an aware datetime; date-grained sources (e.g. an SEC filing's report period) carry a plain date.
    • sourcestringrequired
    • as_ofstring (date-time) | string (date)nullable
  • paginationPaginationnullable
    • limitintegerrequired
    • has_morebooleanrequired
    • next_cursorstringnullable

Search Events Route

One 8-K event category across the ingested universe, newest first.

Parameters

NameTypeRequiredDefaultConstraintsDescription
categorystringYes—min length 1Event category: results_announcement, ma_completion, material_agreement, leadership_change, non_reliance, auditor_change, bankruptcy, delisting_notice, impairment, restructuring, financial_obligation, change_in_control, reg_fd, or other
tickersarray<string> | nullNo—max items 20Repeated ticker filters, e.g. AAPL, MSFT
startstring (date) | nullNo——Earliest event date, inclusive (YYYY-MM-DD)
endstring (date) | nullNo——Latest event date, inclusive (YYYY-MM-DD)
limitintegerNo20min 1, max 100Events to return, newest first
cursorstring | nullNo——Opaque pagination cursor from a previous response's pagination.next_cursor; omit to start from the newest.

Example request

Required parameters only, with values taken from the schema. Optional parameters are in the table above.

[ BASH ]
curl --fail --silent --show-error \
  --header "X-API-KEY: adk_..." \
  "https://api.agentdatasets.com/v1/stocks/events/search?category=CATEGORY"

Response

200 Successful Response · expand a branch to see its fields.

  • dataEventSearchDatarequiredFilter echoes plus the bounded newest-first cross-universe page. Echoes are the canonicalized values that were applied; ``None`` means the filter was omitted (``category`` is required, so it is always present).
    • category"results_announcement" | "ma_completion" | "material_agreement" | "leadership_change" | "non_reliance" | "auditor_change" | "bankruptcy" | "delisting_notice" | "impairment" | "restructuring" | "financial_obligation" | "change_in_control" | "reg_fd" | "other"requiredDocumented buckets for 8-K item codes (issue #41 §4).
    • tickersarray<string>requirednullable
    • startstring (date)requirednullable
    • endstring (date)requirednullable
    • eventsarray<EventSearchRow>required
      • event_datestring (date)required
      • filed_datestring (date)required
      • form_typestringrequired
      • item_codestringrequired
      • category"results_announcement" | "ma_completion" | "material_agreement" | "leadership_change" | "non_reliance" | "auditor_change" | "bankruptcy" | "delisting_notice" | "impairment" | "restructuring" | "financial_obligation" | "change_in_control" | "reg_fd" | "other"requiredDocumented buckets for 8-K item codes (issue #41 §4).
      • accession_numberstringrequired
      • primary_document_urlstringrequirednullable
      • index_urlstringrequired
      • sourcestringrequired
      • as_ofstring (date-time)required
      • tickerstringrequirednullable
      • cikintegerrequired
      • company_namestringrequired
  • metaMetarequiredResult-level provenance. ``source`` is a stable connector identifier (e.g. ``sec_edgar_companyfacts``); ``as_of`` is the freshest value-level ``as_of`` on the returned page, or ``None`` when the page is empty. Event-grained sources carry an aware datetime; date-grained sources (e.g. an SEC filing's report period) carry a plain date.
    • sourcestringrequired
    • as_ofstring (date-time) | string (date)nullable
  • paginationPaginationnullable
    • limitintegerrequired
    • has_morebooleanrequired
    • next_cursorstringnullable

GET/v1/stocks/executive-compensation

Executive Compensation

SEC pay-versus-performance rows (DEF 14A Item 402(v)) per fiscal year, newest first: PEO and average-NEO compensation, company and peer-group TSR, net income, and the company-selected measure.

Parameters

NameTypeRequiredDefaultConstraintsDescription
tickerstringYes—min length 1Ticker symbol, e.g. AAPL or BRK.B
limitintegerNo4min 1, max 12Fiscal years to return, newest first. Counts years, not rows: a year with multiple PEOs returns one row per PEO.
cursorstring | nullNo——Opaque pagination cursor from a previous response's pagination.next_cursor; omit to start from the newest fiscal year.

Example request

Required parameters only, with values taken from the schema. Optional parameters are in the table above.

[ BASH ]
curl --fail --silent --show-error \
  --header "X-API-KEY: adk_..." \
  "https://api.agentdatasets.com/v1/stocks/executive-compensation?ticker=TICKER"

Response

200 Successful Response · expand a branch to see its fields.

  • dataExecutiveCompensationDatarequiredThe envelope ``data``: company identity echo + the bounded, newest-first row list. ``ticker`` echoes the canonical (SEC) form of the requested symbol, which may differ from the raw query ("brk.b" → "BRK-B").
    • tickerstringrequired
    • cikintegerrequired
    • company_namestringrequired
    • rowsarray<PayVersusPerformanceRow>required
      • fiscal_yearintegerrequired
      • period_startstring (date)required
      • period_endstring (date)required
      • peo_memberstringrequired
      • peo_namestringrequirednullable
      • company_selected_measure_namestringrequirednullable
      • measuresmap<string, PvpValue>required
        • [key: string]PvpValueOne measure's value with its own attribution. Mirrors the statements surface's ``StatementValue``: ``as_of`` is when we last saw this value (a corrected proxy refreshes it in place); ``accession_number`` is the EDGAR filing the value was taken from, so an agent can cite or fetch the source document.
          • valuestringrequiredpattern ^(?!^[-+.]*$)[+-]?0*\d*\.?\d*$
          • unitstringrequired
          • currencystringrequirednullable
          • as_ofstring (date-time)required
          • accession_numberstringrequirednullable
  • metaMetarequiredResult-level provenance. ``source`` is a stable connector identifier (e.g. ``sec_edgar_companyfacts``); ``as_of`` is the freshest value-level ``as_of`` on the returned page, or ``None`` when the page is empty. Event-grained sources carry an aware datetime; date-grained sources (e.g. an SEC filing's report period) carry a plain date.
    • sourcestringrequired
    • as_ofstring (date-time) | string (date)nullable
  • paginationPaginationnullable
    • limitintegerrequired
    • has_morebooleanrequired
    • next_cursorstringnullable

GET/v1/stocks/expected-report

Expected Report

Estimate when one company will next file a periodic report (10-K/10-Q/20-F).

An estimate derived from the company's own filing cadence — the median lag from period end to filed date over its last 8 periodic filings — never a scheduled or announced date; companies announce real reporting dates in press releases this platform does not ingest. A company with fewer than two periodic filings returns estimate: null with a reason; a filer that appears to have stopped returns the derivation flagged stale: true.

Parameters

NameTypeRequiredDefaultConstraintsDescription
ticker_or_cikstringYes—min length 1Ticker symbol (AAPL, BRK.B) or CIK (320193, 0000320193)

Example request

Required parameters only, with values taken from the schema. Optional parameters are in the table above.

[ BASH ]
curl --fail --silent --show-error \
  --header "X-API-KEY: adk_..." \
  "https://api.agentdatasets.com/v1/stocks/expected-report?ticker_or_cik=TICKER_OR_CIK"

Response

200 Successful Response · expand a branch to see its fields.

  • dataExpectedReportDatarequiredOne company's identity echo plus its estimate, or an honest gap. ``estimate`` is ``null`` when the company has fewer than :data:`MIN_OBSERVATIONS` comparable-form filings for its next cycle; ``reason`` then names the gap. ``reason`` is also set — alongside a full ``estimate`` — when the filer is stale or its estimated window has already passed. It is ``null`` only for an ordinary active filer with a current or future window.
    • tickerstringrequirednullable
    • cikintegerrequired
    • company_namestringrequired
    • estimateExpectedReportrequirednullable
      • expected_period_endstring (date)required
      • expected_filing_windowExpectedFilingWindowrequiredThe inclusive date range the next periodic filing is estimated to land in. A range, never a day: see the module docstring on why a single date would misrepresent an estimate as a schedule.
        • earlieststring (date)required
        • lateststring (date)required
      • cadence"quarterly" | "annual"required
      • basis"derived-from-filing-cadence"default "derived-from-filing-cadence"
      • basis_lag"median"default "median"
      • median_lag_daysintegerrequired
      • min_lag_daysintegerrequired
      • max_lag_daysintegerrequired
      • observationsintegerrequired
      • last_filedLastPeriodicFilingrequiredThe filing the whole estimate is anchored on. The company's most recent periodic filing carrying a ``period_of_report``, by ``filed_date`` (ties broken by period and accession, so the anchor is deterministic when several land the same day).
        • form_typestringrequired
        • period_of_reportstring (date)required
        • filed_datestring (date)required
        • accession_numberstringrequired
      • stalebooleanrequired
      • sourcestringrequired
      • as_ofstring (date-time)required
    • reasonstringrequirednullable
  • metaMetarequiredResult-level provenance. ``source`` is a stable connector identifier (e.g. ``sec_edgar_companyfacts``); ``as_of`` is the freshest value-level ``as_of`` on the returned page, or ``None`` when the page is empty. Event-grained sources carry an aware datetime; date-grained sources (e.g. an SEC filing's report period) carry a plain date.
    • sourcestringrequired
    • as_ofstring (date-time) | string (date)nullable
  • paginationPaginationnullable
    • limitintegerrequired
    • has_morebooleanrequired
    • next_cursorstringnullable

GET/v1/stocks/expected-reports

Expected Reports

Companies whose estimated filing window overlaps the next days_ahead days.

Soonest-first, cursor-paged, and estimates only — derived from each company's own filing cadence, not from announced reporting dates. Filers with too little history and filers that appear to have stopped are excluded.

Parameters

NameTypeRequiredDefaultConstraintsDescription
days_aheadintegerNo7min 1, max 30How far ahead to look, in days from today
limitintegerNo20min 1, max 100Companies per page
cursorstring | nullNo——Opaque token from a previous response's next_cursor

Example request

Required parameters only, with values taken from the schema. Optional parameters are in the table above.

[ BASH ]
curl --fail --silent --show-error \
  --header "X-API-KEY: adk_..." \
  "https://api.agentdatasets.com/v1/stocks/expected-reports"

Response

200 Successful Response · expand a branch to see its fields.

  • dataExpectedReportSearchDatarequiredThe window echo plus the bounded, soonest-first page of estimates.
    • window_startstring (date)required
    • window_endstring (date)required
    • days_aheadintegerrequired
    • reportsarray<ExpectedReportRow>required
      • expected_period_endstring (date)required
      • expected_filing_windowExpectedFilingWindowrequiredThe inclusive date range the next periodic filing is estimated to land in. A range, never a day: see the module docstring on why a single date would misrepresent an estimate as a schedule.
        • earlieststring (date)required
        • lateststring (date)required
      • cadence"quarterly" | "annual"required
      • basis"derived-from-filing-cadence"default "derived-from-filing-cadence"
      • basis_lag"median"default "median"
      • median_lag_daysintegerrequired
      • min_lag_daysintegerrequired
      • max_lag_daysintegerrequired
      • observationsintegerrequired
      • last_filedLastPeriodicFilingrequiredThe filing the whole estimate is anchored on. The company's most recent periodic filing carrying a ``period_of_report``, by ``filed_date`` (ties broken by period and accession, so the anchor is deterministic when several land the same day).
        • form_typestringrequired
        • period_of_reportstring (date)required
        • filed_datestring (date)required
        • accession_numberstringrequired
      • stalebooleanrequired
      • sourcestringrequired
      • as_ofstring (date-time)required
      • tickerstringrequirednullable
      • cikintegerrequired
      • company_namestringrequired
  • metaMetarequiredResult-level provenance. ``source`` is a stable connector identifier (e.g. ``sec_edgar_companyfacts``); ``as_of`` is the freshest value-level ``as_of`` on the returned page, or ``None`` when the page is empty. Event-grained sources carry an aware datetime; date-grained sources (e.g. an SEC filing's report period) carry a plain date.
    • sourcestringrequired
    • as_ofstring (date-time) | string (date)nullable
  • paginationPaginationnullable
    • limitintegerrequired
    • has_morebooleanrequired
    • next_cursorstringnullable

GET/v1/stocks/filing-section

Filing Section

One 10-K/10-Q item as a bounded character-offset text page.

Parameters

NameTypeRequiredDefaultConstraintsDescription
ticker_or_cikstringYes—min length 1Exact ticker (AAPL) or SEC CIK (320193)
itemstringYes——Filing item code, e.g. ITEM_1A, Item 7, or Part I Item 2
accession_numberstring | nullNo——Exact SEC accession; mutually exclusive with form_type
form_typestring | nullNo——Latest indexed 10-K or 10-Q; mutually exclusive with accession
page_charsintegerNo10000min 1000, max 25000Maximum characters in this page
cursorstring | nullNo——Opaque pagination.next_cursor from the previous character page

Example request

Required parameters only, with values taken from the schema. Optional parameters are in the table above.

[ BASH ]
curl --fail --silent --show-error \
  --header "X-API-KEY: adk_..." \
  "https://api.agentdatasets.com/v1/stocks/filing-section?ticker_or_cik=TICKER_OR_CIK&item=ITEM"

Response

200 Successful Response · expand a branch to see its fields.

  • dataFilingSectionDatarequiredOne bounded character page from one canonical filing section.
    • tickerstringrequirednullable
    • cikintegerrequired
    • company_namestringrequired
    • accession_numberstringrequired
    • form_typestringrequired
    • filed_datestring (date)required
    • period_of_reportstring (date)requirednullable
    • item_codestringrequired
    • item_titlestringrequirednullable
    • document_urlstringrequired
    • char_startintegerrequired
    • char_endintegerrequired
    • section_char_countintegerrequired
    • textstringrequired
  • metaMetarequiredResult-level provenance. ``source`` is a stable connector identifier (e.g. ``sec_edgar_companyfacts``); ``as_of`` is the freshest value-level ``as_of`` on the returned page, or ``None`` when the page is empty. Event-grained sources carry an aware datetime; date-grained sources (e.g. an SEC filing's report period) carry a plain date.
    • sourcestringrequired
    • as_ofstring (date-time) | string (date)nullable
  • paginationPaginationnullable
    • limitintegerrequired
    • has_morebooleanrequired
    • next_cursorstringnullable

GET/v1/stocks/filings

Sec Filings

SEC EDGAR filings metadata + sec.gov links for one company, newest first.

Parameters

NameTypeRequiredDefaultConstraintsDescription
ticker_or_cikstringYes—min length 1Ticker symbol (AAPL) or SEC CIK (320193)
form_typestring | nullNo——Exact EDGAR form filter, e.g. 10-K, 10-Q, 8-K (amendments end in /A)
startstring (date) | nullNo——Earliest filing date, inclusive (YYYY-MM-DD)
endstring (date) | nullNo——Latest filing date, inclusive (YYYY-MM-DD)
limitintegerNo100min 1, max 1000Filings to return, newest first
cursorstring | nullNo——Opaque pagination cursor from a previous response's pagination.next_cursor; omit to start from the newest.

Example request

Required parameters only, with values taken from the schema. Optional parameters are in the table above.

[ BASH ]
curl --fail --silent --show-error \
  --header "X-API-KEY: adk_..." \
  "https://api.agentdatasets.com/v1/stocks/filings?ticker_or_cik=TICKER_OR_CIK"

Response

200 Successful Response · expand a branch to see its fields.

  • dataSecFilingsDatarequiredThe envelope ``data``: company identity + the bounded filings list. ``filings`` is newest-first by ``(filed_date, accession_number)``. ``ticker`` is the company's active symbol when it has one and ``None`` when the subject was resolved by CIK and has no live ticker mapping — filings exist for filers that were never listed. Result-level provenance (``source``, freshest ``as_of``) rides on the envelope ``meta``; cursor paging on its ``pagination``.
    • tickerstringrequirednullable
    • cikintegerrequired
    • company_namestringrequired
    • filingsarray<FilingSummary>required
      • form_typestringrequired
      • filed_datestring (date)required
      • period_of_reportstring (date)requirednullable
      • accession_numberstringrequired
      • primary_document_urlstringrequirednullable
      • index_urlstringrequired
      • as_ofstring (date-time)required
  • metaMetarequiredResult-level provenance. ``source`` is a stable connector identifier (e.g. ``sec_edgar_companyfacts``); ``as_of`` is the freshest value-level ``as_of`` on the returned page, or ``None`` when the page is empty. Event-grained sources carry an aware datetime; date-grained sources (e.g. an SEC filing's report period) carry a plain date.
    • sourcestringrequired
    • as_ofstring (date-time) | string (date)nullable
  • paginationPaginationnullable
    • limitintegerrequired
    • has_morebooleanrequired
    • next_cursorstringnullable

Search Filings Route

Live EDGAR full-text filing-document search with sec.gov citation URLs.

Parameters

NameTypeRequiredDefaultConstraintsDescription
querystringYes——Full-text phrase/keyword to search across EDGAR filing documents
formsarray<string> | nullNo——EDGAR form types to restrict to, e.g. 10-K; repeat for many
filed_fromstring (date) | nullNo——Earliest filing date to include, inclusive (YYYY-MM-DD)
filed_tostring (date) | nullNo——Latest filing date to include, inclusive (YYYY-MM-DD)
ticker_or_cikstring | nullNo——Optional exact ticker or numeric SEC CIK to restrict to one filer
limitintegerNo10min 1, max 50Document hits to return per page
cursorstring | nullNo——Opaque pagination cursor from a previous response's pagination.next_cursor; omit for the first relevance page.

Example request

Required parameters only, with values taken from the schema. Optional parameters are in the table above.

[ BASH ]
curl --fail --silent --show-error \
  --header "X-API-KEY: adk_..." \
  "https://api.agentdatasets.com/v1/stocks/filings/search?query=QUERY"

Response

200 Successful Response · expand a branch to see its fields.

  • dataFilingSearchDatarequiredThe envelope ``data``: search echoes, totals, and bounded document hits. Echoes let an agent confirm what EDGAR was searched for. ``cik`` is the applied entity filter (resolved from a ticker when one was given). ``total_hits`` caps at 10,000 because EDGAR's Elasticsearch window caps there; ``total_is_lower_bound`` is true when EDGAR reports a capped lower bound rather than an exact total.
    • querystringrequired
    • formsarray<string>requirednullable
    • filed_fromstring (date)requirednullable
    • filed_tostring (date)requirednullable
    • cikintegerrequirednullable
    • total_hitsintegerrequired
    • total_is_lower_boundbooleanrequired
    • hitsarray<FilingSearchHit>required
      • form_typestringrequired
      • filed_datestring (date)required
      • accession_numberstringrequired
      • file_typestringrequirednullable
      • file_descriptionstringrequirednullable
      • document_urlstringrequirednullable
      • index_urlstringrequired
      • companiesarray<FilingSearchCompany>required
        • cikintegerrequired
        • display_namestringrequirednullable
      • scorenumberrequired
  • metaMetarequiredResult-level provenance. ``source`` is a stable connector identifier (e.g. ``sec_edgar_companyfacts``); ``as_of`` is the freshest value-level ``as_of`` on the returned page, or ``None`` when the page is empty. Event-grained sources carry an aware datetime; date-grained sources (e.g. an SEC filing's report period) carry a plain date.
    • sourcestringrequired
    • as_ofstring (date-time) | string (date)nullable
  • paginationPaginationnullable
    • limitintegerrequired
    • has_morebooleanrequired
    • next_cursorstringnullable

GET/v1/stocks/financial-metrics

Financial Metrics

Public-key response

Price-derived valuation metrics (market cap, P/E, P/S, P/B, EV/EBITDA, FCF yield) are omitted for public keys; the response flags the omission via meta.restricted_omitted.

Derived financial metrics (margins/growth/returns/leverage) per period, plus a current-price valuation block. Numbers are served with their definitions; valuation values are non-redistributable (price-derived). Valuation multiples are omitted with currency_mismatch when the USD price would cross a non-USD statement input; fundamentals-only ratios are unaffected.

Parameters

NameTypeRequiredDefaultConstraintsDescription
tickerstringYes—min length 1Ticker symbol, e.g. AAPL or BRK.B
period"annual" | "quarterly" | "ttm"No"annual"—Fiscal frame for per-period metrics: annual (FY), quarterly, or ttm
limitintegerNo4min 1, max 12Fiscal periods to return, newest first
cursorstring | nullNo——Opaque pagination cursor from a previous response's pagination.next_cursor; omit to start from the newest.

Example request

Required parameters only, with values taken from the schema. Optional parameters are in the table above.

[ BASH ]
curl --fail --silent --show-error \
  --header "X-API-KEY: adk_..." \
  "https://api.agentdatasets.com/v1/stocks/financial-metrics?ticker=TICKER"

Response

200 Successful Response · expand a branch to see its fields.

  • dataFinancialMetricsDatarequiredThe envelope ``data``: identity, per-period metrics, current valuation. ``metrics`` is newest-first by ``period_end`` and bounded by ``limit`` + cursor paging. ``valuation`` is ``None`` when we hold no price for the company (the honest answer — valuation multiples need a price).
    • tickerstringrequired
    • cikintegerrequired
    • company_namestringrequired
    • period_type"annual" | "quarterly" | "ttm"required
    • metricsarray<PeriodMetrics>required
      • fiscal_yearintegerrequired
      • fiscal_period"FY" | "Q1" | "Q2" | "Q3" | "Q4"required
      • period_type"annual" | "quarterly" | "ttm"required
      • period_startstring (date)required
      • period_endstring (date)required
      • period_labelstringrequired
      • metricsmap<string, MetricValue>required
        • [key: string]MetricValueOne computed metric with its definition and the inputs it consumed. ``value`` is ``None`` when an input was missing or a guard tripped (e.g. a non-positive denominator); ``null_reason`` then says which, so the absence is explained rather than silent. ``formula_id`` keys the definition in docs/metrics.md; ``formula`` is a short inline restatement so an agent can cite it without a second lookup; ``inputs`` lists the exact line-and-period references used (``"revenue@FY2025"``), making every number re-derivable.
          • valuestringrequirednullablepattern ^(?!^[-+.]*$)[+-]?0*\d*\.?\d*$
          • unitstringrequired
          • formula_idstringrequired
          • formulastringrequired
          • inputsarray<string>required
          • sourcestringrequired
          • non_redistributablebooleanrequired
          • null_reasonstringnullable
    • valuationValuationrequirednullable
      • as_ofstring (date-time)required
      • pricestringrequiredpattern ^(?!^[-+.]*$)[+-]?0*\d*\.?\d*$
      • price_datestring (date)required
      • non_redistributablebooleanrequired
      • metricsmap<string, MetricValue>required
        • [key: string]MetricValueOne computed metric with its definition and the inputs it consumed. ``value`` is ``None`` when an input was missing or a guard tripped (e.g. a non-positive denominator); ``null_reason`` then says which, so the absence is explained rather than silent. ``formula_id`` keys the definition in docs/metrics.md; ``formula`` is a short inline restatement so an agent can cite it without a second lookup; ``inputs`` lists the exact line-and-period references used (``"revenue@FY2025"``), making every number re-derivable.
          • valuestringrequirednullablepattern ^(?!^[-+.]*$)[+-]?0*\d*\.?\d*$
          • unitstringrequired
          • formula_idstringrequired
          • formulastringrequired
          • inputsarray<string>required
          • sourcestringrequired
          • non_redistributablebooleanrequired
          • null_reasonstringnullable
  • metaMetricsMetarequiredResult-level provenance for the metrics surface. ``source`` is the primary (fundamental) connector; valuation values carry their own price ``source`` inline. ``non_redistributable`` is ``True`` when the payload includes a valuation block built from provider-licensed price data — a single flag a public surface can gate on before serving (docs/licensing-register.md), without inspecting every value.
    • sourcestringrequired
    • as_ofstring (date-time) | string (date)nullable
    • non_redistributablebooleandefault false
    • restricted_omittedarray<string>nullable
  • paginationPaginationnullable
    • limitintegerrequired
    • has_morebooleanrequired
    • next_cursorstringnullable

GET/v1/stocks/fund-holders

Fund Holders

Covered registered funds holding one company in their latest N-PORT filing.

Parameters

NameTypeRequiredDefaultConstraintsDescription
tickerstringYes—min length 1Ticker symbol (AAPL, BRK.B)
limitintegerNo25min 1, max 100Registered fund holders to return, highest portfolio weight first
cursorstring | nullNo——Opaque pagination cursor from a previous response's pagination.next_cursor; omit to start with the highest weight.

Example request

Required parameters only, with values taken from the schema. Optional parameters are in the table above.

[ BASH ]
curl --fail --silent --show-error \
  --header "X-API-KEY: adk_..." \
  "https://api.agentdatasets.com/v1/stocks/fund-holders?ticker=TICKER"

Response

200 Successful Response · expand a branch to see its fields.

  • dataStocksGetFundHoldersDatarequiredResolved stock identity and its bounded page of registered-fund holders.
    • tickerstringrequired
    • cikintegerrequired
    • company_namestringrequired
    • holdersarray<StockFundHolder>required
      • series_idstringrequired
      • series_namestringrequirednullable
      • registrant_namestringrequirednullable
      • cikintegerrequired
      • form_typestringrequired
      • accession_numberstringrequired
      • filed_datestring (date)required
      • report_periodstring (date)required
      • value_usdstringrequirednullablepattern ^(?!^[-+.]*$)[+-]?0*\d*\.?\d*$
      • pct_valuestringrequirednullablepattern ^(?!^[-+.]*$)[+-]?0*\d*\.?\d*$
      • holdings_countintegerrequired
  • metaStocksGetFundHoldersMetarequiredN-PORT attribution and coverage limits for the stock-to-fund join.
    • sourcestringrequired
    • as_ofstring (date-time) | string (date)nullable
    • attributionstringrequired
    • coveragestringrequired
    • covered_fundsintegerrequired
    • match_basisstringrequired
    • total_holdingsintegerrequired
    • unattributed_holdingsintegerrequired
  • paginationPaginationnullable
    • limitintegerrequired
    • has_morebooleanrequired
    • next_cursorstringnullable

GET/v1/stocks/income-statements

Income Statements

Normalized income statements for one company, newest period first.

ticker_or_cik takes a ticker symbol or a numeric SEC CIK; a CIK reaches a filer whose symbol was later reused by another listing, and data.ticker is then that company's active symbol or null.

data.reporting_standard is us-gaap, ifrs-full, or null when legacy rows have not observed the taxonomy yet. currency rides on every value as filed; IFRS filers report in their home currency and values are never silently converted to USD.

Parameters

NameTypeRequiredDefaultConstraintsDescription
ticker_or_cikstringYes—min length 1Ticker symbol (AAPL, BRK.B) or SEC CIK (320193)
period"annual" | "quarterly" | "ttm"No"annual"—Fiscal frame: annual (FY), quarterly (Q1-Q4), or ttm. Known IFRS 20-F/FPI filers are annual-only: quarterly returns out_of_coverage, while ttm returns an empty list.
limitintegerNo4min 1, max 12Fiscal periods to return, newest first
cursorstring | nullNo——Opaque pagination cursor from a previous response's pagination.next_cursor; omit to start from the newest.
as_reportedbooleanNofalse—Serve as-originally-reported values instead of latest restated values. Keep as_reported constant while paging. Before the next statement ingest, this mode raises out_of_coverage. In meta.restatements, reported lines carry original and superseding accessions; arithmetic-derived Q4, non-fiscal-year TTM, YTD-difference, and FCF lines carry null lineage, while a TTM matching a reported fiscal year carries the annual accessions.

Example request

Required parameters only, with values taken from the schema. Optional parameters are in the table above.

[ BASH ]
curl --fail --silent --show-error \
  --header "X-API-KEY: adk_..." \
  "https://api.agentdatasets.com/v1/stocks/income-statements?ticker_or_cik=TICKER_OR_CIK"

Response

200 Successful Response · expand a branch to see its fields.

  • dataIncomeStatementsDatarequiredIncome-statement ``data``: identity + the bounded, newest-first list.
    • tickerstringrequirednullable
    • cikintegerrequired
    • company_namestringrequired
    • period_type"annual" | "quarterly" | "ttm"required
    • reporting_standard"us-gaap" | "ifrs-full"requirednullable
    • statementsarray<IncomeStatement>required
      • fiscal_yearintegerrequired
      • fiscal_period"FY" | "Q1" | "Q2" | "Q3" | "Q4"required
      • period_type"annual" | "quarterly" | "ttm"required
      • period_startstring (date)required
      • period_endstring (date)required
      • linesmap<string, StatementValue>required
        • [key: string]StatementValueOne line's value with its own attribution. ``as_of`` is when we last saw this value (restatements refresh it in place, ADR 0001); ``accession_number`` is the EDGAR filing the value was taken from, so an agent can cite or fetch the source document.
          • valuestringrequiredpattern ^(?!^[-+.]*$)[+-]?0*\d*\.?\d*$
          • unitstringrequired
          • currencystringrequirednullable
          • as_ofstring (date-time)required
          • accession_numberstringrequirednullable
  • metaStatementsMetarequiredStatement provenance plus source-document view and restatement lineage.
    • sourcestringrequired
    • as_ofstring (date-time) | string (date)nullable
    • as_reportedbooleandefault false
    • restatementsarray<RestatedLine>nullable
      • fiscal_yearintegerrequired
      • fiscal_period"FY" | "Q1" | "Q2" | "Q3" | "Q4"required
      • period_type"annual" | "quarterly" | "ttm"required
      • line_keystringrequired
      • original_accession_numberstringrequirednullable
      • superseding_accession_numberstringrequirednullable
  • paginationPaginationnullable
    • limitintegerrequired
    • has_morebooleanrequired
    • next_cursorstringnullable

GET/v1/stocks/insider-trades

Insider Trades

Forms 3/4/5 insider transactions for one company, newest filing first.

Parameters

NameTypeRequiredDefaultConstraintsDescription
tickerstringYes—min length 1Ticker symbol (AAPL, BRK.B)
transaction_typestring | nullNo——Optional bucket filter: buy, sell, award, exercise, gift, or other
derivativeboolean | nullNo——Optional table filter: true = derivative rows only, false = Table I
insider_namestring | nullNo——Optional case-insensitive substring match on the reporting owner
filed_fromstring (date) | nullNo——Earliest filed date, inclusive (YYYY-MM-DD)
filed_tostring (date) | nullNo——Latest filed date, inclusive (YYYY-MM-DD)
include_supersededbooleanNofalse—Include superseded filings for audit history
limitintegerNo20min 1, max 100Transactions to return, newest filing first
cursorstring | nullNo——Opaque pagination cursor from a previous response's pagination.next_cursor; omit to start from the newest.

Example request

Required parameters only, with values taken from the schema. Optional parameters are in the table above.

[ BASH ]
curl --fail --silent --show-error \
  --header "X-API-KEY: adk_..." \
  "https://api.agentdatasets.com/v1/stocks/insider-trades?ticker=TICKER"

Response

200 Successful Response · expand a branch to see its fields.

  • dataInsiderTradesDatarequiredIssuer identity, filter echoes, the summary block, and the page.
    • tickerstringrequirednullable
    • cikintegerrequired
    • company_namestringrequired
    • coverage_startstring (date)required
    • transaction_typestringrequirednullable
    • derivativebooleanrequirednullable
    • insider_namestringrequirednullable
    • include_supersededbooleanrequired
    • summaryInsiderTradesSummaryrequiredNet activity over the whole filtered window, not just the page. ``net_nonderivative_shares`` is Σ shares signed by the acquired/disposed flag over non-derivative, non-holding rows that reported both — positive means insiders net-acquired. ``buy_transactions``/``sell_transactions`` count P and S rows respectively (derivative rows included: a P is a purchase either way). ``filed_from``/``filed_to`` echo the window the figures were computed over, null when the caller left that side open. Resolved amendment chains contribute only their latest filing by default. With ``include_superseded=True``, every historical filing contributes to these aggregates for audit and reconciliation work.
      • net_nonderivative_sharesstringrequiredpattern ^(?!^[-+.]*$)[+-]?0*\d*\.?\d*$
      • buy_transactionsintegerrequired
      • sell_transactionsintegerrequired
      • filed_fromstring (date)requirednullable
      • filed_tostring (date)requirednullable
    • transactionsarray<InsiderTransactionRow>required
      • accession_numberstringrequired
      • form_typestringrequired
      • filed_datestring (date)required
      • owner_namestringrequired
      • owner_cikintegerrequired
      • is_directorbooleanrequired
      • is_officerbooleanrequired
      • is_ten_percent_ownerbooleanrequired
      • officer_titlestringrequirednullable
      • is_derivativebooleanrequired
      • is_holdingbooleanrequired
      • transaction_datestring (date)requirednullable
      • transaction_codestringrequirednullable
      • transaction_typestringrequirednullable
      • security_titlestringrequired
      • sharesstringrequirednullablepattern ^(?!^[-+.]*$)[+-]?0*\d*\.?\d*$
      • price_per_sharestringrequirednullablepattern ^(?!^[-+.]*$)[+-]?0*\d*\.?\d*$
      • acquired_disposedstringrequirednullable
      • shares_owned_followingstringrequirednullablepattern ^(?!^[-+.]*$)[+-]?0*\d*\.?\d*$
      • direct_or_indirectstringrequirednullable
      • indirect_naturestringrequirednullable
  • metaMetarequiredResult-level provenance. ``source`` is a stable connector identifier (e.g. ``sec_edgar_companyfacts``); ``as_of`` is the freshest value-level ``as_of`` on the returned page, or ``None`` when the page is empty. Event-grained sources carry an aware datetime; date-grained sources (e.g. an SEC filing's report period) carry a plain date.
    • sourcestringrequired
    • as_ofstring (date-time) | string (date)nullable
  • paginationPaginationnullable
    • limitintegerrequired
    • has_morebooleanrequired
    • next_cursorstringnullable

GET/v1/stocks/ipo-profile

Ipo Profile

One CIK's chronological registration-event timeline.

Parameters

NameTypeRequiredDefaultConstraintsDescription
cikintegerYes—min 1Positive SEC Central Index Key (CIK)

Example request

Required parameters only, with values taken from the schema. Optional parameters are in the table above.

[ BASH ]
curl --fail --silent --show-error \
  --header "X-API-KEY: adk_..." \
  "https://api.agentdatasets.com/v1/stocks/ipo-profile?cik=1"

Response

200 Successful Response · expand a branch to see its fields.

  • dataIpoProfileDatarequiredOne CIK's registration timeline and any anchored lifecycle fields.
    • cikintegerrequired
    • company_namestringrequired
    • sicstringrequirednullable
    • sic_descriptionstringrequirednullable
    • stagestringrequirednullable
    • first_filed_datestring (date)requirednullable
    • effective_datestring (date)requirednullable
    • priced_datestring (date)requirednullable
    • withdrawn_datestring (date)requirednullable
    • latest_event_datestring (date)requirednullable
    • event_countintegerrequired
    • eventsarray<IpoRegistrationEvent>required
      • filed_datestring (date)required
      • form_typestringrequired
      • accession_numberstringrequired
      • filing_index_urlstringrequired
  • metaMetarequiredResult-level provenance. ``source`` is a stable connector identifier (e.g. ``sec_edgar_companyfacts``); ``as_of`` is the freshest value-level ``as_of`` on the returned page, or ``None`` when the page is empty. Event-grained sources carry an aware datetime; date-grained sources (e.g. an SEC filing's report period) carry a plain date.
    • sourcestringrequired
    • as_ofstring (date-time) | string (date)nullable
  • paginationPaginationnullable
    • limitintegerrequired
    • has_morebooleanrequired
    • next_cursorstringnullable

GET/v1/stocks/ipos

Ipos

Search initial-registration lifecycles, newest first.

Parameters

NameTypeRequiredDefaultConstraintsDescription
stagestring | nullNo——Lifecycle stage: in_registration, effective, priced, or withdrawn
filed_fromstring (date) | nullNo——Earliest first-filed date, inclusive (YYYY-MM-DD)
filed_tostring (date) | nullNo——Latest first-filed date, inclusive (YYYY-MM-DD)
sicstring | nullNo——Exact raw SEC SIC code string
limitintegerNo20min 1, max 100IPO registrations to return, newest first
cursorstring | nullNo——Opaque pagination cursor from a previous response's pagination.next_cursor; keep all filters constant while paging

Example request

Required parameters only, with values taken from the schema. Optional parameters are in the table above.

[ BASH ]
curl --fail --silent --show-error \
  --header "X-API-KEY: adk_..." \
  "https://api.agentdatasets.com/v1/stocks/ipos"

Response

200 Successful Response · expand a branch to see its fields.

  • dataIpoSearchDatarequiredEchoed search filters and the matching IPO registration lifecycles.
    • stagestringrequirednullable
    • filed_fromstring (date)requirednullable
    • filed_tostring (date)requirednullable
    • sicstringrequirednullable
    • iposarray<IpoRegistrationSummary>required
      • cikintegerrequired
      • company_namestringrequired
      • sicstringrequirednullable
      • sic_descriptionstringrequirednullable
      • stagestringrequired
      • first_filed_datestring (date)required
      • effective_datestring (date)requirednullable
      • priced_datestring (date)requirednullable
      • withdrawn_datestring (date)requirednullable
      • latest_event_datestring (date)required
      • event_countintegerrequired
  • metaMetarequiredResult-level provenance. ``source`` is a stable connector identifier (e.g. ``sec_edgar_companyfacts``); ``as_of`` is the freshest value-level ``as_of`` on the returned page, or ``None`` when the page is empty. Event-grained sources carry an aware datetime; date-grained sources (e.g. an SEC filing's report period) carry a plain date.
    • sourcestringrequired
    • as_ofstring (date-time) | string (date)nullable
  • paginationPaginationnullable
    • limitintegerrequired
    • has_morebooleanrequired
    • next_cursorstringnullable

Line Items Search

Selected canonical statement lines across several companies.

Parameters

NameTypeRequiredDefaultConstraintsDescription
tickersarray<string>Yes—min items 1, max items 20Repeated exact ticker symbols to compare
line_itemsarray<string>Yes—min items 1, max items 20Repeated exact canonical statement line keys
period"annual" | "quarterly" | "ttm"No"annual"—Fiscal frame: annual (FY), quarterly (Q1–Q4), or ttm
limitintegerNo4min 1, max 12Newest fiscal periods retained independently per ticker and line item
cursorstring | nullNo——Opaque pagination cursor from a previous response's pagination.next_cursor; omit to start from the newest.

Example request

Required parameters only, with values taken from the schema. Optional parameters are in the table above.

[ BASH ]
curl --fail --silent --show-error \
  --header "X-API-KEY: adk_..." \
  "https://api.agentdatasets.com/v1/stocks/line-items/search?tickers=TICKERS&line_items=LINE_ITEMS"

Response

200 Successful Response · expand a branch to see its fields.

  • dataLineItemsSearchDatarequiredResolved identities, selected lines, page rows, and partial failures.
    • companiesarray<LineItemCompany>required
      • tickerstringrequired
      • cikintegerrequired
      • company_namestringrequired
    • period_type"annual" | "quarterly" | "ttm"required
    • line_itemsarray<string>required
    • resultsarray<LineItemStatement>required
      • tickerstringrequired
      • fiscal_yearintegerrequired
      • fiscal_period"FY" | "Q1" | "Q2" | "Q3" | "Q4"required
      • period_type"annual" | "quarterly" | "ttm"required
      • period_startstring (date)required
      • period_endstring (date)required
      • linesmap<string, StatementValue>required
        • [key: string]StatementValueOne line's value with its own attribution. ``as_of`` is when we last saw this value (restatements refresh it in place, ADR 0001); ``accession_number`` is the EDGAR filing the value was taken from, so an agent can cite or fetch the source document.
          • valuestringrequiredpattern ^(?!^[-+.]*$)[+-]?0*\d*\.?\d*$
          • unitstringrequired
          • currencystringrequirednullable
          • as_ofstring (date-time)required
          • accession_numberstringrequirednullable
    • unresolved_tickersarray<agent_datasets__stocks__line_items__UnresolvedTicker>required
      • tickerstringrequired
      • codestringrequired
      • messagestringrequired
      • suggestionsarray<string>nullable
    • unknown_line_itemsarray<string>required
  • metaMetarequiredResult-level provenance. ``source`` is a stable connector identifier (e.g. ``sec_edgar_companyfacts``); ``as_of`` is the freshest value-level ``as_of`` on the returned page, or ``None`` when the page is empty. Event-grained sources carry an aware datetime; date-grained sources (e.g. an SEC filing's report period) carry a plain date.
    • sourcestringrequired
    • as_ofstring (date-time) | string (date)nullable
  • paginationPaginationnullable
    • limitintegerrequired
    • has_morebooleanrequired
    • next_cursorstringnullable

GET/v1/stocks/ownership-filings

Ownership Filings

Schedule 13D/13G ownership-filing events, newest first.

Parameters

NameTypeRequiredDefaultConstraintsDescription
tickerstring | nullNo——Optional subject-company filter by ticker symbol
filer_namestring | nullNo——Optional case-insensitive substring match on a reporting person
schedule_typestring | nullNo——Optional schedule filter: 13D or 13G
filed_fromstring (date) | nullNo——Earliest filed date, inclusive (YYYY-MM-DD)
filed_tostring (date) | nullNo——Latest filed date, inclusive (YYYY-MM-DD)
limitintegerNo20min 1, max 100Filings to return, newest first
cursorstring | nullNo——Opaque pagination cursor from a previous response's pagination.next_cursor; omit to start from the newest.

Example request

Required parameters only, with values taken from the schema. Optional parameters are in the table above.

[ BASH ]
curl --fail --silent --show-error \
  --header "X-API-KEY: adk_..." \
  "https://api.agentdatasets.com/v1/stocks/ownership-filings"

Response

200 Successful Response · expand a branch to see its fields.

  • dataOwnershipFilingSearchDatarequiredFilter echoes plus the bounded newest-first filing page.
    • tickerstringrequirednullable
    • filer_namestringrequirednullable
    • schedule_typestringrequirednullable
    • filed_fromstring (date)requirednullable
    • filed_tostring (date)requirednullable
    • coverage_startstring (date)required
    • filingsarray<OwnershipFilingEvent>required
      • accession_numberstringrequired
      • schedule_typestringrequired
      • submission_typestringrequired
      • amendment_numberintegerrequirednullable
      • subject_namestringrequired
      • subject_cikintegerrequired
      • cusipstringrequirednullable
      • date_of_eventstring (date)requirednullable
      • filed_datestring (date)required
      • reporting_personsarray<OwnershipFilingPerson>required
        • namestringrequired
        • cikintegerrequirednullable
        • person_typestringrequirednullable
        • percent_of_classstringrequirednullablepattern ^(?!^[-+.]*$)[+-]?0*\d*\.?\d*$
        • shares_beneficially_ownedstringrequirednullablepattern ^(?!^[-+.]*$)[+-]?0*\d*\.?\d*$
  • metaMetarequiredResult-level provenance. ``source`` is a stable connector identifier (e.g. ``sec_edgar_companyfacts``); ``as_of`` is the freshest value-level ``as_of`` on the returned page, or ``None`` when the page is empty. Event-grained sources carry an aware datetime; date-grained sources (e.g. an SEC filing's report period) carry a plain date.
    • sourcestringrequired
    • as_ofstring (date-time) | string (date)nullable
  • paginationPaginationnullable
    • limitintegerrequired
    • has_morebooleanrequired
    • next_cursorstringnullable

GET/v1/stocks/peers

Peers

Public-key response

SEC-derived fundamental and statement metrics are available to public keys. Peer comparisons that request price-derived market cap, P/E, P/S, P/B, EV/EBITDA, or FCF yield are refused; those metrics require an internal key.

Comparable companies for one company, with the same metrics side by side.

Peers share the subject's classification in our own SIC-derived taxonomy — the SIC major group inside its sector when it has a SIC code, else the sector — and are ordered by nearest trailing-annual revenue. An unclassified subject returns an empty peer list with a reason, not an error.

Parameters

NameTypeRequiredDefaultConstraintsDescription
ticker_or_cikstringYes—min length 1Ticker symbol (AAPL, BRK.B) or CIK (320193, 0000320193)
limitintegerNo10min 1, max 20Peers to return, nearest in trailing-annual revenue first
metricsarray<string> | nullNo—max items 10Repeated snapshot metric names, e.g. ?metrics=revenue&metrics=roe; omit for the default fundamentals set. `revenue` is always served (the ranking is measured on it), so at most 10 metrics ride on a row: 10 including `revenue`, or 9 that are not

Example request

Required parameters only, with values taken from the schema. Optional parameters are in the table above.

[ BASH ]
curl --fail --silent --show-error \
  --header "X-API-KEY: adk_..." \
  "https://api.agentdatasets.com/v1/stocks/peers?ticker_or_cik=TICKER_OR_CIK"

Response

200 Successful Response · expand a branch to see its fields.

  • dataStocksPeersDatarequiredThe subject's identity echo, the basis used, and the comparison rows.
    • tickerstringrequirednullable
    • cikintegerrequired
    • company_namestringrequired
    • basis"sic-major-group" | "sector"requirednullable
    • sectorstringrequirednullable
    • sic_major_groupstringrequirednullable
    • size_metricstringrequired
    • metricsarray<string>required
    • peer_universe_sizeintegerrequired
    • subjectPeerCompanyrequiredOne company in a peer comparison — the subject or one of its peers. Identity and classification ride on every row so the comparison is self-describing, and ``metrics`` carries the requested snapshot values with their own unit, currency, fiscal frame, ``as_of``, and source. A metric the company has no snapshot row for is simply absent from the list (absence is a missing entry, never a zero).
      • tickerstringrequirednullable
      • cikintegerrequired
      • company_namestringrequired
      • exchangestringrequirednullable
      • sectorstringrequirednullable
      • sic_codestringrequirednullable
      • metricsarray<ScreenMetricValue>required
        • metricstringrequired
        • valuestringrequiredpattern ^(?!^[-+.]*$)[+-]?0*\d*\.?\d*$
        • unitstringrequired
        • currencystringrequirednullable
        • fiscal_yearintegerrequirednullable
        • fiscal_period"FY" | "Q1" | "Q2" | "Q3" | "Q4"requirednullable
        • period_type"annual" | "quarterly" | "ttm"requirednullable
        • period_startstring (date)requirednullable
        • period_endstring (date)requirednullable
        • as_ofstring (date-time)required
        • sourcestringrequired
    • peersarray<PeerCompany>required
      • tickerstringrequirednullable
      • cikintegerrequired
      • company_namestringrequired
      • exchangestringrequirednullable
      • sectorstringrequirednullable
      • sic_codestringrequirednullable
      • metricsarray<ScreenMetricValue>required
        • metricstringrequired
        • valuestringrequiredpattern ^(?!^[-+.]*$)[+-]?0*\d*\.?\d*$
        • unitstringrequired
        • currencystringrequirednullable
        • fiscal_yearintegerrequirednullable
        • fiscal_period"FY" | "Q1" | "Q2" | "Q3" | "Q4"requirednullable
        • period_type"annual" | "quarterly" | "ttm"requirednullable
        • period_startstring (date)requirednullable
        • period_endstring (date)requirednullable
        • as_ofstring (date-time)required
        • sourcestringrequired
    • reasonstringrequirednullable
  • metaStocksPeersMetarequired
    • sourcestringrequired
    • as_ofstring (date-time) | string (date)nullable
  • paginationPaginationnullable
    • limitintegerrequired
    • has_morebooleanrequired
    • next_cursorstringnullable

GET/v1/stocks/proxy-voting-summary

Proxy Voting Summary

Covered N-PX manager votes for one company's shareholder meetings.

Parameters

NameTypeRequiredDefaultConstraintsDescription
tickerstringYes—min length 1US public company ticker symbol, e.g. STZ
limitintegerNo2min 1, max 5Shareholder meetings to return, newest first
cursorstring | nullNo——Opaque pagination.next_cursor from the previous page

Example request

Required parameters only, with values taken from the schema. Optional parameters are in the table above.

[ BASH ]
curl --fail --silent --show-error \
  --header "X-API-KEY: adk_..." \
  "https://api.agentdatasets.com/v1/stocks/proxy-voting-summary?ticker=TICKER"

Response

200 Successful Response · expand a branch to see its fields.

  • dataProxyVotingSummaryDatarequiredCanonical company identity and its bounded proxy-voting meeting page.
    • tickerstringrequired
    • company_namestringrequired
    • meetingsarray<ProxyVotingMeeting>required
      • meeting_datestring (date)requirednullable
      • managers_coveredintegerrequired
      • proposalsarray<ProxyVotingProposal>required
        • descriptionstringrequired
        • categoriesarray<string>required
        • talliesarray<ProxyVoteTally>required
          • how_votedstringrequired
          • managersintegerrequired
          • shares_votedstringnullablepattern ^(?!^[-+.]*$)[+-]?0*\d*\.?\d*$
          • shares_voted_incompletebooleannullable
        • managersarray<ProxyVotingManager>required
          • cikintegerrequired
          • namestringrequired
          • how_votedstringrequired
          • shares_votedstringnullablepattern ^(?!^[-+.]*$)[+-]?0*\d*\.?\d*$
          • shares_voted_incompletebooleannullable
          • management_recommendationstringnullable
          • accession_numberstringrequired
        • managers_truncatedbooleannullable
      • proposals_truncatedbooleannullable
  • metaProxyVotingSummaryMetarequiredEDGAR provenance plus the explicit N-PX manager coverage basis.
    • sourcestringrequired
    • as_ofstring (date-time) | string (date)nullable
    • coveragestringrequired
  • paginationPaginationnullable
    • limitintegerrequired
    • has_morebooleanrequired
    • next_cursorstringnullable

GET/v1/stocks/recent-filings

Recent Filings

SEC EDGAR filings metadata + sec.gov links across companies, newest first.

Parameters

NameTypeRequiredDefaultConstraintsDescription
filed_afterstring (date) | nullNo——Earliest filing date to include, inclusive (YYYY-MM-DD)
form_typesarray<string> | nullNo—max items 10Repeated EDGAR form filters, e.g. 10-K, 8-K
tickersarray<string> | nullNo—max items 20Repeated ticker filters, e.g. AAPL, MSFT
limitintegerNo100min 1, max 1000Filings to return, newest first
cursorstring | nullNo——Opaque pagination cursor from a previous response's pagination.next_cursor; omit to start from the newest.

Example request

Required parameters only, with values taken from the schema. Optional parameters are in the table above.

[ BASH ]
curl --fail --silent --show-error \
  --header "X-API-KEY: adk_..." \
  "https://api.agentdatasets.com/v1/stocks/recent-filings"

Response

200 Successful Response · expand a branch to see its fields.

  • dataRecentFilingsDatarequiredThe envelope ``data`` for the universe-wide filed-since feed. Filter echoes are the canonicalized values that were applied. ``None`` means that filter was omitted. ``filings`` is newest-first by ``(filed_date, accession_number)`` across all matching companies.
    • filed_afterstring (date)requirednullable
    • form_typesarray<string>requirednullable
    • tickersarray<string>requirednullable
    • filingsarray<RecentFilingSummary>required
      • form_typestringrequired
      • filed_datestring (date)required
      • period_of_reportstring (date)requirednullable
      • accession_numberstringrequired
      • primary_document_urlstringrequirednullable
      • index_urlstringrequired
      • as_ofstring (date-time)required
      • tickerstringrequirednullable
      • cikintegerrequired
      • company_namestringrequired
  • metaMetarequiredResult-level provenance. ``source`` is a stable connector identifier (e.g. ``sec_edgar_companyfacts``); ``as_of`` is the freshest value-level ``as_of`` on the returned page, or ``None`` when the page is empty. Event-grained sources carry an aware datetime; date-grained sources (e.g. an SEC filing's report period) carry a plain date.
    • sourcestringrequired
    • as_ofstring (date-time) | string (date)nullable
  • paginationPaginationnullable
    • limitintegerrequired
    • has_morebooleanrequired
    • next_cursorstringnullable

GET/v1/stocks/screen

Screen

Public-key response

SEC-derived fundamental and statement metrics are available to public keys. Screens that filter or sort by price-derived market cap, P/E, P/S, P/B, EV/EBITDA, or FCF yield are refused; those metrics require an internal key.

Screen the latest company metrics cross-section.

Because this is a GET endpoint, filters and optional sort are JSON-encoded query-parameter strings. Example: filters=[{"metric":"net_margin", "op":"gte","value":"0.2"}]&sort={"metric":"roe","direction":"desc"}. Monetary line items filter and rank in each company's reporting currency (each value carries currency); ratio and growth metrics are the cross-currency-comparable choice. Malformed JSON or invalid typed-filter shapes return bad_parameter (422).

Parameters

NameTypeRequiredDefaultConstraintsDescription
filtersstringYes——JSON-encoded list of typed filters, for example [{"metric":"net_margin","op":"gte","value":"0.2"}]
sortstring | nullNo——Optional JSON-encoded sort object, for example {"metric":"roe","direction":"desc"}
limitintegerNo20min 1, max 100Companies to return per page
cursorstring | nullNo——Opaque pagination.next_cursor from the previous page

Example request

Required parameters only, with values taken from the schema. Optional parameters are in the table above.

[ BASH ]
curl --fail --silent --show-error \
  --header "X-API-KEY: adk_..." \
  "https://api.agentdatasets.com/v1/stocks/screen?filters=FILTERS"

Response

200 Successful Response · expand a branch to see its fields.

  • dataStocksScreenDatarequired
    • filtersarray<ScreenFilter>required
      • metricstringrequired
      • op"gt" | "gte" | "lt" | "lte" | "eq" | "between" | "in"required
      • valuestring | array<string>required
    • sortScreenSortrequiredThe numeric snapshot metric and direction that define the total order.
      • metricstringrequired
      • direction"asc" | "desc"default "desc"
    • companiesarray<ScreenCompanyRow>required
      • tickerstringrequirednullable
      • cikintegerrequired
      • company_namestringrequired
      • exchangestringrequirednullable
      • sectorstringrequirednullable
      • sic_codestringrequirednullable
      • metricsarray<ScreenMetricValue>required
        • metricstringrequired
        • valuestringrequiredpattern ^(?!^[-+.]*$)[+-]?0*\d*\.?\d*$
        • unitstringrequired
        • currencystringrequirednullable
        • fiscal_yearintegerrequirednullable
        • fiscal_period"FY" | "Q1" | "Q2" | "Q3" | "Q4"requirednullable
        • period_type"annual" | "quarterly" | "ttm"requirednullable
        • period_startstring (date)requirednullable
        • period_endstring (date)requirednullable
        • as_ofstring (date-time)required
        • sourcestringrequired
  • metaStocksScreenMetarequired
    • sourcestringrequired
    • as_ofstring (date-time) | string (date)nullable
  • paginationPaginationnullable
    • limitintegerrequired
    • has_morebooleanrequired
    • next_cursorstringnullable

Search

Ranked entity matches for a name/ticker/fragment query, best first.

Parameters

NameTypeRequiredDefaultConstraintsDescription
querystringYes——Company name, ticker, or fragment to search
limitintegerNo10min 1, max 50Max ranked matches to return

Example request

Required parameters only, with values taken from the schema. Optional parameters are in the table above.

[ BASH ]
curl --fail --silent --show-error \
  --header "X-API-KEY: adk_..." \
  "https://api.agentdatasets.com/v1/stocks/search?query=QUERY"

Response

200 Successful Response · expand a branch to see its fields.

  • dataTickerSearchDatarequiredThe envelope ``data`` for entity search: the echoed query plus the ranked ``matches``. ``query`` is echoed verbatim so an agent can confirm what was searched; each match carries its own ``score``/``match_reason`` and ``source``/``as_of`` attribution (see :class:`EntityMatch`).
    • querystringrequired
    • matchesarray<EntityMatch>required
      • cikintegerrequired
      • namestringrequired
      • symbolstringrequirednullable
      • exchangestringrequirednullable
      • symbol_activebooleanrequired
      • scorenumberrequired
      • match_reason"ticker_exact" | "ticker_prefix" | "name_exact" | "name_fuzzy"required
      • sourcestringrequired
      • as_ofstring (date-time)required
  • metaMetarequiredResult-level provenance. ``source`` is a stable connector identifier (e.g. ``sec_edgar_companyfacts``); ``as_of`` is the freshest value-level ``as_of`` on the returned page, or ``None`` when the page is empty. Event-grained sources carry an aware datetime; date-grained sources (e.g. an SEC filing's report period) carry a plain date.
    • sourcestringrequired
    • as_ofstring (date-time) | string (date)nullable
  • paginationPaginationnullable
    • limitintegerrequired
    • has_morebooleanrequired
    • next_cursorstringnullable

GET/v1/stocks/segmented-financials

Segmented Financials

Revenue or operating income by segment for one company, newest year first.

Parameters

NameTypeRequiredDefaultConstraintsDescription
tickerstringYes—min length 1Ticker symbol, e.g. AAPL or BRK.B
axis"business_segments" | "products_services" | "geography"Yes——Disaggregation axis: business_segments, products_services, geography
metric"revenue" | "operating_income"No"revenue"—revenue (all axes) or operating_income (business_segments axis only)
include_non_operatingbooleanNofalse—Include elimination and corporate/other members
limitintegerNo4min 1, max 12Fiscal years to return, newest first
cursorstring | nullNo——Opaque pagination.next_cursor from the previous page

Example request

Required parameters only, with values taken from the schema. Optional parameters are in the table above.

[ BASH ]
curl --fail --silent --show-error \
  --header "X-API-KEY: adk_..." \
  "https://api.agentdatasets.com/v1/stocks/segmented-financials?ticker=TICKER&axis=AXIS"

Response

200 Successful Response · expand a branch to see its fields.

  • dataSegmentedFinancialsDatarequiredThe envelope ``data``: identity + request echo + the bounded frame list. ``ticker`` echoes the canonical (SEC) form of the requested symbol, which may differ from the raw query ("brk.b" → "BRK-B"); ``axis`` and ``metric`` echo the series served, because the member vocabulary an agent reads back is meaningless without knowing which disaggregation produced it.
    • tickerstringrequired
    • cikintegerrequired
    • company_namestringrequired
    • axis"business_segments" | "products_services" | "geography"requiredThe XBRL dimension a segment series is disaggregated on.
    • metric"revenue" | "operating_income"requiredThe canonical measures served per segment member.
    • framesarray<SegmentFrame>required
      • fiscal_yearintegerrequired
      • fiscal_period"FY" | "Q1" | "Q2" | "Q3" | "Q4"required
      • period_type"annual" | "quarterly" | "ttm"required
      • period_startstring (date)required
      • period_endstring (date)required
      • currencystringrequirednullable
      • unitstringrequired
      • segmentsarray<SegmentValue>required
        • memberstringrequired
        • member_labelstringrequired
        • member_role"operating" | "elimination" | "corporate_other"requiredHow a member participates in the tie back to the consolidated total.
        • valuestringrequiredpattern ^(?!^[-+.]*$)[+-]?0*\d*\.?\d*$
        • share_of_totalstringrequirednullablepattern ^(?!^[-+.]*$)[+-]?0*\d*\.?\d*$
        • accession_numberstringrequired
        • as_ofstring (date-time)required
      • consolidated_totalConsolidatedTotalrequirednullable
        • valuestringrequiredpattern ^(?!^[-+.]*$)[+-]?0*\d*\.?\d*$
        • accession_numberstringrequired
        • as_ofstring (date-time)required
  • metaSegmentsMetarequiredSegment provenance: the connector ``source`` and the freshest ``as_of`` served on this page (null on an empty page). Named rather than reusing the base ``Meta`` so the tool's output schema has a stable name of its own, and so the constant attribution segments may later carry (as-reported vintages, per plan 005 §2) lands without renaming the model agents already read.
    • sourcestringrequired
    • as_ofstring (date-time) | string (date)nullable
  • paginationPaginationnullable
    • limitintegerrequired
    • has_morebooleanrequired
    • next_cursorstringnullable