# Stocks REST endpoints US public equity markets — fundamentals, filings, prices, and corporate actions sourced from SEC EDGAR and market data providers. 28 endpoints. Paths are relative to `https://api.agentdatasets.com`. Every endpoint mirrors an MCP tool over the same service layer — https://www.agentdatasets.com/docs/tools.md 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 | Parameter | In | Type | Required | Default | Constraints | Description | | --- | --- | --- | --- | --- | --- | --- | | ticker_or_cik | query | `string` | yes | — | min length 1 | Ticker symbol (AAPL, BRK.B) or SEC CIK (320193) | | period | query | `"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. | | limit | query | `integer` | no | 4 | min 1, max 12 | Fiscal periods to return, newest first | | cursor | query | `string \| null` | no | — | — | Opaque pagination cursor from a previous response's pagination.next_cursor; omit to start from the newest. | | as_reported | query | `boolean` | no | false | — | 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. ```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 — `BalanceSheetsResult`. - `data` `BalanceSheetsData` (required) — Balance-sheet ``data``: identity + the bounded, newest-first list. - `ticker` `string | null` (required) - `cik` `integer` (required) - `company_name` `string` (required) - `period_type` `"annual" | "quarterly" | "ttm"` (required) - `reporting_standard` `"us-gaap" | "ifrs-full" | null` (required) - `statements` `array` (required) - `fiscal_year` `integer` (required) - `fiscal_period` `"FY" | "Q1" | "Q2" | "Q3" | "Q4"` (required) - `period_type` `"annual" | "quarterly" | "ttm"` (required) - `period_start` `string (date)` (required) - `period_end` `string (date)` (required) - `lines` `map` (required) - `[key: string]` `StatementValue` — One 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. - `meta` `StatementsMeta` (required) — Statement provenance plus source-document view and restatement lineage. - `source` `string` (required) - `as_of` `string (date-time) | string (date) | null` - `as_reported` `boolean` - `restatements` `array | null` - `fiscal_year` `integer` (required) - `fiscal_period` `"FY" | "Q1" | "Q2" | "Q3" | "Q4"` (required) - `period_type` `"annual" | "quarterly" | "ttm"` (required) - `line_key` `string` (required) - `original_accession_number` `string | null` (required) - `superseding_accession_number` `string | null` (required) - `pagination` `Pagination | null` - `limit` `integer` (required) - `has_more` `boolean` (required) - `next_cursor` `string | null` Fields are shown to 3 levels; the full schema is in https://www.agentdatasets.com/docs/machine/openapi.json ## GET /v1/stocks/beneficial-owners Beneficial Owners Current >5% beneficial owners of one company, latest event per person. ### Parameters | Parameter | In | Type | Required | Default | Constraints | Description | | --- | --- | --- | --- | --- | --- | --- | | ticker | query | `string` | yes | — | min length 1 | Ticker symbol (AAPL, BRK.B) | | limit | query | `integer` | no | 20 | min 1, max 100 | Owners to return, newest first | | cursor | query | `string \| null` | no | — | — | 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. ```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 — `BeneficialOwnersResult`. - `data` `BeneficialOwnersData` (required) - `ticker` `string | null` (required) - `cik` `integer` (required) - `company_name` `string` (required) - `coverage_start` `string (date)` (required) - `owners` `array` (required) - `name` `string` (required) - `cik` `integer | null` (required) - `person_type` `string | null` (required) - `percent_of_class` `string | null` (required) - `shares_beneficially_owned` `string | null` (required) - `schedule_type` `string` (required) - `submission_type` `string` (required) - `amendment_number` `integer | null` (required) - `date_of_event` `string (date) | null` (required) - `filed_date` `string (date)` (required) - `accession_number` `string` (required) - `meta` `Meta` (required) — Result-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. - `source` `string` (required) - `as_of` `string (date-time) | string (date) | null` - `pagination` `Pagination | null` - `limit` `integer` (required) - `has_more` `boolean` (required) - `next_cursor` `string | null` Fields are shown to 3 levels; the full schema is in https://www.agentdatasets.com/docs/machine/openapi.json ## 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 | Parameter | In | Type | Required | Default | Constraints | Description | | --- | --- | --- | --- | --- | --- | --- | | ticker_or_cik | query | `string` | yes | — | min length 1 | Ticker symbol (AAPL, BRK.B) or SEC CIK (320193) | | period | query | `"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. | | limit | query | `integer` | no | 4 | min 1, max 12 | Fiscal periods to return, newest first | | cursor | query | `string \| null` | no | — | — | Opaque pagination cursor from a previous response's pagination.next_cursor; omit to start from the newest. | | as_reported | query | `boolean` | no | false | — | 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. ```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 — `CashFlowStatementsResult`. - `data` `CashFlowStatementsData` (required) — Cash-flow ``data``: identity + the bounded, newest-first list. - `ticker` `string | null` (required) - `cik` `integer` (required) - `company_name` `string` (required) - `period_type` `"annual" | "quarterly" | "ttm"` (required) - `reporting_standard` `"us-gaap" | "ifrs-full" | null` (required) - `statements` `array` (required) - `fiscal_year` `integer` (required) - `fiscal_period` `"FY" | "Q1" | "Q2" | "Q3" | "Q4"` (required) - `period_type` `"annual" | "quarterly" | "ttm"` (required) - `period_start` `string (date)` (required) - `period_end` `string (date)` (required) - `lines` `map` (required) - `[key: string]` `StatementValue` — One 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. - `meta` `StatementsMeta` (required) — Statement provenance plus source-document view and restatement lineage. - `source` `string` (required) - `as_of` `string (date-time) | string (date) | null` - `as_reported` `boolean` - `restatements` `array | null` - `fiscal_year` `integer` (required) - `fiscal_period` `"FY" | "Q1" | "Q2" | "Q3" | "Q4"` (required) - `period_type` `"annual" | "quarterly" | "ttm"` (required) - `line_key` `string` (required) - `original_accession_number` `string | null` (required) - `superseding_accession_number` `string | null` (required) - `pagination` `Pagination | null` - `limit` `integer` (required) - `has_more` `boolean` (required) - `next_cursor` `string | null` Fields are shown to 3 levels; the full schema is in https://www.agentdatasets.com/docs/machine/openapi.json ## 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 | Parameter | In | Type | Required | Default | Constraints | Description | | --- | --- | --- | --- | --- | --- | --- | | ticker_or_cik | query | `string` | yes | — | — | Exact ticker (AAPL, BRK.B) or numeric CIK | ### Example request Required parameters only, with values taken from the schema. ```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 — `CompanyFactsResult`. - `data` `CompanyFactsData` (required) — The 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. - `cik` `integer` (required) - `name` `string` (required) - `tickers` `array` (required) - `symbol` `string` (required) - `exchange` `string | null` (required) - `active` `boolean` (required) - `valid_from` `string (date)` (required) - `valid_to` `string (date) | null` (required) - `exchange` `string | null` (required) - `sector` `string | null` (required) - `sic_code` `string | null` (required) - `sic_description` `string | null` (required) - `fiscal_year_end` `string | null` (required) - `latest_filing_date` `string (date) | null` (required) - `coverage` `Coverage` (required) — Per-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. - `financials` `CoverageEntry` (required) — Whether 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]``. - `available` `boolean` (required) - `since` `string (date) | null` - `through` `string (date) | null` - `prices` `CoverageEntry` (required) — Whether 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]``. - `available` `boolean` (required) - `since` `string (date) | null` - `through` `string (date) | null` - `filings` `CoverageEntry` (required) — Whether 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]``. - `available` `boolean` (required) - `since` `string (date) | null` - `through` `string (date) | null` - `meta` `CompanyMeta` (required) — Company-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). - `source` `string` (required) - `as_of` `string (date-time) | string (date) | null` - `restricted_omitted` `array | null` - `pagination` `Pagination | null` - `limit` `integer` (required) - `has_more` `boolean` (required) - `next_cursor` `string | null` Fields are shown to 3 levels; the full schema is in https://www.agentdatasets.com/docs/machine/openapi.json ## GET /v1/stocks/company-events Company Events Typed 8-K material events for one company, newest first. ### Parameters | Parameter | In | Type | Required | Default | Constraints | Description | | --- | --- | --- | --- | --- | --- | --- | | ticker_or_cik | query | `string` | yes | — | min length 1 | Ticker symbol (AAPL) or SEC CIK (320193) | | category | query | `string \| null` | no | — | — | 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 | | start | query | `string (date) \| null` | no | — | — | Earliest event date, inclusive (YYYY-MM-DD) | | end | query | `string (date) \| null` | no | — | — | Latest event date, inclusive (YYYY-MM-DD) | | limit | query | `integer` | no | 20 | min 1, max 100 | Events to return, newest first | | cursor | query | `string \| null` | no | — | — | 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. ```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 — `CompanyEventsResult`. - `data` `CompanyEventsData` (required) — The 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. - `ticker` `string | null` (required) - `cik` `integer` (required) - `company_name` `string` (required) - `events` `array` (required) - `event_date` `string (date)` (required) - `filed_date` `string (date)` (required) - `form_type` `string` (required) - `item_code` `string` (required) - `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"` (required) — Documented buckets for 8-K item codes (issue #41 §4). - `accession_number` `string` (required) - `primary_document_url` `string | null` (required) - `index_url` `string` (required) - `source` `string` (required) - `as_of` `string (date-time)` (required) - `meta` `Meta` (required) — Result-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. - `source` `string` (required) - `as_of` `string (date-time) | string (date) | null` - `pagination` `Pagination | null` - `limit` `integer` (required) - `has_more` `boolean` (required) - `next_cursor` `string | null` Fields are shown to 3 levels; the full schema is in https://www.agentdatasets.com/docs/machine/openapi.json ## 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 | Parameter | In | Type | Required | Default | Constraints | Description | | --- | --- | --- | --- | --- | --- | --- | | ticker_or_cik | query | `string` | yes | — | min length 1 | Ticker symbol (AAPL) or SEC CIK (320193) | | action_type | query | `string \| null` | no | — | — | Optional event type filter: dividend, split, delisting, ticker_change, or merger_acquisition | | start_date | query | `string (date) \| null` | no | — | — | Earliest event date, inclusive (YYYY-MM-DD) | | end_date | query | `string (date) \| null` | no | — | — | Latest event date, inclusive (YYYY-MM-DD) | | limit | query | `integer` | no | 100 | min 1, max 1000 | Corporate-action events to return, newest first | | cursor | query | `string \| null` | no | — | — | 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. ```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 — `CorporateActionsResult`. - `data` `CorporateActionsData` (required) - `ticker` `string | null` (required) - `cik` `integer` (required) - `company_name` `string` (required) - `action_type` `"dividend" | "split" | "delisting" | "ticker_change" | "merger_acquisition" | null` (required) - `actions` `array` (required) - `action_type` `"dividend" | "split" | "delisting" | "ticker_change" | "merger_acquisition"` (required) - `event_date` `string (date)` (required) - `amount` `string | null` - `currency` `string | null` - `ratio` `string | null` - `record_date` `string (date) | null` - `pay_date` `string (date) | null` - `accession_number` `string | null` - `details` `object | null` - `source` `string` (required) - `non_redistributable` `boolean` (required) - `as_of` `string (date-time)` (required) - `meta` `CorporateActionsMeta` (required) - `source` `string` (required) - `as_of` `string (date-time) | string (date) | null` - `non_redistributable` `boolean` - `restricted_omitted` `array | null` - `pagination` `Pagination | null` - `limit` `integer` (required) - `has_more` `boolean` (required) - `next_cursor` `string | null` Fields are shown to 3 levels; the full schema is in https://www.agentdatasets.com/docs/machine/openapi.json ## 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 | Parameter | In | Type | Required | Default | Constraints | Description | | --- | --- | --- | --- | --- | --- | --- | | ticker_or_cik | query | `string` | yes | — | — | Ticker symbol (AAPL, BRK.B) or CIK (320193, 0000320193) | | limit | query | `integer` | no | 8 | min 1, max 40 | Announcement-history rows; default 8, max 40 | ### Example request Required parameters only, with values taken from the schema. ```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 — `EarningsDatesResult`. - `data` `EarningsDatesData` (required) — Company identity, bounded announcement history, and the next estimate. - `ticker` `string | null` (required) - `cik` `integer` (required) - `company_name` `string` (required) - `history` `array` (required) - `announced_on` `string (date)` (required) - `filed_on` `string (date)` (required) - `form_type` `string` (required) - `accession_number` `string` (required) - `primary_document_url` `string | null` (required) - `index_url` `string` (required) - `source` `string` (required) - `as_of` `string (date-time)` (required) - `next` `NextEarningsEstimate | null` (required) - `window_start` `string (date)` (required) - `window_end` `string (date)` (required) - `basis` `"derived-from-announcement-cadence" | "derived-from-filing-cadence"` (required) - `cadence` `"quarterly" | "annual"` (required) - `observations` `integer` (required) - `median_gap_days` `integer | null` (required) - `stale` `boolean` (required) - `reason` `string | null` (required) - `source` `string` (required) - `as_of` `string (date-time)` (required) - `reason` `string | null` (required) - `meta` `Meta` (required) — Result-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. - `source` `string` (required) - `as_of` `string (date-time) | string (date) | null` - `pagination` `Pagination | null` - `limit` `integer` (required) - `has_more` `boolean` (required) - `next_cursor` `string | null` Fields are shown to 3 levels; the full schema is in https://www.agentdatasets.com/docs/machine/openapi.json ## GET /v1/stocks/events/search Search Events Route One 8-K event category across the ingested universe, newest first. ### Parameters | Parameter | In | Type | Required | Default | Constraints | Description | | --- | --- | --- | --- | --- | --- | --- | | category | query | `string` | yes | — | min length 1 | Event 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 | | tickers | query | `array \| null` | no | — | max items 20 | Repeated ticker filters, e.g. AAPL, MSFT | | start | query | `string (date) \| null` | no | — | — | Earliest event date, inclusive (YYYY-MM-DD) | | end | query | `string (date) \| null` | no | — | — | Latest event date, inclusive (YYYY-MM-DD) | | limit | query | `integer` | no | 20 | min 1, max 100 | Events to return, newest first | | cursor | query | `string \| null` | no | — | — | 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. ```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 — `EventSearchResult`. - `data` `EventSearchData` (required) — Filter 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"` (required) — Documented buckets for 8-K item codes (issue #41 §4). - `tickers` `array | null` (required) - `start` `string (date) | null` (required) - `end` `string (date) | null` (required) - `events` `array` (required) - `event_date` `string (date)` (required) - `filed_date` `string (date)` (required) - `form_type` `string` (required) - `item_code` `string` (required) - `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"` (required) — Documented buckets for 8-K item codes (issue #41 §4). - `accession_number` `string` (required) - `primary_document_url` `string | null` (required) - `index_url` `string` (required) - `source` `string` (required) - `as_of` `string (date-time)` (required) - `ticker` `string | null` (required) - `cik` `integer` (required) - `company_name` `string` (required) - `meta` `Meta` (required) — Result-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. - `source` `string` (required) - `as_of` `string (date-time) | string (date) | null` - `pagination` `Pagination | null` - `limit` `integer` (required) - `has_more` `boolean` (required) - `next_cursor` `string | null` Fields are shown to 3 levels; the full schema is in https://www.agentdatasets.com/docs/machine/openapi.json ## 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 | Parameter | In | Type | Required | Default | Constraints | Description | | --- | --- | --- | --- | --- | --- | --- | | ticker | query | `string` | yes | — | min length 1 | Ticker symbol, e.g. AAPL or BRK.B | | limit | query | `integer` | no | 4 | min 1, max 12 | Fiscal years to return, newest first. Counts years, not rows: a year with multiple PEOs returns one row per PEO. | | cursor | query | `string \| null` | no | — | — | 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. ```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 — `ExecutiveCompensationResult`. - `data` `ExecutiveCompensationData` (required) — The 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"). - `ticker` `string` (required) - `cik` `integer` (required) - `company_name` `string` (required) - `rows` `array` (required) - `fiscal_year` `integer` (required) - `period_start` `string (date)` (required) - `period_end` `string (date)` (required) - `peo_member` `string` (required) - `peo_name` `string | null` (required) - `company_selected_measure_name` `string | null` (required) - `measures` `map` (required) - `[key: string]` `PvpValue` — One 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. - `meta` `Meta` (required) — Result-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. - `source` `string` (required) - `as_of` `string (date-time) | string (date) | null` - `pagination` `Pagination | null` - `limit` `integer` (required) - `has_more` `boolean` (required) - `next_cursor` `string | null` Fields are shown to 3 levels; the full schema is in https://www.agentdatasets.com/docs/machine/openapi.json ## 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 | Parameter | In | Type | Required | Default | Constraints | Description | | --- | --- | --- | --- | --- | --- | --- | | ticker_or_cik | query | `string` | yes | — | min length 1 | Ticker symbol (AAPL, BRK.B) or CIK (320193, 0000320193) | ### Example request Required parameters only, with values taken from the schema. ```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 — `ExpectedReportResult`. - `data` `ExpectedReportData` (required) — One 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. - `ticker` `string | null` (required) - `cik` `integer` (required) - `company_name` `string` (required) - `estimate` `ExpectedReport | null` (required) - `expected_period_end` `string (date)` (required) - `expected_filing_window` `ExpectedFilingWindow` (required) — The 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. - `earliest` `string (date)` (required) - `latest` `string (date)` (required) - `cadence` `"quarterly" | "annual"` (required) - `basis` `"derived-from-filing-cadence"` - `basis_lag` `"median"` - `median_lag_days` `integer` (required) - `min_lag_days` `integer` (required) - `max_lag_days` `integer` (required) - `observations` `integer` (required) - `last_filed` `LastPeriodicFiling` (required) — The 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_type` `string` (required) - `period_of_report` `string (date)` (required) - `filed_date` `string (date)` (required) - `accession_number` `string` (required) - `stale` `boolean` (required) - `source` `string` (required) - `as_of` `string (date-time)` (required) - `reason` `string | null` (required) - `meta` `Meta` (required) — Result-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. - `source` `string` (required) - `as_of` `string (date-time) | string (date) | null` - `pagination` `Pagination | null` - `limit` `integer` (required) - `has_more` `boolean` (required) - `next_cursor` `string | null` Fields are shown to 3 levels; the full schema is in https://www.agentdatasets.com/docs/machine/openapi.json ## 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 | Parameter | In | Type | Required | Default | Constraints | Description | | --- | --- | --- | --- | --- | --- | --- | | days_ahead | query | `integer` | no | 7 | min 1, max 30 | How far ahead to look, in days from today | | limit | query | `integer` | no | 20 | min 1, max 100 | Companies per page | | cursor | query | `string \| null` | no | — | — | Opaque token from a previous response's next_cursor | ### Example request Required parameters only, with values taken from the schema. ```bash curl --fail --silent --show-error \ --header "X-API-KEY: adk_..." \ "https://api.agentdatasets.com/v1/stocks/expected-reports" ``` ### Response `200` Successful Response — `ExpectedReportSearchResult`. - `data` `ExpectedReportSearchData` (required) — The window echo plus the bounded, soonest-first page of estimates. - `window_start` `string (date)` (required) - `window_end` `string (date)` (required) - `days_ahead` `integer` (required) - `reports` `array` (required) - `expected_period_end` `string (date)` (required) - `expected_filing_window` `ExpectedFilingWindow` (required) — The 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. - `earliest` `string (date)` (required) - `latest` `string (date)` (required) - `cadence` `"quarterly" | "annual"` (required) - `basis` `"derived-from-filing-cadence"` - `basis_lag` `"median"` - `median_lag_days` `integer` (required) - `min_lag_days` `integer` (required) - `max_lag_days` `integer` (required) - `observations` `integer` (required) - `last_filed` `LastPeriodicFiling` (required) — The 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_type` `string` (required) - `period_of_report` `string (date)` (required) - `filed_date` `string (date)` (required) - `accession_number` `string` (required) - `stale` `boolean` (required) - `source` `string` (required) - `as_of` `string (date-time)` (required) - `ticker` `string | null` (required) - `cik` `integer` (required) - `company_name` `string` (required) - `meta` `Meta` (required) — Result-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. - `source` `string` (required) - `as_of` `string (date-time) | string (date) | null` - `pagination` `Pagination | null` - `limit` `integer` (required) - `has_more` `boolean` (required) - `next_cursor` `string | null` Fields are shown to 3 levels; the full schema is in https://www.agentdatasets.com/docs/machine/openapi.json ## GET /v1/stocks/filing-section Filing Section One 10-K/10-Q item as a bounded character-offset text page. ### Parameters | Parameter | In | Type | Required | Default | Constraints | Description | | --- | --- | --- | --- | --- | --- | --- | | ticker_or_cik | query | `string` | yes | — | min length 1 | Exact ticker (AAPL) or SEC CIK (320193) | | item | query | `string` | yes | — | — | Filing item code, e.g. ITEM_1A, Item 7, or Part I Item 2 | | accession_number | query | `string \| null` | no | — | — | Exact SEC accession; mutually exclusive with form_type | | form_type | query | `string \| null` | no | — | — | Latest indexed 10-K or 10-Q; mutually exclusive with accession | | page_chars | query | `integer` | no | 10000 | min 1000, max 25000 | Maximum characters in this page | | cursor | query | `string \| null` | no | — | — | Opaque pagination.next_cursor from the previous character page | ### Example request Required parameters only, with values taken from the schema. ```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 — `FilingSectionResult`. - `data` `FilingSectionData` (required) — One bounded character page from one canonical filing section. - `ticker` `string | null` (required) - `cik` `integer` (required) - `company_name` `string` (required) - `accession_number` `string` (required) - `form_type` `string` (required) - `filed_date` `string (date)` (required) - `period_of_report` `string (date) | null` (required) - `item_code` `string` (required) - `item_title` `string | null` (required) - `document_url` `string` (required) - `char_start` `integer` (required) - `char_end` `integer` (required) - `section_char_count` `integer` (required) - `text` `string` (required) - `meta` `Meta` (required) — Result-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. - `source` `string` (required) - `as_of` `string (date-time) | string (date) | null` - `pagination` `Pagination | null` - `limit` `integer` (required) - `has_more` `boolean` (required) - `next_cursor` `string | null` Fields are shown to 3 levels; the full schema is in https://www.agentdatasets.com/docs/machine/openapi.json ## GET /v1/stocks/filings Sec Filings SEC EDGAR filings metadata + sec.gov links for one company, newest first. ### Parameters | Parameter | In | Type | Required | Default | Constraints | Description | | --- | --- | --- | --- | --- | --- | --- | | ticker_or_cik | query | `string` | yes | — | min length 1 | Ticker symbol (AAPL) or SEC CIK (320193) | | form_type | query | `string \| null` | no | — | — | Exact EDGAR form filter, e.g. 10-K, 10-Q, 8-K (amendments end in /A) | | start | query | `string (date) \| null` | no | — | — | Earliest filing date, inclusive (YYYY-MM-DD) | | end | query | `string (date) \| null` | no | — | — | Latest filing date, inclusive (YYYY-MM-DD) | | limit | query | `integer` | no | 100 | min 1, max 1000 | Filings to return, newest first | | cursor | query | `string \| null` | no | — | — | 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. ```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 — `SecFilingsResult`. - `data` `SecFilingsData` (required) — The 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``. - `ticker` `string | null` (required) - `cik` `integer` (required) - `company_name` `string` (required) - `filings` `array` (required) - `form_type` `string` (required) - `filed_date` `string (date)` (required) - `period_of_report` `string (date) | null` (required) - `accession_number` `string` (required) - `primary_document_url` `string | null` (required) - `index_url` `string` (required) - `as_of` `string (date-time)` (required) - `meta` `Meta` (required) — Result-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. - `source` `string` (required) - `as_of` `string (date-time) | string (date) | null` - `pagination` `Pagination | null` - `limit` `integer` (required) - `has_more` `boolean` (required) - `next_cursor` `string | null` Fields are shown to 3 levels; the full schema is in https://www.agentdatasets.com/docs/machine/openapi.json ## GET /v1/stocks/filings/search Search Filings Route Live EDGAR full-text filing-document search with sec.gov citation URLs. ### Parameters | Parameter | In | Type | Required | Default | Constraints | Description | | --- | --- | --- | --- | --- | --- | --- | | query | query | `string` | yes | — | — | Full-text phrase/keyword to search across EDGAR filing documents | | forms | query | `array \| null` | no | — | — | EDGAR form types to restrict to, e.g. 10-K; repeat for many | | filed_from | query | `string (date) \| null` | no | — | — | Earliest filing date to include, inclusive (YYYY-MM-DD) | | filed_to | query | `string (date) \| null` | no | — | — | Latest filing date to include, inclusive (YYYY-MM-DD) | | ticker_or_cik | query | `string \| null` | no | — | — | Optional exact ticker or numeric SEC CIK to restrict to one filer | | limit | query | `integer` | no | 10 | min 1, max 50 | Document hits to return per page | | cursor | query | `string \| null` | no | — | — | 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. ```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 — `FilingSearchResult`. - `data` `FilingSearchData` (required) — The 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. - `query` `string` (required) - `forms` `array | null` (required) - `filed_from` `string (date) | null` (required) - `filed_to` `string (date) | null` (required) - `cik` `integer | null` (required) - `total_hits` `integer` (required) - `total_is_lower_bound` `boolean` (required) - `hits` `array` (required) - `form_type` `string` (required) - `filed_date` `string (date)` (required) - `accession_number` `string` (required) - `file_type` `string | null` (required) - `file_description` `string | null` (required) - `document_url` `string | null` (required) - `index_url` `string` (required) - `companies` `array` (required) - `cik` `integer` (required) - `display_name` `string | null` (required) - `score` `number` (required) - `meta` `Meta` (required) — Result-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. - `source` `string` (required) - `as_of` `string (date-time) | string (date) | null` - `pagination` `Pagination | null` - `limit` `integer` (required) - `has_more` `boolean` (required) - `next_cursor` `string | null` Fields are shown to 3 levels; the full schema is in https://www.agentdatasets.com/docs/machine/openapi.json ## 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 | Parameter | In | Type | Required | Default | Constraints | Description | | --- | --- | --- | --- | --- | --- | --- | | ticker | query | `string` | yes | — | min length 1 | Ticker symbol, e.g. AAPL or BRK.B | | period | query | `"annual" \| "quarterly" \| "ttm"` | no | "annual" | — | Fiscal frame for per-period metrics: annual (FY), quarterly, or ttm | | limit | query | `integer` | no | 4 | min 1, max 12 | Fiscal periods to return, newest first | | cursor | query | `string \| null` | no | — | — | 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. ```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 — `FinancialMetricsResult`. - `data` `FinancialMetricsData` (required) — The 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). - `ticker` `string` (required) - `cik` `integer` (required) - `company_name` `string` (required) - `period_type` `"annual" | "quarterly" | "ttm"` (required) - `metrics` `array` (required) - `fiscal_year` `integer` (required) - `fiscal_period` `"FY" | "Q1" | "Q2" | "Q3" | "Q4"` (required) - `period_type` `"annual" | "quarterly" | "ttm"` (required) - `period_start` `string (date)` (required) - `period_end` `string (date)` (required) - `period_label` `string` (required) - `metrics` `map` (required) - `[key: string]` `MetricValue` — One 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. - `valuation` `Valuation | null` (required) - `as_of` `string (date-time)` (required) - `price` `string` (required) - `price_date` `string (date)` (required) - `non_redistributable` `boolean` (required) - `metrics` `map` (required) - `[key: string]` `MetricValue` — One 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. - `meta` `MetricsMeta` (required) — Result-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. - `source` `string` (required) - `as_of` `string (date-time) | string (date) | null` - `non_redistributable` `boolean` - `restricted_omitted` `array | null` - `pagination` `Pagination | null` - `limit` `integer` (required) - `has_more` `boolean` (required) - `next_cursor` `string | null` Fields are shown to 3 levels; the full schema is in https://www.agentdatasets.com/docs/machine/openapi.json ## GET /v1/stocks/fund-holders Fund Holders Covered registered funds holding one company in their latest N-PORT filing. ### Parameters | Parameter | In | Type | Required | Default | Constraints | Description | | --- | --- | --- | --- | --- | --- | --- | | ticker | query | `string` | yes | — | min length 1 | Ticker symbol (AAPL, BRK.B) | | limit | query | `integer` | no | 25 | min 1, max 100 | Registered fund holders to return, highest portfolio weight first | | cursor | query | `string \| null` | no | — | — | 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. ```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 — `StocksGetFundHoldersResult`. - `data` `StocksGetFundHoldersData` (required) — Resolved stock identity and its bounded page of registered-fund holders. - `ticker` `string` (required) - `cik` `integer` (required) - `company_name` `string` (required) - `holders` `array` (required) - `series_id` `string` (required) - `series_name` `string | null` (required) - `registrant_name` `string | null` (required) - `cik` `integer` (required) - `form_type` `string` (required) - `accession_number` `string` (required) - `filed_date` `string (date)` (required) - `report_period` `string (date)` (required) - `value_usd` `string | null` (required) - `pct_value` `string | null` (required) - `holdings_count` `integer` (required) - `meta` `StocksGetFundHoldersMeta` (required) — N-PORT attribution and coverage limits for the stock-to-fund join. - `source` `string` (required) - `as_of` `string (date-time) | string (date) | null` - `attribution` `string` (required) - `coverage` `string` (required) - `covered_funds` `integer` (required) - `match_basis` `string` (required) - `total_holdings` `integer` (required) - `unattributed_holdings` `integer` (required) - `pagination` `Pagination | null` - `limit` `integer` (required) - `has_more` `boolean` (required) - `next_cursor` `string | null` Fields are shown to 3 levels; the full schema is in https://www.agentdatasets.com/docs/machine/openapi.json ## 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 | Parameter | In | Type | Required | Default | Constraints | Description | | --- | --- | --- | --- | --- | --- | --- | | ticker_or_cik | query | `string` | yes | — | min length 1 | Ticker symbol (AAPL, BRK.B) or SEC CIK (320193) | | period | query | `"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. | | limit | query | `integer` | no | 4 | min 1, max 12 | Fiscal periods to return, newest first | | cursor | query | `string \| null` | no | — | — | Opaque pagination cursor from a previous response's pagination.next_cursor; omit to start from the newest. | | as_reported | query | `boolean` | no | false | — | 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. ```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 — `IncomeStatementsResult`. - `data` `IncomeStatementsData` (required) — Income-statement ``data``: identity + the bounded, newest-first list. - `ticker` `string | null` (required) - `cik` `integer` (required) - `company_name` `string` (required) - `period_type` `"annual" | "quarterly" | "ttm"` (required) - `reporting_standard` `"us-gaap" | "ifrs-full" | null` (required) - `statements` `array` (required) - `fiscal_year` `integer` (required) - `fiscal_period` `"FY" | "Q1" | "Q2" | "Q3" | "Q4"` (required) - `period_type` `"annual" | "quarterly" | "ttm"` (required) - `period_start` `string (date)` (required) - `period_end` `string (date)` (required) - `lines` `map` (required) - `[key: string]` `StatementValue` — One 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. - `meta` `StatementsMeta` (required) — Statement provenance plus source-document view and restatement lineage. - `source` `string` (required) - `as_of` `string (date-time) | string (date) | null` - `as_reported` `boolean` - `restatements` `array | null` - `fiscal_year` `integer` (required) - `fiscal_period` `"FY" | "Q1" | "Q2" | "Q3" | "Q4"` (required) - `period_type` `"annual" | "quarterly" | "ttm"` (required) - `line_key` `string` (required) - `original_accession_number` `string | null` (required) - `superseding_accession_number` `string | null` (required) - `pagination` `Pagination | null` - `limit` `integer` (required) - `has_more` `boolean` (required) - `next_cursor` `string | null` Fields are shown to 3 levels; the full schema is in https://www.agentdatasets.com/docs/machine/openapi.json ## GET /v1/stocks/insider-trades Insider Trades Forms 3/4/5 insider transactions for one company, newest filing first. ### Parameters | Parameter | In | Type | Required | Default | Constraints | Description | | --- | --- | --- | --- | --- | --- | --- | | ticker | query | `string` | yes | — | min length 1 | Ticker symbol (AAPL, BRK.B) | | transaction_type | query | `string \| null` | no | — | — | Optional bucket filter: buy, sell, award, exercise, gift, or other | | derivative | query | `boolean \| null` | no | — | — | Optional table filter: true = derivative rows only, false = Table I | | insider_name | query | `string \| null` | no | — | — | Optional case-insensitive substring match on the reporting owner | | filed_from | query | `string (date) \| null` | no | — | — | Earliest filed date, inclusive (YYYY-MM-DD) | | filed_to | query | `string (date) \| null` | no | — | — | Latest filed date, inclusive (YYYY-MM-DD) | | include_superseded | query | `boolean` | no | false | — | Include superseded filings for audit history | | limit | query | `integer` | no | 20 | min 1, max 100 | Transactions to return, newest filing first | | cursor | query | `string \| null` | no | — | — | 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. ```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 — `InsiderTradesResult`. - `data` `InsiderTradesData` (required) — Issuer identity, filter echoes, the summary block, and the page. - `ticker` `string | null` (required) - `cik` `integer` (required) - `company_name` `string` (required) - `coverage_start` `string (date)` (required) - `transaction_type` `string | null` (required) - `derivative` `boolean | null` (required) - `insider_name` `string | null` (required) - `include_superseded` `boolean` (required) - `summary` `InsiderTradesSummary` (required) — Net 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_shares` `string` (required) - `buy_transactions` `integer` (required) - `sell_transactions` `integer` (required) - `filed_from` `string (date) | null` (required) - `filed_to` `string (date) | null` (required) - `transactions` `array` (required) - `accession_number` `string` (required) - `form_type` `string` (required) - `filed_date` `string (date)` (required) - `owner_name` `string` (required) - `owner_cik` `integer` (required) - `is_director` `boolean` (required) - `is_officer` `boolean` (required) - `is_ten_percent_owner` `boolean` (required) - `officer_title` `string | null` (required) - `is_derivative` `boolean` (required) - `is_holding` `boolean` (required) - `transaction_date` `string (date) | null` (required) - `transaction_code` `string | null` (required) - `transaction_type` `string | null` (required) - `security_title` `string` (required) - `shares` `string | null` (required) - `price_per_share` `string | null` (required) - `acquired_disposed` `string | null` (required) - `shares_owned_following` `string | null` (required) - `direct_or_indirect` `string | null` (required) - `indirect_nature` `string | null` (required) - `meta` `Meta` (required) — Result-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. - `source` `string` (required) - `as_of` `string (date-time) | string (date) | null` - `pagination` `Pagination | null` - `limit` `integer` (required) - `has_more` `boolean` (required) - `next_cursor` `string | null` Fields are shown to 3 levels; the full schema is in https://www.agentdatasets.com/docs/machine/openapi.json ## GET /v1/stocks/ipo-profile Ipo Profile One CIK's chronological registration-event timeline. ### Parameters | Parameter | In | Type | Required | Default | Constraints | Description | | --- | --- | --- | --- | --- | --- | --- | | cik | query | `integer` | yes | — | min 1 | Positive SEC Central Index Key (CIK) | ### Example request Required parameters only, with values taken from the schema. ```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 — `IpoProfileResult`. - `data` `IpoProfileData` (required) — One CIK's registration timeline and any anchored lifecycle fields. - `cik` `integer` (required) - `company_name` `string` (required) - `sic` `string | null` (required) - `sic_description` `string | null` (required) - `stage` `string | null` (required) - `first_filed_date` `string (date) | null` (required) - `effective_date` `string (date) | null` (required) - `priced_date` `string (date) | null` (required) - `withdrawn_date` `string (date) | null` (required) - `latest_event_date` `string (date) | null` (required) - `event_count` `integer` (required) - `events` `array` (required) - `filed_date` `string (date)` (required) - `form_type` `string` (required) - `accession_number` `string` (required) - `filing_index_url` `string` (required) - `meta` `Meta` (required) — Result-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. - `source` `string` (required) - `as_of` `string (date-time) | string (date) | null` - `pagination` `Pagination | null` - `limit` `integer` (required) - `has_more` `boolean` (required) - `next_cursor` `string | null` Fields are shown to 3 levels; the full schema is in https://www.agentdatasets.com/docs/machine/openapi.json ## GET /v1/stocks/ipos Ipos Search initial-registration lifecycles, newest first. ### Parameters | Parameter | In | Type | Required | Default | Constraints | Description | | --- | --- | --- | --- | --- | --- | --- | | stage | query | `string \| null` | no | — | — | Lifecycle stage: in_registration, effective, priced, or withdrawn | | filed_from | query | `string (date) \| null` | no | — | — | Earliest first-filed date, inclusive (YYYY-MM-DD) | | filed_to | query | `string (date) \| null` | no | — | — | Latest first-filed date, inclusive (YYYY-MM-DD) | | sic | query | `string \| null` | no | — | — | Exact raw SEC SIC code string | | limit | query | `integer` | no | 20 | min 1, max 100 | IPO registrations to return, newest first | | cursor | query | `string \| null` | no | — | — | 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. ```bash curl --fail --silent --show-error \ --header "X-API-KEY: adk_..." \ "https://api.agentdatasets.com/v1/stocks/ipos" ``` ### Response `200` Successful Response — `IposSearchResult`. - `data` `IpoSearchData` (required) — Echoed search filters and the matching IPO registration lifecycles. - `stage` `string | null` (required) - `filed_from` `string (date) | null` (required) - `filed_to` `string (date) | null` (required) - `sic` `string | null` (required) - `ipos` `array` (required) - `cik` `integer` (required) - `company_name` `string` (required) - `sic` `string | null` (required) - `sic_description` `string | null` (required) - `stage` `string` (required) - `first_filed_date` `string (date)` (required) - `effective_date` `string (date) | null` (required) - `priced_date` `string (date) | null` (required) - `withdrawn_date` `string (date) | null` (required) - `latest_event_date` `string (date)` (required) - `event_count` `integer` (required) - `meta` `Meta` (required) — Result-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. - `source` `string` (required) - `as_of` `string (date-time) | string (date) | null` - `pagination` `Pagination | null` - `limit` `integer` (required) - `has_more` `boolean` (required) - `next_cursor` `string | null` Fields are shown to 3 levels; the full schema is in https://www.agentdatasets.com/docs/machine/openapi.json ## GET /v1/stocks/line-items/search Line Items Search Selected canonical statement lines across several companies. ### Parameters | Parameter | In | Type | Required | Default | Constraints | Description | | --- | --- | --- | --- | --- | --- | --- | | tickers | query | `array` | yes | — | min items 1, max items 20 | Repeated exact ticker symbols to compare | | line_items | query | `array` | yes | — | min items 1, max items 20 | Repeated exact canonical statement line keys | | period | query | `"annual" \| "quarterly" \| "ttm"` | no | "annual" | — | Fiscal frame: annual (FY), quarterly (Q1–Q4), or ttm | | limit | query | `integer` | no | 4 | min 1, max 12 | Newest fiscal periods retained independently per ticker and line item | | cursor | query | `string \| null` | no | — | — | 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. ```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 — `LineItemsSearchResult`. - `data` `LineItemsSearchData` (required) — Resolved identities, selected lines, page rows, and partial failures. - `companies` `array` (required) - `ticker` `string` (required) - `cik` `integer` (required) - `company_name` `string` (required) - `period_type` `"annual" | "quarterly" | "ttm"` (required) - `line_items` `array` (required) - `results` `array` (required) - `ticker` `string` (required) - `fiscal_year` `integer` (required) - `fiscal_period` `"FY" | "Q1" | "Q2" | "Q3" | "Q4"` (required) - `period_type` `"annual" | "quarterly" | "ttm"` (required) - `period_start` `string (date)` (required) - `period_end` `string (date)` (required) - `lines` `map` (required) - `[key: string]` `StatementValue` — One 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. - `unresolved_tickers` `array` (required) - `ticker` `string` (required) - `code` `string` (required) - `message` `string` (required) - `suggestions` `array | null` - `unknown_line_items` `array` (required) - `meta` `Meta` (required) — Result-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. - `source` `string` (required) - `as_of` `string (date-time) | string (date) | null` - `pagination` `Pagination | null` - `limit` `integer` (required) - `has_more` `boolean` (required) - `next_cursor` `string | null` Fields are shown to 3 levels; the full schema is in https://www.agentdatasets.com/docs/machine/openapi.json ## GET /v1/stocks/ownership-filings Ownership Filings Schedule 13D/13G ownership-filing events, newest first. ### Parameters | Parameter | In | Type | Required | Default | Constraints | Description | | --- | --- | --- | --- | --- | --- | --- | | ticker | query | `string \| null` | no | — | — | Optional subject-company filter by ticker symbol | | filer_name | query | `string \| null` | no | — | — | Optional case-insensitive substring match on a reporting person | | schedule_type | query | `string \| null` | no | — | — | Optional schedule filter: 13D or 13G | | filed_from | query | `string (date) \| null` | no | — | — | Earliest filed date, inclusive (YYYY-MM-DD) | | filed_to | query | `string (date) \| null` | no | — | — | Latest filed date, inclusive (YYYY-MM-DD) | | limit | query | `integer` | no | 20 | min 1, max 100 | Filings to return, newest first | | cursor | query | `string \| null` | no | — | — | 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. ```bash curl --fail --silent --show-error \ --header "X-API-KEY: adk_..." \ "https://api.agentdatasets.com/v1/stocks/ownership-filings" ``` ### Response `200` Successful Response — `OwnershipFilingSearchResult`. - `data` `OwnershipFilingSearchData` (required) — Filter echoes plus the bounded newest-first filing page. - `ticker` `string | null` (required) - `filer_name` `string | null` (required) - `schedule_type` `string | null` (required) - `filed_from` `string (date) | null` (required) - `filed_to` `string (date) | null` (required) - `coverage_start` `string (date)` (required) - `filings` `array` (required) - `accession_number` `string` (required) - `schedule_type` `string` (required) - `submission_type` `string` (required) - `amendment_number` `integer | null` (required) - `subject_name` `string` (required) - `subject_cik` `integer` (required) - `cusip` `string | null` (required) - `date_of_event` `string (date) | null` (required) - `filed_date` `string (date)` (required) - `reporting_persons` `array` (required) - `name` `string` (required) - `cik` `integer | null` (required) - `person_type` `string | null` (required) - `percent_of_class` `string | null` (required) - `shares_beneficially_owned` `string | null` (required) - `meta` `Meta` (required) — Result-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. - `source` `string` (required) - `as_of` `string (date-time) | string (date) | null` - `pagination` `Pagination | null` - `limit` `integer` (required) - `has_more` `boolean` (required) - `next_cursor` `string | null` Fields are shown to 3 levels; the full schema is in https://www.agentdatasets.com/docs/machine/openapi.json ## 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 | Parameter | In | Type | Required | Default | Constraints | Description | | --- | --- | --- | --- | --- | --- | --- | | ticker_or_cik | query | `string` | yes | — | min length 1 | Ticker symbol (AAPL, BRK.B) or CIK (320193, 0000320193) | | limit | query | `integer` | no | 10 | min 1, max 20 | Peers to return, nearest in trailing-annual revenue first | | metrics | query | `array \| null` | no | — | max items 10 | Repeated 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. ```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 — `StocksPeersResult`. - `data` `StocksPeersData` (required) — The subject's identity echo, the basis used, and the comparison rows. - `ticker` `string | null` (required) - `cik` `integer` (required) - `company_name` `string` (required) - `basis` `"sic-major-group" | "sector" | null` (required) - `sector` `string | null` (required) - `sic_major_group` `string | null` (required) - `size_metric` `string` (required) - `metrics` `array` (required) - `peer_universe_size` `integer` (required) - `subject` `PeerCompany` (required) — One 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). - `ticker` `string | null` (required) - `cik` `integer` (required) - `company_name` `string` (required) - `exchange` `string | null` (required) - `sector` `string | null` (required) - `sic_code` `string | null` (required) - `metrics` `array` (required) - `metric` `string` (required) - `value` `string` (required) - `unit` `string` (required) - `currency` `string | null` (required) - `fiscal_year` `integer | null` (required) - `fiscal_period` `"FY" | "Q1" | "Q2" | "Q3" | "Q4" | null` (required) - `period_type` `"annual" | "quarterly" | "ttm" | null` (required) - `period_start` `string (date) | null` (required) - `period_end` `string (date) | null` (required) - `as_of` `string (date-time)` (required) - `source` `string` (required) - `peers` `array` (required) - `ticker` `string | null` (required) - `cik` `integer` (required) - `company_name` `string` (required) - `exchange` `string | null` (required) - `sector` `string | null` (required) - `sic_code` `string | null` (required) - `metrics` `array` (required) - `metric` `string` (required) - `value` `string` (required) - `unit` `string` (required) - `currency` `string | null` (required) - `fiscal_year` `integer | null` (required) - `fiscal_period` `"FY" | "Q1" | "Q2" | "Q3" | "Q4" | null` (required) - `period_type` `"annual" | "quarterly" | "ttm" | null` (required) - `period_start` `string (date) | null` (required) - `period_end` `string (date) | null` (required) - `as_of` `string (date-time)` (required) - `source` `string` (required) - `reason` `string | null` (required) - `meta` `StocksPeersMeta` (required) - `source` `string` (required) - `as_of` `string (date-time) | string (date) | null` - `pagination` `Pagination | null` - `limit` `integer` (required) - `has_more` `boolean` (required) - `next_cursor` `string | null` Fields are shown to 3 levels; the full schema is in https://www.agentdatasets.com/docs/machine/openapi.json ## GET /v1/stocks/proxy-voting-summary Proxy Voting Summary Covered N-PX manager votes for one company's shareholder meetings. ### Parameters | Parameter | In | Type | Required | Default | Constraints | Description | | --- | --- | --- | --- | --- | --- | --- | | ticker | query | `string` | yes | — | min length 1 | US public company ticker symbol, e.g. STZ | | limit | query | `integer` | no | 2 | min 1, max 5 | Shareholder meetings to return, newest first | | cursor | query | `string \| null` | no | — | — | Opaque pagination.next_cursor from the previous page | ### Example request Required parameters only, with values taken from the schema. ```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 — `ProxyVotingSummaryResult`. - `data` `ProxyVotingSummaryData` (required) — Canonical company identity and its bounded proxy-voting meeting page. - `ticker` `string` (required) - `company_name` `string` (required) - `meetings` `array` (required) - `meeting_date` `string (date) | null` (required) - `managers_covered` `integer` (required) - `proposals` `array` (required) - `description` `string` (required) - `categories` `array` (required) - `tallies` `array` (required) - `managers` `array` (required) - `managers_truncated` `boolean | null` - `proposals_truncated` `boolean | null` - `meta` `ProxyVotingSummaryMeta` (required) — EDGAR provenance plus the explicit N-PX manager coverage basis. - `source` `string` (required) - `as_of` `string (date-time) | string (date) | null` - `coverage` `string` (required) - `pagination` `Pagination | null` - `limit` `integer` (required) - `has_more` `boolean` (required) - `next_cursor` `string | null` Fields are shown to 3 levels; the full schema is in https://www.agentdatasets.com/docs/machine/openapi.json ## GET /v1/stocks/recent-filings Recent Filings SEC EDGAR filings metadata + sec.gov links across companies, newest first. ### Parameters | Parameter | In | Type | Required | Default | Constraints | Description | | --- | --- | --- | --- | --- | --- | --- | | filed_after | query | `string (date) \| null` | no | — | — | Earliest filing date to include, inclusive (YYYY-MM-DD) | | form_types | query | `array \| null` | no | — | max items 10 | Repeated EDGAR form filters, e.g. 10-K, 8-K | | tickers | query | `array \| null` | no | — | max items 20 | Repeated ticker filters, e.g. AAPL, MSFT | | limit | query | `integer` | no | 100 | min 1, max 1000 | Filings to return, newest first | | cursor | query | `string \| null` | no | — | — | 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. ```bash curl --fail --silent --show-error \ --header "X-API-KEY: adk_..." \ "https://api.agentdatasets.com/v1/stocks/recent-filings" ``` ### Response `200` Successful Response — `RecentFilingsResult`. - `data` `RecentFilingsData` (required) — The 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_after` `string (date) | null` (required) - `form_types` `array | null` (required) - `tickers` `array | null` (required) - `filings` `array` (required) - `form_type` `string` (required) - `filed_date` `string (date)` (required) - `period_of_report` `string (date) | null` (required) - `accession_number` `string` (required) - `primary_document_url` `string | null` (required) - `index_url` `string` (required) - `as_of` `string (date-time)` (required) - `ticker` `string | null` (required) - `cik` `integer` (required) - `company_name` `string` (required) - `meta` `Meta` (required) — Result-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. - `source` `string` (required) - `as_of` `string (date-time) | string (date) | null` - `pagination` `Pagination | null` - `limit` `integer` (required) - `has_more` `boolean` (required) - `next_cursor` `string | null` Fields are shown to 3 levels; the full schema is in https://www.agentdatasets.com/docs/machine/openapi.json ## 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 | Parameter | In | Type | Required | Default | Constraints | Description | | --- | --- | --- | --- | --- | --- | --- | | filters | query | `string` | yes | — | — | JSON-encoded list of typed filters, for example [{"metric":"net_margin","op":"gte","value":"0.2"}] | | sort | query | `string \| null` | no | — | — | Optional JSON-encoded sort object, for example {"metric":"roe","direction":"desc"} | | limit | query | `integer` | no | 20 | min 1, max 100 | Companies to return per page | | cursor | query | `string \| null` | no | — | — | Opaque pagination.next_cursor from the previous page | ### Example request Required parameters only, with values taken from the schema. ```bash curl --fail --silent --show-error \ --header "X-API-KEY: adk_..." \ "https://api.agentdatasets.com/v1/stocks/screen?filters=FILTERS" ``` ### Response `200` Successful Response — `StocksScreenResult`. - `data` `StocksScreenData` (required) - `filters` `array` (required) - `metric` `string` (required) - `op` `"gt" | "gte" | "lt" | "lte" | "eq" | "between" | "in"` (required) - `value` `string | array` (required) - `sort` `ScreenSort` (required) — The numeric snapshot metric and direction that define the total order. - `metric` `string` (required) - `direction` `"asc" | "desc"` - `companies` `array` (required) - `ticker` `string | null` (required) - `cik` `integer` (required) - `company_name` `string` (required) - `exchange` `string | null` (required) - `sector` `string | null` (required) - `sic_code` `string | null` (required) - `metrics` `array` (required) - `metric` `string` (required) - `value` `string` (required) - `unit` `string` (required) - `currency` `string | null` (required) - `fiscal_year` `integer | null` (required) - `fiscal_period` `"FY" | "Q1" | "Q2" | "Q3" | "Q4" | null` (required) - `period_type` `"annual" | "quarterly" | "ttm" | null` (required) - `period_start` `string (date) | null` (required) - `period_end` `string (date) | null` (required) - `as_of` `string (date-time)` (required) - `source` `string` (required) - `meta` `StocksScreenMeta` (required) - `source` `string` (required) - `as_of` `string (date-time) | string (date) | null` - `pagination` `Pagination | null` - `limit` `integer` (required) - `has_more` `boolean` (required) - `next_cursor` `string | null` Fields are shown to 3 levels; the full schema is in https://www.agentdatasets.com/docs/machine/openapi.json ## GET /v1/stocks/search Search Ranked entity matches for a name/ticker/fragment query, best first. ### Parameters | Parameter | In | Type | Required | Default | Constraints | Description | | --- | --- | --- | --- | --- | --- | --- | | query | query | `string` | yes | — | — | Company name, ticker, or fragment to search | | limit | query | `integer` | no | 10 | min 1, max 50 | Max ranked matches to return | ### Example request Required parameters only, with values taken from the schema. ```bash curl --fail --silent --show-error \ --header "X-API-KEY: adk_..." \ "https://api.agentdatasets.com/v1/stocks/search?query=QUERY" ``` ### Response `200` Successful Response — `TickerSearchResult`. - `data` `TickerSearchData` (required) — The 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`). - `query` `string` (required) - `matches` `array` (required) - `cik` `integer` (required) - `name` `string` (required) - `symbol` `string | null` (required) - `exchange` `string | null` (required) - `symbol_active` `boolean` (required) - `score` `number` (required) - `match_reason` `"ticker_exact" | "ticker_prefix" | "name_exact" | "name_fuzzy"` (required) - `source` `string` (required) - `as_of` `string (date-time)` (required) - `meta` `Meta` (required) — Result-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. - `source` `string` (required) - `as_of` `string (date-time) | string (date) | null` - `pagination` `Pagination | null` - `limit` `integer` (required) - `has_more` `boolean` (required) - `next_cursor` `string | null` Fields are shown to 3 levels; the full schema is in https://www.agentdatasets.com/docs/machine/openapi.json ## GET /v1/stocks/segmented-financials Segmented Financials Revenue or operating income by segment for one company, newest year first. ### Parameters | Parameter | In | Type | Required | Default | Constraints | Description | | --- | --- | --- | --- | --- | --- | --- | | ticker | query | `string` | yes | — | min length 1 | Ticker symbol, e.g. AAPL or BRK.B | | axis | query | `"business_segments" \| "products_services" \| "geography"` | yes | — | — | Disaggregation axis: business_segments, products_services, geography | | metric | query | `"revenue" \| "operating_income"` | no | "revenue" | — | revenue (all axes) or operating_income (business_segments axis only) | | include_non_operating | query | `boolean` | no | false | — | Include elimination and corporate/other members | | limit | query | `integer` | no | 4 | min 1, max 12 | Fiscal years to return, newest first | | cursor | query | `string \| null` | no | — | — | Opaque pagination.next_cursor from the previous page | ### Example request Required parameters only, with values taken from the schema. ```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 — `SegmentedFinancialsResult`. - `data` `SegmentedFinancialsData` (required) — The 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. - `ticker` `string` (required) - `cik` `integer` (required) - `company_name` `string` (required) - `axis` `"business_segments" | "products_services" | "geography"` (required) — The XBRL dimension a segment series is disaggregated on. - `metric` `"revenue" | "operating_income"` (required) — The canonical measures served per segment member. - `frames` `array` (required) - `fiscal_year` `integer` (required) - `fiscal_period` `"FY" | "Q1" | "Q2" | "Q3" | "Q4"` (required) - `period_type` `"annual" | "quarterly" | "ttm"` (required) - `period_start` `string (date)` (required) - `period_end` `string (date)` (required) - `currency` `string | null` (required) - `unit` `string` (required) - `segments` `array` (required) - `member` `string` (required) - `member_label` `string` (required) - `member_role` `"operating" | "elimination" | "corporate_other"` (required) — How a member participates in the tie back to the consolidated total. - `value` `string` (required) - `share_of_total` `string | null` (required) - `accession_number` `string` (required) - `as_of` `string (date-time)` (required) - `consolidated_total` `ConsolidatedTotal | null` (required) - `value` `string` (required) - `accession_number` `string` (required) - `as_of` `string (date-time)` (required) - `meta` `SegmentsMeta` (required) — Segment 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. - `source` `string` (required) - `as_of` `string (date-time) | string (date) | null` - `pagination` `Pagination | null` - `limit` `integer` (required) - `has_more` `boolean` (required) - `next_cursor` `string | null` Fields are shown to 3 levels; the full schema is in https://www.agentdatasets.com/docs/machine/openapi.json