# AkkruData Docs ## Overview These docs describe the AkkruData HTTP API (data, metrics, ownership, corporate events and screening: request and response fields, HTTP status codes, credit usage, and rate limits) and the AkkruData MCP server. **Base URL:** `https://api.akkrudata.ai/api/v1` Endpoint paths in this guide are appended to that prefix (for example, `POST …/data/filings` means `POST https://api.akkrudata.ai/api/v1/data/filings`). > **Note:** All request and response JSON examples in this documentation are provided for reference purposes only. They may be abbreviated or truncated for readability, and the exact structure or available fields are subject to change without prior notice. # Get Started ## MCP Every dataset in these docs is also available through the Model Context Protocol (MCP). Your assistant gets ten tools for companies, filings, statements, facts, metrics, ownership and events, and calls them when a question needs filing data. ```text title="Server URL" https://api.akkrudata.ai/mcp ``` ### Connect your client Clients sign you in with OAuth: sign in with the same AkkruData account you use for the dashboard (email and password, Google, or GitHub), review the connecting client, and click **Authorize**. Tokens renew automatically. #### Claude (web and desktop) 1. Open **Customize → Connectors** and click **Add custom connector**. 2. Enter `https://api.akkrudata.ai/mcp` as the server URL. If Claude asks how it should identify itself, choose **Register automatically**. Click **Add**. 3. Sign in with your AkkruData account when Claude asks, review the client, and click **Authorize**. On Team and Enterprise plans, an Owner adds the connector under **Organization settings → Connectors**, and each member clicks **Connect** under **Customize → Connectors**. #### Claude Code ```bash claude mcp add --transport http akkrudata https://api.akkrudata.ai/mcp ``` Then run `/mcp` inside Claude Code and finish sign-in in your browser. #### Cursor Add the server to `~/.cursor/mcp.json`, then sign in when Cursor prompts you. ```json { "mcpServers": { "akkrudata": { "url": "https://api.akkrudata.ai/mcp" } } } ``` #### Other clients Add `https://api.akkrudata.ai/mcp` as a remote MCP server (custom connector) with OAuth, then sign in. ### Managing connections List and disconnect any authorized assistant from **Connected AI assistants** in the dashboard. One account can hold up to 10 connections at a time. ### Tools | Tool | Data | Actions | |---|---|---| | [`akkru_companies`](#akkru_companies) | Find a company and see what is covered for it. | `search`, `lookup`, `list` | | [`akkru_filings`](#akkru_filings) | The financial reports (10-K, 10-Q, 20-F, 40-F and their Korean, Japanese, Chinese and European equivalents) on file for a company. | `list`, `excel` | | [`akkru_statements`](#akkru_statements) | Whole statements and notes of one filing, as filed: every row with its value, period, unit and source. | `get`, `list` | | [`akkru_facts`](#akkru_facts) | Single reported numbers (and text facts) from filings, each with its period, unit, dimensions and a link to its place in the filing. | `get`, `breakdown` | | [`akkru_metrics`](#akkru_metrics) | 82 metrics computed from each filing (margins, growth, leverage, efficiency, cash flow, valuation), each with its formula and the facts it used. US companies only. Starter plan or higher; formula_override needs Pro. | `get`, `history`, `list`, `catalog`, `search` | | [`akkru_insider_transactions`](#akkru_insider_transactions) | Trades insiders report on SEC Form 4 (and Form 5), nested filing then transactions, with the insiders, footnotes and links to the filing. A trade's direction is its acquired_disposed_code (A or D). Rows failing a consistency check carry data_quality_flags and are left out unless include_anomalies is true; the count left out is reported. | `list`, `stats`, `get`, `insiders`, `types`, `tickers`, `search` | | [`akkru_initial_holdings`](#akkru_initial_holdings) | What insiders report holding when they become insiders (SEC Form 3), nested filing then holdings; no_securities_owned true means the filer reported holding nothing. Rows failing a consistency check carry data_quality_flags and are left out unless include_anomalies is true. | `list`, `stats`, `get`, `insiders`, `tickers`, `search` | | [`akkru_institutional_holdings`](#akkru_institutional_holdings) | What institutional managers report holding each quarter on SEC Form 13F, by manager (filer CIK) and quarter. Links open the filing's EDGAR index page. | `managers`, `history`, `portfolio`, `holders`, `search` | | [`akkru_events`](#akkru_events) | Corporate events US companies report to the SEC, one section per Item (e.g. 5.02, officer changes), each with a summary and a link to its place in the filing; amendments are merged into the filing they amend. Starter plan or higher; results stop at your plan's history window. | `types`, `list`, `get`, `search` | | [`akkru_account`](#akkru_account) | Your account. | `balance` | ### Calling a tool Every tool takes `action` plus that action's parameters. Each tool's page lists its actions with their credits and every parameter with the actions that take it. A parameter set to `null` counts as not given. ```json {"action": "get", "ticker": "AAPL", "fiscal_year": 2025, "line_items": ["revenue"]} ``` `detail` is `"full"` (default), `"light"` or `"minimal"` on the actions that take it; all three are charged the same. ### Responses A successful call returns the reply as JSON text without indentation. Read `_warnings` in every reply. ### Errors A failed call returns `isError: true` with `{"error": {...}}`: | Field | Meaning | |---|---| | `source` | `tool`: the call was refused before any data was read, and nothing was charged. `api`: the request ran and returned an error. | | `code` | A stable error code. For `source` `api`, the codes listed under [Errors](#errors) and each endpoint. | | `message` | What is wrong. | | `status` | HTTP status, for `source` `api`. | | `params`, `accepted` | The parameters at fault, and the valid values or parameter names. | | `hint` | The next step, when there is one. | Errors with `source` `tool`: | `code` | When | |---|---| | `TOOL_UNKNOWN` | No tool has that name. | | `TOOL_PARAM_MISSING` | `action`, or one of the parameters the action needs, is missing. | | `TOOL_PARAM_INVALID` | `action`, or a parameter that selects what the action returns, has a value outside `accepted`. | | `TOOL_PARAM_NOT_ACCEPTED` | The action does not take the parameters in `params`. | | `TOOL_PARAM_CONFLICT` | The parameters in `params` cannot be used together. | | `INTERNAL_SERVER_ERROR` | The tool failed unexpectedly. | Other parameter values are checked when the request runs; a wrong value returns an error with `source` `api`. ### Credits and limits Each action costs the credits its tool page shows, from your account's balance, under the account's rate limits ([Credits & Rate Limits](#credits-rate-limits)). Calls refused with `source` `tool` are not charged. `akkru_account` with action `balance` shows the credits left. ## akkru_companies Find a company and see what is covered for it. ### Actions | Action | What it does | |---|---| | `search` | Companies whose name contains query, or whose ticker or registrant id starts with it; up to 8 candidates, best match first. 10 credits. | | `lookup` | One company by exactly one of ticker, cik, dart_corp_code, edinet_code, lei or uscc: its identity, every ticker it has traded under, links to its filings lists, and the forms, fiscal years and quarters on file. 8 credits, also when no company matches. | | `list` | Every company covered, 100 per page; jurisdiction filters by market. 30 credits per page. | Results stop at your plan's coverage. On Pro plans and above, search and list also give each company's industry classification. ### Parameters | Parameter | Type | Actions | Description | |---|---|---|---| | `query` | string | `search` | Name, ticker or registrant id to search for (1-64 characters); English names only. | | `jurisdiction` | string | `search`, `list` | Market: "US", "KR", "JP", "EU", "CN", or "all" (default: every market your plan covers). | | `ticker` | string | `lookup` | Ticker, e.g. "AAPL", "000100", "1332", "VIRI_F", "600519_CN"; any symbol the company has traded under. | | `cik` | string | `lookup` | SEC CIK, digits, e.g. "320193" (companies filing with the SEC). | | `dart_corp_code` | string | `lookup` | Korean DART corp code, 8 digits, e.g. "00126380". | | `edinet_code` | string | `lookup` | Japanese EDINET code, e.g. "E02778". | | `lei` | string | `lookup` | Legal Entity Identifier, 20 characters (European filers). | | `uscc` | string | `lookup` | Unified Social Credit Code, 18 characters (China A-share companies). | | `page` | integer | `list` | Page number, from 1; the response's next_page gives the next one. | | `page_size` | integer | `list` | Companies per page, 1-100 (default 100). | | `detail` | string | `list` | Response detail: "full" (default) returns the most detail available; "light" leaves out the bulkiest fields, such as breakdown lists; "minimal" returns the values with only what defines them. All three are charged the same. One of `full`, `light`, `minimal`. | ### Examples ```json {"action": "search", "query": "apple"} ``` ```json {"action": "lookup", "ticker": "AAPL"} ``` ```json {"action": "list", "jurisdiction": "US", "page": 1} ``` ## akkru_filings The financial reports (10-K, 10-Q, 20-F, 40-F and their Korean, Japanese, Chinese and European equivalents) on file for a company. ### Actions | Action | What it does | |---|---| | `list` | One company's filings for one fiscal year, with each filing's id, form, quarter, registrant, fact count, whether it has an Excel file (has_excel), and a note when an amendment was merged in. 10 credits. | | `excel` | A download URL for one filing's Excel file, valid for one hour. 300 credits. | Older years and some markets depend on your plan. ### Parameters | Parameter | Type | Actions | Description | |---|---|---|---| | `filing_id` | integer | `excel` | Filing id from akkru_filings action "list". Name the filing with filing_id, or with ticker and fiscal_year, not both. | | `ticker` | string | `list`, `excel` | Company ticker, e.g. "AAPL" (US), "000100" (Korea), "1332" (Japan), "VIRI_F" (Europe), "600519_CN" (China A-share); any symbol the company has traded under. | | `fiscal_year` | integer | `list`, `excel` | Fiscal year of the filing (1990-2100). | | `form_type` | string | `list`, `excel` | Form: "10-K", "10-Q", "20-F" or "40-F" (Korean, Japanese, Chinese and European filings use "10-K" for annual and "10-Q" for interim reports). list: filters the list, omit for every form; excel: defaults to "10-K". | | `quarter` | string | `list`, `excel` | "FY", "Q1", "Q2", "Q3" or "Q4". list: filters the list, omit for every quarter; excel: needed only when the fiscal year has several filings of the form; the error then lists the quarters on file. | | `detail` | string | `list` | Response detail: "full" (default) returns the most detail available; "light" leaves out the bulkiest fields, such as breakdown lists; "minimal" returns the values with only what defines them. All three are charged the same. One of `full`, `light`, `minimal`. | ### Examples ```json {"action": "list", "ticker": "AAPL", "fiscal_year": 2025} ``` ```json {"action": "excel", "ticker": "AAPL", "fiscal_year": 2025} ``` ## akkru_statements Whole statements and notes of one filing, as filed: every row with its value, period, unit and source. ### Actions | Action | What it does | |---|---| | `get` | One statement or note, named by exactly one of statement_type, role_label or block_index. statement_type takes the five main statements by name, for US filings. role_label takes any statement or note by the name the filer gave it, in any filing. block_index takes the position that list shows. 28 credits; 48 when role_label is matched to a differently worded name. | | `list` | Every statement and note block of the filing with its block_index, statement_type and role_label. 10 credits. | Name the filing with filing_id, or with ticker and fiscal_year. ### Parameters | Parameter | Type | Actions | Description | |---|---|---|---| | `filing_id` | integer | `get`, `list` | Filing id from akkru_filings action "list". Name the filing with filing_id, or with ticker and fiscal_year, not both. | | `ticker` | string | `get`, `list` | Company ticker, e.g. "AAPL" (US), "000100" (Korea), "1332" (Japan), "VIRI_F" (Europe), "600519_CN" (China A-share); any symbol the company has traded under. | | `fiscal_year` | integer | `get`, `list` | Fiscal year of the filing (1990-2100). | | `form_type` | string | `get`, `list` | Form, default "10-K": "10-K" or "10-Q" for US filers, "20-F" or "40-F" for foreign issuers filing with the SEC. Korean, Japanese, Chinese and European filings use "10-K" for annual and "10-Q" for interim reports. | | `quarter` | string | `get`, `list` | "FY", "Q1", "Q2", "Q3" or "Q4". Needed only when the fiscal year has several filings of the form; the error then lists the quarters on file. | | `statement_type` | string | `get` | "Income Statement", "Balance Sheet", "Cash Flow Statement", "Comprehensive Income" or "Stockholders Equity" (US filings only). Give one of statement_type, role_label, block_index. | | `role_label` | string | `get` | The statement or note name as the filer gave it, e.g. "CONSOLIDATED STATEMENTS OF OPERATIONS" or "Revenue Recognition"; a name that differs from the filing's is matched for 20 more credits. Give one of statement_type, role_label, block_index. | | `block_index` | integer | `get` | The block's position as list returns it. Give one of statement_type, role_label, block_index. | | `detail` | string | `get` | Response detail: "full" (default) returns the most detail available; "light" leaves out the bulkiest fields, such as breakdown lists; "minimal" returns the values with only what defines them. All three are charged the same. One of `full`, `light`, `minimal`. | ### Examples ```json {"action": "get", "ticker": "AAPL", "fiscal_year": 2025, "statement_type": "Balance Sheet"} ``` ```json {"action": "list", "ticker": "AAPL", "fiscal_year": 2025} ``` ## akkru_facts Single reported numbers (and text facts) from filings, each with its period, unit, dimensions and a link to its place in the filing. ### Actions | Action | What it does | |---|---| | `get` | By name, give line_items (e.g. ["revenue", "net income"]); by id, give fact_ids. For one filing name it with filing_id, or with ticker and fiscal_year; to compare years or companies, give filings instead, one row per filing (by id, each row carries its own fact_ids). A name is matched to the filing's concepts in four levels, L0 to L3, costing 10, 20, 30 or 50 credits per name and per filing; _resolution_level says which level matched. Ids cost 10 credits per 5 ids. A name matches consolidated totals and can return several facts, best first. | | `breakdown` | Split a consolidated total into its segments, products or regions; give line_item (a name) or fact_id. By id: 10 credits per 5 facts, counting the total and its direct slices; by name: the name's level price plus 10 credits per 5 slices returned. | ### Parameters | Parameter | Type | Actions | Description | |---|---|---|---| | `filing_id` | integer | `get`, `breakdown` | Filing id from akkru_filings action "list". Name the filing with filing_id, or with ticker and fiscal_year, not both. | | `ticker` | string | `get`, `breakdown` | Company ticker, e.g. "AAPL" (US), "000100" (Korea), "1332" (Japan), "VIRI_F" (Europe), "600519_CN" (China A-share); any symbol the company has traded under. | | `fiscal_year` | integer | `get`, `breakdown` | Fiscal year of the filing (1990-2100). | | `form_type` | string | `get`, `breakdown` | Form, default "10-K": "10-K" or "10-Q" for US filers, "20-F" or "40-F" for foreign issuers filing with the SEC. Korean, Japanese, Chinese and European filings use "10-K" for annual and "10-Q" for interim reports. | | `quarter` | string | `get`, `breakdown` | "FY", "Q1", "Q2", "Q3" or "Q4". Needed only when the fiscal year has several filings of the form; the error then lists the quarters on file. | | `line_items` | array of string | `get` | Line-item names, e.g. ["revenue", "net income"] (1-50). A name asked twice is charged once. | | `fact_ids` | array of string | `get` | Fact ids from an earlier result (1-500), charged 10 credits per 5. | | `filings` | array of object | `get` | Filings to compare (1-25), each {"filing_id": ...} or {"ticker": ..., "fiscal_year": ..., "form_type"?, "quarter"?}; with fact_ids in each row to compare by id. Filings that cannot be returned are listed in failed_filings with their error code and are not charged. | | `line_item` | string | `breakdown` | The line-item name to split, e.g. "revenue". | | `fact_id` | string | `breakdown` | The id of the consolidated fact to split. | | `recursive` | boolean | `breakdown` | true (default): every level of the split; false: only the first level. | | `detail` | string | `get`, `breakdown` | Response detail: "full" (default) returns the most detail available; "light" leaves out the bulkiest fields, such as breakdown lists; "minimal" returns the values with only what defines them. All three are charged the same. One of `full`, `light`, `minimal`. | ### Examples ```json {"action": "get", "ticker": "AAPL", "fiscal_year": 2025, "line_items": ["revenue", "net income"]} ``` ```json {"action": "get", "filings": [{"ticker": "AAPL", "fiscal_year": 2025}, {"ticker": "MSFT", "fiscal_year": 2025}], "line_items": ["revenue"]} ``` ```json {"action": "breakdown", "ticker": "AAPL", "fiscal_year": 2025, "line_item": "revenue"} ``` ## akkru_metrics 82 metrics computed from each filing (margins, growth, leverage, efficiency, cash flow, valuation), each with its formula and the facts it used. US companies only. Starter plan or higher; formula_override needs Pro. ### Actions | Action | What it does | |---|---| | `get` | One filing's metrics. Name the filing with metric_group_id, filing_id, or ticker and fiscal_year. All metrics by default; metric_names for chosen ones; category for one of six groups. Price-based ratios come at the filing-date price, and also at current_price when you give it; filing_date_price_only skips the current-price block. 158 credits. | | `history` | The same metrics over many periods for one ticker, newest or oldest first, up to 5 periods per page. 55 credits plus 148 per period on the page. | | `list` | A company's filings that have metrics, with their metric_group_id; give fiscal_year or as_of_date. 10 credits. | | `catalog` | Every metric name with its unit, plus the operators and options search takes. Free. | | `search` | Screen every covered company with conditions on metrics (where). Pro plan or higher; 89-1,825 credits depending on the conditions; the response shows the price. | Metric names are catalog ids such as gross_margin; a wrong name returns the full list of names. ### Parameters | Parameter | Type | Actions | Description | |---|---|---|---| | `metric_group_id` | integer | `get` | Metric set id from action "list". One of metric_group_id, filing_id, or ticker with fiscal_year names the filing. | | `filing_id` | integer | `get` | Filing id from akkru_filings action "list". One of metric_group_id, filing_id, or ticker with fiscal_year names the filing. | | `ticker` | string | `get`, `history`, `list` | Company ticker, e.g. "AAPL" (US), "000100" (Korea), "1332" (Japan), "VIRI_F" (Europe), "600519_CN" (China A-share); any symbol the company has traded under. | | `form_type` | string | `get` | Form, default "10-K": "10-K" or "10-Q" for US filers, "20-F" or "40-F" for foreign issuers filing with the SEC. Korean, Japanese, Chinese and European filings use "10-K" for annual and "10-Q" for interim reports. | | `fiscal_year` | integer | `get`, `list` | Fiscal year of the filing (1990-2100). | | `quarter` | string | `get`, `list` | "FY", "Q1", "Q2", "Q3" or "Q4". list: filters the list, omit for every quarter; get: needed only when the fiscal year has several filings of the form; the error then lists the quarters on file. | | `form_types` | array of string | `list` | Forms to include, e.g. ["10-K", "10-Q"] (up to 8). Default: every form. | | `metric_names` | array of string | `get`, `history` | Metric ids, e.g. ["gross_margin", "pe_ratio"]. get: only these; history: only these (default all). The names are in action "catalog". | | `category` | string | `get` | One group of metrics: profitability, growth, financial_health, efficiency, cash_flow or valuation. | | `filing_date_price_only` | boolean | `get` | true: price-based ratios at the filing-date price only, without the current-price block; with all metrics or with category valuation. | | `current_price` | number | `get` | Current share price in USD; price-based ratios are then also computed at it (above 0, at most 10,000,000, at most 4 decimals). Without it the current-price block says it is missing. | | `current_fx_rate` | number | `get` | Fallback exchange rate, used only when the current rate for a foreign-currency filing is briefly unavailable (above 0, at most 1,000,000, at most 6 decimals). | | `accept_suggested_formula` | boolean | `get`, `history` | true: compute the metrics that need a formula choice with the suggested formula. | | `formula_override` | object | `get`, `history` | Your own formula per metric id, e.g. {"interest_coverage": {"concepts": ["OperatingIncomeLoss", "InterestExpense"], "operators": ["/"]}}. Pro plan or higher. | | `as_of_date` | string | `get`, `history`, `list`, `search` | Date "YYYY-MM-DD": only what had been filed by that day counts. Default: no cutoff. | | `period_type` | string | `history` | "quarterly" (default) or "annual". annual covers 10-K, 20-F and 40-F; quarterly covers 10-Q. | | `start_period_start` | string | `history` | Earliest period start, "YYYY-MM-DD". | | `end_period_end` | string | `history` | Latest period end, "YYYY-MM-DD". | | `sort` | string | `history` | "period_end_asc" (default) or "period_end_desc". | | `page` | integer | `history`, `search` | Page number, from 1; the response's next_page gives the next one. | | `page_size` | integer | `history`, `search` | history: periods per page, 1-5 (default 3); search: rows per page, 1-100 (default 50), with page times page_size at most 500. | | `where` | object | `search` | Conditions and sort: {"filter": , "sort_by"?: , "sort_order"?: "asc" or "desc"}. A tree is a leaf {"metric": , "op": ">", ">=", "<", "<=" or "between", "value": } with at most one of "for_latest", "for_consecutive", "for_at_least": N; or {"and": [...]}, {"or": [...]}, {"not": }. 1-10 leaves, nesting depth at most 4. | | `lookback` | integer | `search` | How many filings back the conditions look (1-120, default 1); cut to your plan's history window. | | `include_quarterly` | boolean | `search` | true: quarterly filings count too; default annual only. | | `tickers` | array of string | `search` | Only these companies (up to 100); any symbol a company has traded under. Default: every company. | | `exclude_tickers` | array of string | `search` | Leave these companies out (up to 100). | | `usd_only` | boolean | `search` | true: only rows whose values are in USD. | | `sectors` | array of string | `search` | Only companies in these sectors (names from akkru_metrics action "catalog"). Pro plan or higher. | | `include_metrics_using_filing_date_price` | boolean | `search` | false: the 13 price-based valuation ratios cannot be used in conditions or sorting; default true. | | `exclude_derivations` | array of string | `search` | Conditions ignore metric values derived these ways, e.g. "composite" (the kinds are in action "catalog"). | | `include_metrics` | array of string | `search` | Extra metric ids to return next to the ones in the conditions (up to 10). | | `group_by_ticker` | boolean | `search` | true (default): one row per company; false: one row per filing. | | `detail` | string | `get`, `history`, `search` | Response detail: "full" (default) returns the most detail available; "light" leaves out the bulkiest fields, such as breakdown lists; "minimal" returns the values with only what defines them. All three are charged the same. One of `full`, `light`, `minimal`. | ### Examples ```json {"action": "get", "ticker": "AAPL", "fiscal_year": 2025, "category": "profitability"} ``` ```json {"action": "history", "ticker": "AAPL", "period_type": "annual", "metric_names": ["gross_margin"], "page_size": 5} ``` ```json {"action": "list", "ticker": "AAPL", "fiscal_year": 2025} ``` ```json {"action": "catalog"} ``` ```json {"action": "search", "where": {"filter": {"metric": "return_on_equity", "op": ">", "value": 0.2, "for_latest": 3}}, "lookback": 3, "page_size": 10} ``` ## akkru_insider_transactions Trades insiders report on SEC Form 4 (and Form 5), nested filing then transactions, with the insiders, footnotes and links to the filing. A trade's direction is its acquired_disposed_code (A or D). Rows failing a consistency check carry data_quality_flags and are left out unless include_anomalies is true; the count left out is reported. ### Actions | Action | What it does | |---|---| | `list` | One company's (ticker or cik) and/or one insider's (insider_cik) filings. 30 credits per page. | | `stats` | Totals over a date window for one company and/or insider, with the ids of every transaction counted. 40 credits plus 5 per 1,000 transactions counted. | | `get` | Transactions by id (from stats), up to 100. 10 credits per 5 ids. | | `insiders` | Everyone who filed a Form 4 for one company, one row per CIK, with roles, latest title and filing counts; gives the insider_cik the other actions take. 30 credits. | | `types` | The transaction codes with their official names. Free. | | `tickers` | The companies with Form 4 data, 500 per page. 30 credits per page. | | `search` | Screen every company's trades with trade_filters and aggregate_filters. Pro plan or higher; 65-920 credits. | A company outside your plan's coverage returns 403 and the call is still charged. ### Parameters | Parameter | Type | Actions | Description | |---|---|---|---| | `ticker` | string | `list`, `stats`, `insiders` | Company ticker, e.g. "AAPL" (US), "000100" (Korea), "1332" (Japan), "VIRI_F" (Europe), "600519_CN" (China A-share); any symbol the company has traded under. | | `cik` | string | `list`, `stats`, `insiders` | Company SEC CIK, digits, e.g. "320193"; any CIK the company has filed under. Give ticker or cik, not both. | | `insider_cik` | string | `list`, `stats` | Insider SEC CIK, digits (from action "insiders"). | | `transaction_code` | array of string | `list`, `stats` | SEC transaction codes to keep, e.g. ["P", "S"] (up to 20; action "types" lists them). Unknown codes are dropped and reported in _warnings. | | `transaction_form_type` | string | `list` | Only "4" or only "5". | | `relationship` | array of string | `list`, `stats`, `insiders` | list, stats: the role on the filing, any of "is_director", "is_officer", "is_ten_percent_owner", "is_other". insiders: a role ever reported, any of "ever_director", "ever_officer", "ever_ten_percent_owner", "ever_other". | | `include_unresolved_amendments` | boolean | `list`, `stats` | true: include amendments that could not be matched to their original filing. | | `exclude_likely_merged` | boolean | `list`, `stats` | true: leave out filings whose amendment match is only probable. | | `include_anomalies` | boolean | `list`, `stats` | true: include rows that fail a consistency check (left out by default). | | `start_date` | string | `stats`, `search` | Window start, transaction date "YYYY-MM-DD". | | `as_of_date` | string | `stats`, `search` | Window end, transaction date "YYYY-MM-DD" (not in the future); filings submitted after it are left out too. | | `method` | string | `stats` | "ad" (default): totals by acquired_disposed_code; "ps": P as a buy and S as a sell, only those two codes. One of `ad`, `ps`. | | `is_derivative` | boolean | `stats` | true: derivative rows only; false: non-derivative rows only. | | `ids_page` | integer | `stats` | Page of transaction_ids in the stats response (default 1). | | `ids_page_size` | integer | `stats` | transaction_ids per page, 1-1,000 (default 200). | | `transaction_ids` | array of integer | `get` | Transaction ids from action "stats" (1-100). | | `tickers` | array of string | `search` | Only these companies (up to 100); any symbol a company has traded under. Default: every company. | | `exclude_tickers` | array of string | `search` | Leave these companies out (up to 100). | | `sectors` | array of string | `search` | Only companies in these sectors (names from akkru_metrics action "catalog"). Pro plan or higher. | | `trade_filters` | object | `search` | Trade-level filters: transaction_code, relationship, is_derivative, principal_amount_not_shares, include_anomalies, exclude_likely_merged, include_unresolved_amendments, and up to 8 conditions {field, op, value} on transaction_value, price_per_share, shares, own_pct_change, split_adjusted_shares or split_adjusted_price. | | `aggregate_filters` | array of object | `search` | Company-level conditions (up to 8) {metric, op, value} on value_acquired, value_disposed, net_value, shares_acquired, shares_disposed, net_shares, txn_count, txn_count_acquired, txn_count_disposed, max_txn_value_acquired, max_txn_value_disposed or distinct_insiders. Operators for both: >, >=, <, <=, between ([low, high]). | | `group_by_ticker` | boolean | `search` | true (default): one row per company; false: one row per transaction. | | `sort_by` | string | `search` | Grouped: ticker or txn_count. One row per transaction: transaction_date, filing_date, transaction_value, shares, price_per_share, own_pct_change, split_adjusted_shares or split_adjusted_price. | | `sort_order` | string | `search` | "desc" (default) or "asc". | | `page` | integer | `list`, `get`, `tickers`, `search` | Page number, from 1; the response's next_page gives the next one. | | `page_size` | integer | `list`, `get`, `tickers`, `search` | list, get: filings per page; search: rows per page, with page times page_size at most 500; tickers: companies per page, up to 500. | | `detail` | string | `list`, `stats`, `get`, `search` | Response detail: "full" (default) returns the most detail available; "light" leaves out the bulkiest fields, such as breakdown lists; "minimal" returns the values with only what defines them. All three are charged the same. One of `full`, `light`, `minimal`. | ### Examples ```json {"action": "list", "ticker": "AAPL", "transaction_code": ["P", "S"], "page_size": 5} ``` ```json {"action": "stats", "ticker": "AAPL", "start_date": "2025-01-01"} ``` ```json {"action": "get", "transaction_ids": [123456, 123457]} ``` ```json {"action": "insiders", "ticker": "AAPL", "relationship": ["ever_officer"]} ``` ```json {"action": "types"} ``` ```json {"action": "tickers", "page": 1} ``` ```json {"action": "search", "start_date": "2026-04-01", "trade_filters": {"transaction_code": ["P"]}, "page_size": 10} ``` ## akkru_initial_holdings What insiders report holding when they become insiders (SEC Form 3), nested filing then holdings; no_securities_owned true means the filer reported holding nothing. Rows failing a consistency check carry data_quality_flags and are left out unless include_anomalies is true. ### Actions | Action | What it does | |---|---| | `list` | One company's (ticker or cik) and/or one insider's (insider_cik) Form 3 filings. 30 credits per page. | | `stats` | Totals over a filing-date window, with the ids of every holding counted. 40 credits plus 5 per 1,000 holdings counted. shares_owned_total and underlying_shares_total are in different units. | | `get` | Holdings by id (from stats), up to 100. 10 credits per 5 ids. | | `insiders` | Everyone who filed a Form 3 for one company, one row per CIK. 30 credits. | | `tickers` | The companies with Form 3 data, 500 per page. 30 credits per page. | | `search` | Screen every company's holdings with holding_filters and aggregate_filters. Pro plan or higher; 65-920 credits. | A company outside your plan's coverage returns 403 and the call is still charged. ### Parameters | Parameter | Type | Actions | Description | |---|---|---|---| | `ticker` | string | `list`, `stats`, `insiders` | Company ticker, e.g. "AAPL" (US), "000100" (Korea), "1332" (Japan), "VIRI_F" (Europe), "600519_CN" (China A-share); any symbol the company has traded under. | | `cik` | string | `list`, `stats`, `insiders` | Company SEC CIK, digits, e.g. "320193"; any CIK the company has filed under. Give ticker or cik, not both. | | `insider_cik` | string | `list`, `stats` | Insider SEC CIK, digits (from action "insiders"). | | `relationship` | array of string | `list`, `stats`, `insiders` | list, stats: the role on the filing, any of "is_director", "is_officer", "is_ten_percent_owner", "is_other". insiders: a role ever reported, any of "ever_director", "ever_officer", "ever_ten_percent_owner", "ever_other". | | `no_securities_owned` | boolean | `list` | true: only filings that report holding nothing; false: only filings with holdings; default both. | | `include_unresolved_amendments` | boolean | `list`, `stats` | true: include amendments that could not be matched to their original filing. | | `exclude_likely_merged` | boolean | `list`, `stats` | true: leave out filings whose amendment match is only probable. | | `include_anomalies` | boolean | `list`, `stats` | true: include rows that fail a consistency check (left out by default). | | `start_date` | string | `stats`, `search` | Window start, filing date "YYYY-MM-DD". | | `as_of_date` | string | `stats`, `search` | Window end, filing date "YYYY-MM-DD" (not in the future). | | `is_derivative` | boolean | `stats` | true: derivative rows only; false: non-derivative rows only. | | `ids_page` | integer | `stats` | Page of holding_ids in the stats response (default 1). | | `ids_page_size` | integer | `stats` | holding_ids per page, 1-1,000 (default 200). | | `holding_ids` | array of integer | `get` | Holding ids from action "stats" (1-100). | | `tickers` | array of string | `search` | Only these companies (up to 100); any symbol a company has traded under. Default: every company. | | `exclude_tickers` | array of string | `search` | Leave these companies out (up to 100). | | `sectors` | array of string | `search` | Only companies in these sectors (names from akkru_metrics action "catalog"). Pro plan or higher. | | `holding_filters` | object | `search` | Holding-level filters: relationship, is_derivative, direct_or_indirect (D or I), include_anomalies, exclude_likely_merged, include_unresolved_amendments, and up to 8 conditions {field, op, value} on shares_owned, split_adjusted_shares_owned, underlying_security_shares, split_adjusted_underlying_security_shares or conversion_or_exercise_price. | | `aggregate_filters` | array of object | `search` | Company-level conditions (up to 8) {metric, op, value} on filing_count, no_securities_filing_count, distinct_insiders, holdings_count or shares_owned_total. Operators for both: >, >=, <, <=, between ([low, high]). | | `group_by_ticker` | boolean | `search` | true (default): one row per company; false: one row per holding. | | `sort_by` | string | `search` | Grouped: ticker, holdings_count or shares_owned_total. One row per holding: filing_date, shares_owned, split_adjusted_shares_owned, underlying_security_shares or conversion_or_exercise_price. | | `sort_order` | string | `search` | "desc" (default) or "asc". | | `page` | integer | `list`, `get`, `tickers`, `search` | Page number, from 1; the response's next_page gives the next one. | | `page_size` | integer | `list`, `get`, `tickers`, `search` | list, get: filings per page; search: rows per page, with page times page_size at most 500; tickers: companies per page, up to 500. | | `detail` | string | `list`, `stats`, `get`, `search` | Response detail: "full" (default) returns the most detail available; "light" leaves out the bulkiest fields, such as breakdown lists; "minimal" returns the values with only what defines them. All three are charged the same. One of `full`, `light`, `minimal`. | ### Examples ```json {"action": "list", "ticker": "TSLA", "page_size": 5} ``` ```json {"action": "stats", "ticker": "TSLA", "start_date": "2020-01-01"} ``` ```json {"action": "get", "holding_ids": [1234, 1235]} ``` ```json {"action": "insiders", "ticker": "TSLA"} ``` ```json {"action": "tickers", "page": 1} ``` ```json {"action": "search", "tickers": ["TSLA"], "holding_filters": {"is_derivative": false}, "page_size": 10} ``` ## akkru_institutional_holdings What institutional managers report holding each quarter on SEC Form 13F, by manager (filer CIK) and quarter. Links open the filing's EDGAR index page. ### Actions | Action | What it does | |---|---| | `managers` | Managers whose latest name matches query, or whose CIK is query when it is all digits; up to 8, largest latest portfolio first, with their latest quarter. 10 credits. | | `history` | One manager's quarters (cik, or the exact name) with each quarter's headline numbers and its quarter label (e.g. "2026Q2", for portfolio). 30 credits. | | `portfolio` | One manager's holdings for one quarter: positions, derivatives and positions closed out (exited), under a header with the quarter's numbers and its amendment record. 30 credits per page. | | `holders` | Who holds one security (cusip or ticker), row by row, or one row per quarter with group_by_quarter. 30 credits per page; 40 grouped. | | `search` | Screen every manager-quarter by its numbers (conditions), by quarter end dates and flags. Pro plan or higher; 160-720 credits. | An unknown manager, quarter or security returns 404 and is still charged. ### Parameters | Parameter | Type | Actions | Description | |---|---|---|---| | `query` | string | `managers` | Manager name (1-64 characters; under 3 characters matches the start of the name) or CIK digits. | | `cik` | string | `history`, `portfolio` | Manager (filer) CIK, digits without leading zeros (from action "managers"). Give cik or name, not both. | | `name` | string | `history`, `portfolio` | Manager name, exact apart from spaces and case; a name several managers share returns 404. | | `quarter` | string | `portfolio`, `holders` | Calendar quarter "YYYYQn", e.g. "2026Q1" (Q1 ends March 31, Q2 June 30, Q3 September 30, Q4 December 31). portfolio: required; holders: default every quarter. | | `type` | string | `portfolio`, `holders` | "positions" (stock rows), "derivatives" (option rows) or "exited" (positions closed out that quarter); default all three. | | `activity` | array of string | `portfolio`, `holders` | Any of "NEW", "ADD", "REDUCE", "HOLD", "CUSIP_CHANGE"; unknown values are dropped with a warning. Exited rows have no activity. | | `restated` | array of string | `portfolio` | Any of "added", "modified", "cancelled": rows a merged amendment changed. | | `cusip` | string | `portfolio`, `holders` | 9-character CUSIP. portfolio: only this security; holders: the security (or give ticker). | | `ticker` | string | `portfolio`, `holders` | Security ticker; any symbol the company has traded under. portfolio: only this security; holders: the security (or give cusip). | | `group_by_quarter` | boolean | `holders` | true: one row per quarter (holders, total shares, total value of stock rows), unpaged. | | `sort_by` | string | `portfolio`, `holders`, `search` | portfolio, holders: period, d_shares, ticker, issuer_norm or type (holders also shares or value); search: total_positions_value (default), positions_count, derivatives_count, total_derivatives_notional, portfolio_value_qoq_pct, top1_security_pct, top10_security_pct, est_turnover, period or filing_date. | | `sort_order` | string | `history`, `portfolio`, `holders`, `search` | "desc" (default) or "asc". | | `start_date` | string | `search` | Only quarters ending on or after this date, "YYYY-MM-DD". | | `end_date` | string | `search` | Only quarters ending on or before this date, "YYYY-MM-DD". Omit both dates for every quarter. | | `conditions` | array of object | `search` | Up to 8 {field, op, value}; op is >, >=, <, <= or between ([low, high]); field is total_positions_value, positions_count, derivatives_count, total_derivatives_notional, portfolio_value_qoq_pct, top1_security_pct, top10_security_pct, est_turnover, cover_table_value, new_count, add_count, reduce_count, hold_count, sold_out_count or filing_date ("YYYY-MM-DD"). A quarter where the field is empty never matches. | | `is_amended` | boolean | `search` | true: only quarters with merged amendments; false: only quarters without. | | `confidential` | boolean | `search` | true: only quarters with confidential holdings; false: only without. | | `is_combination_report` | boolean | `search` | true: only combination reports (the filer also reports for other managers); false: only holdings reports. | | `page` | integer | `history`, `portfolio`, `holders`, `search` | Page number, from 1; the response's next_page gives the next one. | | `page_size` | integer | `history`, `portfolio`, `holders`, `search` | Rows per page, 1-100 (default 50); search: page times page_size at most 500. | | `detail` | string | `history`, `portfolio`, `holders`, `search` | Response detail: "full" (default) returns the most detail available; "light" leaves out the bulkiest fields, such as breakdown lists; "minimal" returns the values with only what defines them. All three are charged the same. One of `full`, `light`, `minimal`. | ### Examples ```json {"action": "managers", "query": "berkshire"} ``` ```json {"action": "history", "cik": "1067983", "page_size": 8} ``` ```json {"action": "portfolio", "cik": "1067983", "quarter": "2025Q4", "type": "positions"} ``` ```json {"action": "holders", "ticker": "AAPL", "quarter": "2025Q4", "page_size": 20} ``` ```json {"action": "search", "start_date": "2025-10-01", "end_date": "2025-12-31", "conditions": [{"field": "total_positions_value", "op": ">=", "value": 100000000000}]} ``` ## akkru_events Corporate events US companies report to the SEC, one section per Item (e.g. 5.02, officer changes), each with a summary and a link to its place in the filing; amendments are merged into the filing they amend. Starter plan or higher; results stop at your plan's history window. ### Actions | Action | What it does | |---|---| | `types` | The Item codes with their official titles. Free. | | `list` | One company's (ticker or cik) event filings, newest first, with their ids, dates and Items. 10 credits per page. | | `get` | One filing by filing_id: its sections, amendment history, and on request the original text and the attachments, at no extra cost. 30 credits. | | `search` | Filings across companies by Items and filing dates, newest first, with the matching sections. Pro plan or higher; 65-280 credits per page. | list, get and search are charged even when nothing matches or the filing or company is not found. ### Parameters | Parameter | Type | Actions | Description | |---|---|---|---| | `ticker` | string | `list` | Company ticker, e.g. "AAPL" (US), "000100" (Korea), "1332" (Japan), "VIRI_F" (Europe), "600519_CN" (China A-share); any symbol the company has traded under. | | `cik` | string | `list` | Company SEC CIK, digits, e.g. "320193"; any CIK the company has filed under. Give ticker or cik, not both. | | `filing_id` | integer | `get` | Event filing id from action "list" or "search". | | `items` | array of string | `get`, `search` | Item codes, e.g. ["5.02"] (1-33; action "types" lists them). get: only these sections; search: filings with these Items. Default: every Item. | | `item_match` | string | `search` | "any" (default): a filing with at least one of items; "all": a filing with every one. One of `any`, `all`. | | `include_original_raw_text` | boolean | `get` | true: also return the filing's complete original text. | | `include_exhibits` | boolean | `get` | true: also return the filing's attachments with their text. | | `as_of_date` | string | `get`, `search` | Date "YYYY-MM-DD", not in the future. get: the filing only if it was filed by then (404 otherwise); search: only filings filed by then. | | `tickers` | array of string | `search` | Only these companies (up to 100); any symbol a company has traded under. Default: every company. | | `start_date` | string | `search` | Earliest filing date, "YYYY-MM-DD". | | `end_date` | string | `search` | Latest filing date, "YYYY-MM-DD". | | `include_unresolved_amendments` | boolean | `search` | true: include amendments that could not be matched to their original filing. | | `exclude_likely_merged` | boolean | `search` | true: leave out filings whose amendment match is only probable. | | `page` | integer | `list`, `search` | Page number, from 1; the response's next_page gives the next one. | | `page_size` | integer | `list`, `search` | list: filings per page, 1-100 (default 50); search: filings per page, 1-10 (default 5), with page times page_size at most 500. | | `detail` | string | `list`, `get`, `search` | Response detail: "full" (default) returns the most detail available; "light" leaves out the bulkiest fields, such as breakdown lists; "minimal" returns the values with only what defines them. All three are charged the same. One of `full`, `light`, `minimal`. | ### Examples ```json {"action": "types"} ``` ```json {"action": "list", "ticker": "CNP", "page_size": 5} ``` ```json {"action": "get", "filing_id": 4688, "items": ["5.02"]} ``` ```json {"action": "search", "tickers": ["CNP"], "items": ["5.02"], "start_date": "2023-01-01", "end_date": "2023-01-31"} ``` ## akkru_account Your account. ### Actions | Action | What it does | |---|---| | `balance` | The credits left on your account. Free. | ### Examples ```json {"action": "balance"} ``` # API Basics ## Authentication All requests to **`/data/*`**, **`/metric/*`**, **`/screener/*`**, **`/ownership/*`**, **`/events/*`** and **`GET /billing/balance`** require: | Header | Value | |--------|--------| | `X-API-Key` | Your API key (create and manage keys in the product dashboard after sign-in). | For `POST` requests with a JSON body, also send: | Header | Value | |--------|--------| | `Content-Type` | `application/json` | ## Errors ### Success and error payloads Structured errors return JSON of the form: ```json { "detail": { "error_code": "SOME_CODE", "message": "Human-readable explanation." } } ``` **Validation errors** (`error_code: "VALIDATION_ERROR"`) additionally include a `fields` array describing each rejected input. Each entry has `type` (a stable code such as `missing`, `extra_forbidden`, `int_parsing`, `string_too_long`), `loc` (path to the field), `msg` (human text), and `input` (the value that failed). Use **`detail.message`** for a single-line summary and **`detail.fields`** if you need per-field structured detail. Authentication failures use the same object form: `401 AUTH_API_KEY_MISSING` (no `X-API-Key`), `403 AUTH_API_KEY_INVALID` (unknown or inactive key), `403 AUTH_USER_INACTIVE`, `403 AUTH_EMAIL_NOT_VERIFIED`. Every 4xx and 5xx response uses the object form above. An error returned after credits were debited also carries **`credits_used`**, the credits that request used. **Plan-tier responses.** A request may be rejected because the caller's plan does not include the requested endpoint or option. These return **`403`** with one of `PLAN_TIER_INSUFFICIENT`, `PLAN_TIER_INSUFFICIENT_HISTORY`, `PLAN_TIER_INSUFFICIENT_FORMULA_OVERRIDE`, or `PLAN_TIER_INSUFFICIENT_COVERAGE`. The `detail` body also carries `required_tier` (the lowest plan that would accept the request) and `current_tier` (the caller's current plan). See **[API key, account, and plan errors](#api-key-account-and-plan-errors)**. ### API key, account, and plan errors | HTTP | When | |------|------| | 401 | `AUTH_API_KEY_MISSING` — no `X-API-Key` header. | | 403 | `AUTH_API_KEY_INVALID` — unknown or inactive key. | | 403 | `AUTH_USER_INACTIVE` — the key's account is inactive or deleted. | | 403 | `AUTH_EMAIL_NOT_VERIFIED` — the key's account has not verified its email. | | 403 | `AUTH_API_KEY_EXPIRED` — key past its expiry. | | 403 | `AUTH_API_KEY_INACTIVE` — key disabled by inactivity policy. | | 403 | `AUTH_MCP_CLIENT_REVOKED` — the MCP connection behind this access token was disconnected. | | 403 | `PLAN_TIER_INSUFFICIENT` — the endpoint, or a filing, metric group, transaction or holding requested by id, is not available on the caller's current plan. | | 403 | `PLAN_TIER_INSUFFICIENT_HISTORY` — a request names one filing by `ticker` and a `fiscal_year` before the caller's plan's history window. The body carries `filing_fiscal_year` and `earliest_allowed_fiscal_year`. | | 403 | `PLAN_TIER_INSUFFICIENT_FORMULA_OVERRIDE` — the `formula_override` request field is not available on the caller's current plan. Omit `formula_override` to proceed, or upgrade. | | 403 | `PLAN_TIER_INSUFFICIENT_COVERAGE` — the company named by `ticker` or `cik`, or the requested `jurisdiction`, is outside the caller's plan's coverage scope. Body also carries `coverage_band`. | Every `PLAN_TIER_*` response includes `required_tier` and `current_tier` strings (lowercase plan names) in the `detail` body so clients can prompt for an upgrade without parsing the message text. ### Request limits (validation) These caps apply at validation time (**422** when exceeded): | Limit | Value | |-------|--------| | Line items per request (`/data/line-items`, `/data/compare/line-items`) | 50 | | Fact ids per request (`/data/facts`) | 500 | | Fact ids per row (`/data/compare/facts`) | 500 | | Total fact ids (`/data/compare/facts`) | 2500 | | Filings per compare request | 25 | | Metric names (`/metric/items`, optional `/metric/historical`) | 100 | | Concepts per metric in `formula_override` (`/metric/all`, `/metric/items`, `/metric/historical`) | 50 | | Form types (`/metric/filings`) | 8 | | Historical page size | 5 | | Corporate event Item codes (`/events/filing`, `/screener/events`) | 33 | | Corporate event screening tickers | 100 | | Corporate event screening page size | 10 (default 5) | | Corporate event screening cumulative results | page × page_size ≤ 500 | | Screening cumulative results (`/screener/*`) | page × page_size ≤ 500 | | Ids per request (`/ownership/transaction-ids`, `/ownership/initial-holding-ids`) | 100 | | Page number (`page`, `ids_page`) | 1,000,000 | | Search `query` (`/data/company/search`, `/ownership/institutional-holdings/managers`) | 64 characters | *AkkruData — API user guide.* ## Credits & Rate Limits ### Credits Credits are deducted from the account tied to your API key. Amounts and timing are listed under each endpoint and in **[Credit summary](#credit-summary)**. **`402 Payment Required`** indicates insufficient credits for that operation. ### Credit summary Credit charges for **`/data`**, **`/metric`**, **`/screener`**, **`/ownership`**, and **`/events`** are as follows. | Endpoint | Credits | |----------|---------| | `POST /data/filings` | **10** per successful debit. Debited **even if** the returned `filings` list is empty. | | `POST /data/company` | **8** per successful debit. Debited **even if** `DATA_COMPANY_NOT_FOUND` is returned. | | `GET /data/company/list` | **30** per page. | | `POST /data/company/search` | **10** per call. A blank `query` returns no companies and is not charged. | | `POST /data/line-items` | Sum over requested line items: tier **L0=10, L1=20, L2=30, L3=50** per line item. If your balance is less than the full sum, the rest of your balance is charged. | | `POST /data/facts` | **ceil(n / 5) × 10** where **n** is the number of **deduplicated** fact ids. | | `POST /data/statement` | **28** per debit, debited **even if** the filing is missing or nothing matches. role_label mode is tiered **28 / 48**: the extra **20** of the higher (48-credit) tier is capped at your remaining balance. | | `POST /data/filing-statements` | **10** per successful debit. Debited **even if** the filing is missing. | | `POST /data/income-statement` | **28** per successful debit. Debited **even if** the filing is missing or has no such statement. | | `POST /data/comprehensive-income` | **28** per successful debit. Debited **even if** the filing is missing or has no such statement. | | `POST /data/balance-sheet` | **28** per successful debit. Debited **even if** the filing is missing or has no such statement. | | `POST /data/cash-flow-statement` | **28** per successful debit. Debited **even if** the filing is missing or has no such statement. | | `POST /data/equity-statement` | **28** per successful debit. Debited **even if** the filing is missing or has no such statement. | | `POST /data/facts/dimensional-breakdown` | **ceil((1 + N) / 5) × 10** where **N** is the number of the fact's direct dimensional children. **10 credits** are debited on `DATA_FACT_NOT_FOUND`. | | `POST /data/line-items/dimensional-breakdown` | Tier credit for `line_item` (**L0=10 … L3=50**) + **ceil(N_total / 5) × 10** for returned slice facts. Partial billing applies. | | `POST /data/compare/line-items` | For each line item, **(tier credits) × (number of filings compared)**. Rows listed in `failed_filings` are not charged. Same partial charging as **`POST /data/line-items`** when your balance is below the full price. | | `POST /data/compare/facts` | **ceil(total_deduplicated_ids / 5) × 10** across the compared filing rows. Rows listed in `failed_filings` are not charged. | | `POST /data/filings/excel` | **300**. Debited **even if** `DATA_EXCEL_OBJECT_NOT_IN_STORAGE` is returned. | | `POST /metric/filings` | **10** | | `POST /metric/all` | **158** | | `POST /metric/all/filing-date` | **158** | | `POST /metric/items` | **158** | | `POST /metric/profitability` | **158** | | `POST /metric/growth` | **158** | | `POST /metric/financial-health` | **158** | | `POST /metric/efficiency` | **158** | | `POST /metric/cash-flow` | **158** | | `POST /metric/valuation` | **158** | | `POST /metric/valuation/filing-date` | **158** | | `POST /metric/historical` | **55** base fee, plus **148 × (number of filing rows on the current page)**. Default page size is 3 filing rows. | | `POST /screener/metrics` | Dynamic per request: **`max(65, 425 − tickerDiscount − lookbackDiscount − quarterlyDiscount + lookbackSurcharge + filterSurcharge + temporalSurcharge + includeSurcharge)`**. Range **89–1825**. See [Credit formula (`/screener/metrics`)](#credit-formula-screenermetrics) for the formula. Debited **even if** results are empty. | | `GET /screener/metrics/filters` | **0**. | | `POST /ownership/transactions` | **30** per page. Debited **even if** `OWNERSHIP_COMPANY_NOT_FOUND` is returned. | | `POST /ownership/stats` | **40** base + **ceil(n / 1000) × 5**, where **n** is the number of participating transactions. The base is debited **even if** `OWNERSHIP_COMPANY_NOT_FOUND` is returned. | | `POST /ownership/transaction-ids` | **ceil(n / 5) × 10** where **n** is the number of **deduplicated** ids (max 100). | | `POST /screener/ownership` | Dynamic per request: **`max(65, 200 − tickerDiscount − shortWindowDiscount + fullHistorySurcharge + 40 × conditions)`**. Range **65–920**. See [Credit formula (`/screener/ownership`)](#credit-formula-screenerownership) for the formula. Debited **even if** results are empty. | | `GET /ownership/tickers` | **30** per page. | | `POST /ownership/names` | **30** per successful debit. Debited **even if** `OWNERSHIP_COMPANY_NOT_FOUND` is returned. | | `GET /ownership/transaction-types` | **0** — static catalog, no charge. | | `POST /ownership/initial-holdings` | **30** per page. Debited **even if** `OWNERSHIP_COMPANY_NOT_FOUND` is returned. | | `POST /ownership/initial-holdings/stats` | **40** base + **ceil(n / 1000) × 5**, where **n** is the number of participating holdings. The base is debited **even if** `OWNERSHIP_COMPANY_NOT_FOUND` is returned. | | `POST /ownership/initial-holding-ids` | **ceil(n / 5) × 10** where **n** is the number of **deduplicated** ids (max 100). | | `POST /screener/initial-holdings` | Dynamic per request, same formula as `POST /screener/ownership` ([Credit formula (`/screener/ownership`)](#credit-formula-screenerownership)). Range **65–920**. Debited **even if** results are empty. | | `POST /ownership/institutional-holdings/manager-history` | **30** per successful debit. Debited **even if** `OWNERSHIP_MANAGER_NOT_FOUND` is returned. | | `POST /ownership/institutional-holdings/portfolio` | **30** per page. Debited **even if** the manager or the quarter is not found. | | `POST /ownership/institutional-holdings/security` | **30** per page (flat mode); **40** flat with `group_by_quarter=true`. Debited **even if** `OWNERSHIP_SECURITY_NOT_FOUND` is returned. | | `POST /ownership/institutional-holdings/managers` | **10** per call. A blank `query` returns no managers and is not charged. | | `POST /screener/institutional-holdings` | Dynamic per request: **`max(65, 200 + 40 × conditions − narrowWindowDiscount + noWindowSurcharge)`**. Range **160–720**. See [Credit formula (`/screener/institutional-holdings`)](#credit-formula-screenerinstitutional-holdings) for the formula. Debited **even if** results are empty. | | `GET /events/types` | **0**; Starter or higher required. | | `POST /events/filings` | **10** per page, including empty results and missing companies. | | `POST /events/filing` | **30**, with or without selected Items or original text; post-charge resource errors remain charged. | | `POST /screener/events` | **65–280** per page; see [Credit formula (`/screener/events`)](#credit-formula-screenerevents). | | `GET /billing/balance` | **0** — free balance check. Returns `{"credits_balance": }` for the API key's account. Rate-limited at 30/minute. | **Metrics resolution tiers (for `/data/line-items` and `/data/compare/line-items`):** each requested label is classified into **L0–L3**, which sets that line item’s credit cost. The chosen tier is echoed on each result as **`_resolution_level`** (`"L0"` through `"L3"`). The response carries **`_correction`** when a name was matched by filing label or at L3, matched several concepts, or could not be resolved. ### Workflow budgets Indicative credit ranges for common workflows, so you can size a plan before you start. Numbers assume the L1 tier on common line-item names (`revenue`, `net income`, `operating income`, etc.). Rarer or ambiguous names land at L2–L3 and cost more; see the tier list in [Credit summary](#credit-summary). | Workflow | Endpoint pattern | Typical credits | |---|---|---| | Discover one company (identity + coverage map) | `POST /data/company` | **8** | | List all filings for one company-year | `POST /data/filings` | **10** | | Pull all three primary statements (income / balance / cash flow) for one filing | `POST /data/income-statement` + `/balance-sheet` + `/cash-flow-statement` | **84** (28 × 3) | | Pull a few specific line items from one filing (3 items × L1) | `POST /data/line-items` | **60** (3 × 20) | | Five-year trend on one metric for one company | `POST /data/line-items` × 5 filings, 1 item, L1 | **100** (5 × 20) | | Peer comparison: 5 companies × 1 metric × 1 year (L1) | `POST /data/compare/line-items` | **100** (1 × 20 × 5) | | All key metrics snapshot for one company (1 call) | `POST /metric/all` | **158** | | Full dimensional breakdown of revenue for one filing (~50 slice facts) | `POST /data/line-items/dimensional-breakdown` | **~120** (20 + 100) | | Download one filing's Excel workbook | `POST /data/filings/excel` | **300** | Reference: a **Starter** plan (20,000 credits / month) covers about **330** three-item line-item queries, **240** three-statement pulls, or **126** `/metric/all` snapshots per month — pick the mix that fits your workflow. ### Rate limiting When limits are exceeded, the API returns **`429 Too Many Requests`** with `detail.error_code` **`RATE_LIMIT_EXCEEDED`**. Limits apply per account across all API keys on that account. ### Rate limits Per-account limits (requests per minute, per route): | Method | Path | Limit | |--------|------|-------| | POST | `/data/filings` | 120 | | POST | `/data/company` | 120 | | GET | `/data/company/list` | 120 | | POST | `/data/company/search` | 120 | | POST | `/data/line-items` | 100 | | POST | `/data/facts` | 100 | | POST | `/data/statement` | 120 | | POST | `/data/filing-statements` | 120 | | POST | `/data/income-statement` | 120 | | POST | `/data/comprehensive-income` | 120 | | POST | `/data/balance-sheet` | 120 | | POST | `/data/cash-flow-statement` | 120 | | POST | `/data/equity-statement` | 120 | | POST | `/data/facts/dimensional-breakdown` | 60 | | POST | `/data/line-items/dimensional-breakdown` | 60 | | POST | `/data/compare/line-items` | 60 | | POST | `/data/compare/facts` | 60 | | POST | `/data/filings/excel` | 20 | | POST | `/metric/filings` | 100 | | POST | `/metric/all` | 60 | | POST | `/metric/all/filing-date` | 60 | | POST | `/metric/items` | 60 | | POST | `/metric/profitability` | 60 | | POST | `/metric/growth` | 60 | | POST | `/metric/financial-health` | 60 | | POST | `/metric/efficiency` | 60 | | POST | `/metric/cash-flow` | 60 | | POST | `/metric/valuation` | 60 | | POST | `/metric/valuation/filing-date` | 60 | | POST | `/metric/historical` | 60 | | POST | `/screener/metrics` | 10 | | GET | `/screener/metrics/filters` | 60 | | POST | `/screener/ownership` | 10 | | POST | `/ownership/transactions` | 120 | | POST | `/ownership/stats` | 120 | | POST | `/ownership/transaction-ids` | 120 | | GET | `/ownership/tickers` | 120 | | POST | `/ownership/names` | 120 | | GET | `/ownership/transaction-types` | 60 | | POST | `/ownership/initial-holdings` | 120 | | POST | `/ownership/initial-holdings/stats` | 120 | | POST | `/ownership/initial-holding-ids` | 120 | | POST | `/screener/initial-holdings` | 10 | | POST | `/ownership/institutional-holdings/manager-history` | 120 | | POST | `/ownership/institutional-holdings/portfolio` | 120 | | POST | `/ownership/institutional-holdings/security` | 120 | | POST | `/ownership/institutional-holdings/managers` | 120 | | POST | `/screener/institutional-holdings` | 10 | | GET | `/events/types` | 60 | | POST | `/events/filings` | 120 | | POST | `/events/filing` | 60 | | POST | `/screener/events` | 10 | | GET | `/billing/balance` | 30 | ## Coverage ### History truncation notice Each plan has a history window. List, range, and discovery endpoints return only data inside it and may attach a generic `_warnings` entry: `POST /data/filings`, `POST /data/company` (the `coverage` map), `POST /metric/filings`, `POST /metric/historical`, `POST /screener/metrics`, `POST /ownership/transactions`, `POST /ownership/stats`, `POST /ownership/names`, `POST /screener/ownership`, `POST /ownership/initial-holdings`, `POST /ownership/initial-holdings/stats`, `POST /screener/initial-holdings` (on `filing_date`), `POST /events/filings` and `POST /screener/events`. For `/screener/metrics` the `lookback` is clamped to your plan's window and billed only for that portion. A filing named by `ticker` and `fiscal_year` before the window returns **`403 PLAN_TIER_INSUFFICIENT_HISTORY`** before any credits are debited. A filing, metric group, transaction or holding requested by id outside your plan returns **`403 PLAN_TIER_INSUFFICIENT`**. [`POST /ownership/transaction-ids`](#post-ownershiptransaction-ids) and [`POST /ownership/initial-holding-ids`](#post-ownershipinitial-holding-ids) list such ids in `restricted_ids` and return that 403 only when every id found is restricted. ### Coverage scope notice Corporate event company coverage is the same across eligible paid plans. Each plan covers a subset of companies. A request naming a company by `ticker` or `cik` outside your plan's scope returns **`403 PLAN_TIER_INSUFFICIENT_COVERAGE`** with `detail.required_tier`. List, discovery, `/screener/metrics`, `/screener/ownership`, `/screener/initial-holdings`, and Form 4 / Form 3 `/ownership/*` requests that name no company are filtered to your plan's scope and attach a generic `_warnings` entry. [`POST /ownership/transaction-ids`](#post-ownershiptransaction-ids) and [`POST /ownership/initial-holding-ids`](#post-ownershipinitial-holding-ids) report out-of-scope ids in `restricted_ids`. ### Company symbols and CIKs A `ticker` may be any symbol the company has traded under; a `cik` may be any CIK it has filed under. Responses name the company by its current symbol, and grouping and counting are per company. When the input is not the company's current symbol or CIK, or the company is delisted, `_warnings` says so. ### Industry classification (Pro+) Pro-plan and higher responses attach an industry `classification` block per company, when the company has one, on `POST /data/company/search`, `GET /data/company/list`, `POST /data/compare/line-items`, `POST /data/compare/facts`, and `POST /screener/metrics` results, at no extra credits. ```json "classification": { "sectors": ["Technology"], "source": { "scheme": "US_SIC", "code": "3571", "url": "https://www.sec.gov/search-filings/standard-industrial-classification-sic-code-list" } } ``` | Field | Meaning | |---|---| | `sectors` | One or two of the 12 canonical buckets — primary first, plus an optional secondary when a code spans two. | | `source.scheme` | `US_SIC` (US, SEC SIC), `KR_KSIC` (Korea, KSIC), `JP_TSE33` (Japan, TSE 33-sector), or `EU_ICB` (Europe, ICB). | | `source.code` | The company's official industry code as filed. | | `source.url` | Official page to look that code up. | The 12 canonical buckets: **Technology, Healthcare, Finance, Consumer Discretionary, Consumer Staples, Communications, Industrials, Energy, Utilities, Materials, Real Estate, Other**. `POST /screener/metrics` ([`POST /screener/metrics`](#post-screenermetrics)), `POST /screener/ownership` ([`POST /screener/ownership`](#post-screenerownership)) and `POST /screener/initial-holdings` ([`POST /screener/initial-holdings`](#post-screenerinitial-holdings)) accept a `sectors` filter over these. ## Responses ### Response detail Endpoints that list a `detail` field accept `"full"` (default), `"light"` or `"minimal"`; all three are charged the same. - `"full"` returns everything. - `"light"` leaves out the fields listed under each endpoint. - `"minimal"` returns only the values and what identifies them; sources, links, calculation details and prior versions are left out. ### Filing caveats A filing may carry a free-text disclaimer about the completeness of its data. When present, it appears: - As a **`caveat`** field on the filing information (top-level for single-filing responses; per-row in `results[]` for compare endpoints; per-item in `filings[]` for `POST /data/filings`). Either `null` / absent (no caveat), or a string. - On endpoints that return facts or statements, as a **`_warnings`** entry of the form `Filing

FY[ ] has caveat: `. Compare endpoints aggregate per-filing caveats into a single deduplicated `_warnings` list. # Datasets ## `POST /data/company` **Purpose:** Resolve one company by **`ticker`**, **`cik`**, **`dart_corp_code`**, **`edinet_code`**, **`lei`**, or **`uscc`** and return its identity plus a coverage summary — every `form_type × fiscal_year × quarter` we hold for that issuer. To find a company by name, use [`POST /data/company/search`](#post-datacompanysearch). **Request:** | Field | Type | Required | Notes | |-------|------|----------|--------| | `ticker` | string | Conditional | Exactly one of `ticker`, `cik`, `dart_corp_code`, `edinet_code`, `lei`, or `uscc` must be provided. 1–32 characters; case-insensitive. European tickers are the composite form `_` (e.g. `VIRI_F`); China A-share tickers are `<6-digit code>_CN` (e.g. `600519_CN`). | | `cik` | string | Conditional | Numeric string; leading zeros optional. SEC-listed companies only. | | `dart_corp_code` | string | Conditional | Numeric string; leading zeros optional. Korean DART-listed companies only. | | `edinet_code` | string | Conditional | EDINET issuer code (`E` + 5 digits). Japanese EDINET-listed companies only. | | `lei` | string | Conditional | 20-character ISO 17442 LEI; case-insensitive. European ESEF-listed companies only. | | `uscc` | string | Conditional | 18-character Unified Social Credit Code; case-insensitive. China A-share companies only. | **Response:** | Field | Meaning | |-------|---------| | `ticker`, `cik`, `dart_corp_code`, `edinet_code`, `lei`, `uscc`, `legal_name` | Company identity. Only the applicable identifier is present — `cik` for SEC-listed companies, `dart_corp_code` for Korean companies, `edinet_code` for Japanese companies, `lei` for European companies, `uscc` (Unified Social Credit Code, 18 chars) for China A-share companies; the others are omitted. `legal_name` may be absent for rare records. | | `jurisdiction` | `"US"` for SEC-listed companies; `"KR"` for Korean DART-listed companies; `"JP"` for Japanese EDINET-listed companies; `"EU"` for European ESEF-listed companies; `"CN"` for China A-share companies. | | `sec_filings_url` | EDGAR public browse URL for the company, derived from CIK. Omitted for companies with no CIK (e.g. Korean and Japanese companies). | | `sec_filings_urls` | SEC-listed companies only: one entry per CIK the company has filed under, current first — `{cik, is_current, url}`. | | `tickers` | Every symbol the company has traded under — `{ticker, is_current, valid_from, valid_to}`; `valid_from` / `valid_to` only when set. | | `dart_filings_url` | DART public browse URL for the company, derived from `dart_corp_code`. Omitted for companies with no DART corp code (e.g. US and Japanese companies). | | `edinet_filings_url` | EDINET public browse URL for the company, derived from `edinet_code`. Omitted for companies with no EDINET code (e.g. US and Korean companies). | | `esef_filings_url` | filings.xbrl.org public browse URL for the company, derived from `lei`. Omitted for companies with no LEI. | | `cninfo_filings_url` | cninfo public browse URL for the company, derived from the 6-digit stock code. Omitted for non-A-share companies. | | `filings_count` | Total filings we hold for this company across all forms, within your plan's history window. | | `coverage` | Object keyed by filing-type name. **US**: SEC form names (`"10-K"`, `"10-Q"`, `"20-F"`, `"40-F"`). **KR** / **JP** / **EU** / **CN**: jurisdiction-neutral labels (`"annual"`, `"quarterly"`). Each value has `fiscal_years` (sorted list), `earliest`, `latest`, `fiscal_year_quarters` (year → list of quarter labels: `"FY"`, `"Q1"`–`"Q4"`), and `normalized_form` — a uniform identifier (`"annual"` / `"quarterly"`) you can use to iterate across jurisdictions without checking the key. | | `credits_used` | Always **8** when successful. | **Charging:** A `DATA_COMPANY_NOT_FOUND` response is still charged 8 credits. **Errors:** | HTTP | `error_code` | When | |------|----------------|------| | 404 | `DATA_COMPANY_NOT_FOUND` | No company on file for the given identifier. **Still debits 8 credits.** | | 403 | `PLAN_TIER_INSUFFICIENT_COVERAGE` | The requested company is outside your plan's coverage scope. **Still debits 8 credits.** | | 402 | `CREDITS_INSUFFICIENT` | Not enough credits. | | 422 | — | Validation (zero or more than one of `ticker`/`cik`/`dart_corp_code`/`edinet_code`/`lei`/`uscc` supplied; non-numeric `cik` or `dart_corp_code`; `lei` not 20 letters or digits; `uscc` not 18 letters or digits). | **Example Request:** ```json { "ticker": "AAPL" } ``` **Example Response:** ```json { "ticker": "AAPL", "jurisdiction": "US", "cik": "0000320193", "legal_name": "Apple Inc.", "sec_filings_url": "https://www.sec.gov/cgi-bin/browse-edgar?action=getcompany&CIK=0000320193&type=&dateb=&owner=include&count=40", "tickers": [ {"ticker": "AAPL", "is_current": true} ], "filings_count": 12, "coverage": { "10-K": { "fiscal_years": [2020, 2021, 2022, 2023, 2024], "earliest": 2020, "latest": 2024, "fiscal_year_quarters": { "2020": ["FY"], "2021": ["FY"], "2022": ["FY"], "2023": ["FY"], "2024": ["FY"] }, "normalized_form": "annual" }, "10-Q": { "fiscal_years": [2023, 2024], "earliest": 2023, "latest": 2024, "fiscal_year_quarters": { "2023": ["Q1", "Q2", "Q3"], "2024": ["Q1", "Q2", "Q3"] }, "normalized_form": "quarterly" } }, "credits_used": 8, "sec_filings_urls": [ {"cik": "0000320193", "is_current": true, "url": "https://www.sec.gov/cgi-bin/browse-edgar?action=getcompany&CIK=0000320193&type=&dateb=&owner=include&count=40"} ] } ``` ## `POST /data/company/search` **Purpose:** Find companies by name, symbol or registrant id: companies whose name contains `query`, or whose symbol (any it has traded under) or registrant id starts with it. Up to 8 companies, best match first. **Request:** | Field | Type | Required | Notes | |-------|------|----------|--------| | `query` | string | Yes | 1–64 characters; English names. | | `jurisdiction` | string | No | `"US"`, `"KR"`, `"JP"`, `"EU"`, `"CN"`, or `"all"`. When omitted, searches everything your plan includes. | **Response:** | Field | Meaning | |-------|---------| | `companies` | Up to 8 objects, best match first, each with `ticker`, `legal_name`, `jurisdiction`, and the one identifier that applies — `cik`, `dart_corp_code`, `edinet_code`, `lei`, or `uscc`. | | `companies[].classification` | Industry classification block — **Pro+ only**. See [Industry classification (Pro+)](#industry-classification-pro). | | `credits_used` | **10**; **0** when `query` is blank. | | `_warnings` | Optional; the coverage notice of [Coverage scope notice](#coverage-scope-notice). | **Errors:** | HTTP | `error_code` | When | |------|----------------|------| | 400 | `JURISDICTION_INVALID` | `jurisdiction` is not one of `US`, `KR`, `JP`, `EU`, `CN`, `all`. Not charged. | | 403 | `PLAN_TIER_INSUFFICIENT_COVERAGE` | The requested `jurisdiction` is outside your plan's coverage scope. Not charged. | | 402 | `CREDITS_INSUFFICIENT` | Not enough credits. | | 422 | — | Validation (`query` missing or longer than 64 characters). | **Example Request:** ```json { "query": "apple" } ``` **Example Response:** ```json { "companies": [ {"ticker": "AAPL", "legal_name": "Apple Inc.", "jurisdiction": "US", "cik": "0000320193"} ], "credits_used": 10 } ``` ## `GET /data/company/list` **Purpose:** Discovery — return the companies covered, one page at a time. **Request:** | Query | Type | Default | Notes | |-------|------|---------|--------| | `jurisdiction` | string | (omitted) | Optional. `"US"`, `"KR"`, `"JP"`, `"EU"`, `"CN"`, or `"all"`. When omitted, returns everything your plan includes. | | `page` | integer | `1` | 1–1,000,000. | | `page_size` | integer | `100` | 1–100. | | `detail` | string | `"full"` | `"light"` leaves out each company's `classification.source.url`. See [Response detail](#response-detail). | **Response:** | Field | Meaning | |-------|---------| | `companies` | One object per company, each with `ticker`, `legal_name`, `jurisdiction`, and the one identifier that applies — `cik` (SEC-listed), `dart_corp_code` (Korean), `edinet_code` (Japanese), `lei` (European), or `uscc` (China A-share); the others are omitted. All are omitted for the rare row whose identifier is not yet on file. | | `companies[].classification` | Industry classification block — **Pro+ only**. See [Industry classification (Pro+)](#industry-classification-pro). | | `page`, `page_size`, `has_more`, `next_page` | Paging; `next_page` is `null` on the last page. | | `credits_used` | **30** per page. | **Errors:** | HTTP | `error_code` | When | |------|----------------|------| | 403 | `PLAN_TIER_INSUFFICIENT_COVERAGE` | The requested `jurisdiction` is outside your plan's coverage scope. Not charged. | | 402 | `CREDITS_INSUFFICIENT` | Not enough credits. | | 400 | `JURISDICTION_INVALID` | `jurisdiction` is not one of `US`, `KR`, `JP`, `EU`, `CN`, `all`. Not charged. | | 422 | `VALIDATION_ERROR` | An unknown query parameter, or `page` / `page_size` out of range. Not charged. | **Example Request:** ``` GET /api/v1/data/company/list X-API-Key: ``` **Example Response:** ```json { "companies": [ {"ticker": "AAPL", "legal_name": "Apple Inc.", "jurisdiction": "US", "cik": "0000320193", "classification": {"sectors": ["Technology"], "source": {"scheme": "US_SIC", "code": "3571", "url": "https://www.sec.gov/search-filings/standard-industrial-classification-sic-code-list"}}}, {"ticker": "MSFT", "legal_name": "MICROSOFT CORP", "jurisdiction": "US", "cik": "0000789019"}, {"ticker": "005930", "legal_name": "Samsung Electronics Co., Ltd.", "jurisdiction": "KR", "dart_corp_code": "00126380"} ], "page": 1, "page_size": 100, "has_more": true, "next_page": 2, "credits_used": 30 } ``` ## `POST /data/filings` **Purpose:** List filings available for one company and one fiscal year, optionally filtered by form type and quarter. **Request:** | Field | Type | Required | Notes | |-------|------|----------|--------| | `ticker` | string | Yes | 1–32 characters; matched case-insensitively. | | `fiscal_year` | integer | Yes | 1990–2100. | | `form_type` | string | No | Max 32 characters. US forms: `10-K`, `10-Q`. Foreign-issuer annual reports: `20-F` (US-listed foreign companies), `40-F` (Canadian filers). Korean (DART), Japanese (EDINET), European (ESEF) and China A-share filings use the same values — `10-K` for the annual report, `10-Q` for the quarterly report. If omitted, all forms for that ticker and year are considered. | | `quarter` | string | No | Max 4 characters (e.g. `Q1`). Only filings of this quarter. | | `detail` | string | No | Default `"full"`. `"light"` leaves out the `fiscal_year`, `form_type` and `quarter` echoes. See [Response detail](#response-detail). | **Response:** | Field | Meaning | |-------|---------| | `credits_used` | Always **10** when successful. | | `fiscal_year` | Echo of request. | | `form_type` | Present only if you sent `form_type`. | | `quarter` | Present only if you sent `quarter`. | | `company` | Company profile (`ticker`, `jurisdiction`, `legal_name` and the identifier that applies: `cik`, `dart_corp_code`, `edinet_code`, `lei` or `uscc`), or `null` if unknown. | | `filings` | Array of filings: `id`, `ticker`, `registrant_cik`, `registrant_name` (the filing's registrant; `null` when absent), `form_type`, `fiscal_year`, `quarter`, `total_facts`, `total_blocks`, `has_excel`, `caveat` (see [Filing caveats](#filing-caveats)). | Optional **`amendment_context`** (`{summary}`, an English summary) appears on a filing item when an amendment was merged into it. **Errors:** | HTTP | `error_code` | When | |------|----------------|------| | 403 | `PLAN_TIER_INSUFFICIENT_COVERAGE` | The company is outside your plan's coverage scope. **Still debits 10 credits.** | | 402 | `CREDITS_INSUFFICIENT` | Not enough credits. | | 422 | — | Validation (body rules). | **Example Request:** ```json { "ticker": "AAPL", "fiscal_year": 2024, "form_type": "10-K" } ``` **Example Response:** ```json { "credits_used": 10, "fiscal_year": 2024, "company": { "ticker": "AAPL", "cik": "0000320193", "legal_name": "Apple Inc." }, "filings": [ { "id": 12345, "ticker": "AAPL", "registrant_cik": "0000320193", "registrant_name": "Apple Inc.", "form_type": "10-K", "fiscal_year": 2024, "quarter": "FY", "total_facts": 1500, "total_blocks": 12, "has_excel": true } ] } ``` ## `POST /data/filings/excel` **Purpose:** Obtain a download URL for the filing's Excel file, valid for one hour. **Filing selection:** supply **`filing_id`**, or **`ticker`** and **`fiscal_year`** with optional **`form_type`** (default **`10-K`**) and **`quarter`**. Giving both, or `form_type` or `quarter` with `filing_id`, returns 422. **Request:** | Field | Type | Required | Notes | |-------|------|----------|--------| | `filing_id` | integer | Conditional | 1–10⁹. | | `ticker` | string | Conditional | Required if `filing_id` omitted. 1–32 characters. | | `form_type` | string | No | Default `10-K`, max 32. | | `fiscal_year` | integer | Conditional | Required if `filing_id` omitted. 1990–2100. | | `quarter` | string | No | Max 4 characters. | **Response:** | Field | Meaning | |-------|---------| | `ticker`, `fiscal_year` | Filing identity. | | `download_url` | The URL to download the Excel file. | | `expires_in` | Seconds the URL stays valid (**3600**). | | `credits_used` | **300**. | **Credits:** **300**, debited after the filing and its Excel attachment are found; a `DATA_EXCEL_OBJECT_NOT_IN_STORAGE` response is still charged. **Errors:** | HTTP | `error_code` | When | |------|----------------|------| | 400 | `DATA_FILING_QUARTER_REQUIRED` | Several filings match without a quarter; message lists available quarters. Not charged. | | 404 | `DATA_FILING_NOT_FOUND` | No filing for the given id or identity. Not charged. | | 403 | `PLAN_TIER_INSUFFICIENT_HISTORY`, `PLAN_TIER_INSUFFICIENT`, `PLAN_TIER_INSUFFICIENT_COVERAGE` | The filing is outside your plan. Not charged. | | 404 | `DATA_EXCEL_NOT_AVAILABLE_FOR_FILING` | The filing has no Excel attachment. Not charged. | | 503 | `DATA_EXCEL_PUBLIC_URL_UNAVAILABLE` | A download URL cannot be provided right now. Not charged. | | 404 | `DATA_EXCEL_OBJECT_NOT_IN_STORAGE` | The Excel file is not available. **Charged 300.** | | 402 | `CREDITS_INSUFFICIENT` | Insufficient credits. | | 422 | — | Validation (filing selector, limits). | **Example Request:** ```json { "ticker": "AAPL", "fiscal_year": 2024 } ``` **Example Response:** ```json { "ticker": "AAPL", "fiscal_year": 2024, "download_url": "https://api.akkrudata.ai/...", "expires_in": 3600, "credits_used": 300 } ``` ## `POST /data/statement` **Purpose:** Return one or more **financial statement block(s)** (JSON) for a filing. Three mutually exclusive lookup modes: - **`role_label` mode** — the filer's original XBRL role string (varies per filer; e.g. `"CONSOLIDATED STATEMENTS OF OPERATIONS"` for Apple). Returns the one matched block. - **`statement_type` mode** — the canonical statement name (e.g. `"Income Statement"`, `"Balance Sheet"`, `"Comprehensive Income"`, `"Stockholders Equity"`, `"Cash Flow Statement"`). Call **[`POST /data/filing-statements`](#post-datafiling-statements)** for the valid values in a specific filing. Case-insensitive; trailing `(N)` suffix is ignored. Returns every matching block; a block that combines several statements matches each of its names. Available for SEC filings only; use `role_label` mode for other jurisdictions. - **`block_index` mode** — the block's `block_index` as [`POST /data/filing-statements`](#post-datafiling-statements) currently lists it. Returns that block. The 5 main statements also have their own [statement endpoints](#statement-endpoints-datastatement) (`/data/income-statement` etc.) with the same response shape. **Filing selection:** same pattern as **`POST /data/facts`** (`filing_id` **or** `ticker` + `fiscal_year` + `form_type` + optional `quarter`). **Request:** | Field | Type | Required | Notes | |-------|------|----------|--------| | `filing_id` | integer | Conditional | Same rules as facts. | | `ticker` | string | Conditional | | | `form_type` | string | No | Default `10-K`. | | `fiscal_year` | integer | Conditional | | | `quarter` | string | No | | | `role_label` | string | **One of `role_label` / `statement_type` / `block_index`** | 1–4000 characters; original filer XBRL role string. | | `statement_type` | string | **One of `role_label` / `statement_type` / `block_index`** | 1–4000 characters; canonical statement-type label. | | `block_index` | integer | **One of `role_label` / `statement_type` / `block_index`** | 0–32767; as listed by `POST /data/filing-statements`. | | `detail` | string | No | Default `"full"`. `"light"` leaves out `concept_ns`, `concept_local`, `item_type`, `decimals`, `sign_attr` and `format` from each fact's `xbrl_fact`. `"minimal"` keeps only `line_items` and, for each fact, its row label, `ix_id`, `concept`, `calculated_value` (`raw_value` when that is empty), `unit`, period and `dimensions` (China A-share filings: also `note_scope`); a fact repeated under `child_components` is listed once. See [Response detail](#response-detail). | **Credits:** - `role_label` mode: tiered **28 / 48**. **28** is debited before the filing is resolved (balance below 28 → **HTTP 402**); the extra **20** of the higher (48-credit) tier is debited after matching, up to your remaining balance. - `statement_type` and `block_index` modes: **28** flat, debited before the filing is resolved (balance below 28 → **HTTP 402**). **Response:** | Field | Meaning | |-------|---------| | `ticker`, `form_type`, `fiscal_year`, `quarter` | Filing identity. | | `matches` | Array of match objects (length 1 for role_label and block_index mode; length 1+ for statement_type mode). Each has `block_index`, `role_label`, `statement_type` (array of names; more than one when the block combines several statements), `matched_via` (describes how it was selected), and `block` (the statement block content; an entry under `block.child_components` that repeats the `block.parent_xbrl_table.mapped_xbrl_facts` entry with the same `html_locator.ix_id` carries only that `ix_id`). | | `credits_used` | Number of credits deducted. | | `amendment_context` | Optional; restatement or amendment information. | | `_correction` | Optional; present on the 48-credit tier. | | `_warnings` | Optional. | `calculated_value` (on each fact in `block`) is the XBRL value as filed. **Errors:** | HTTP | `error_code` | When | |------|----------------|------| | 400 | `DATA_FILING_QUARTER_REQUIRED` | Ambiguous quarterly filings (charged). | | 404 | `DATA_FILING_NOT_FOUND` | Filing not found. **Still charged 28 credits.** | | 404 | `DATA_STATEMENT_ROLE_LABEL_UNRESOLVED` | role_label mode: no block matched; charged for the match tier reached. | | 404 | `DATA_STATEMENT_NOT_AVAILABLE_IN_FILING` | statement_type mode: no block has this statement_type (charged). | | 400 | `DATA_STATEMENT_TYPE_UNSUPPORTED_FOR_KR` | statement_type mode on a Korean (DART) filing; use `role_label` mode (charged). | | 400 | `DATA_STATEMENT_TYPE_UNSUPPORTED_FOR_JP` | statement_type mode on a Japanese (EDINET) filing; use `role_label` mode (charged). | | 400 | `DATA_STATEMENT_TYPE_UNSUPPORTED_FOR_EU` | statement_type mode on a European (ESEF) filing; use `role_label` mode (charged). | | 400 | `DATA_STATEMENT_TYPE_UNSUPPORTED_FOR_CN` | statement_type mode on a China A-share filing; use `role_label` mode (charged). | | 404 | `DATA_STATEMENT_BLOCK_INDEX_NOT_FOUND` | block_index mode: the filing has no block at that position (charged). | | 404 | `DATA_STATEMENT_BLOCK_JSON_MISSING` | The block was found but its content is unavailable (**charged**). | | 403 | `PLAN_TIER_INSUFFICIENT_HISTORY` | The filing, named by `ticker` and `fiscal_year`, is before your plan's history window. Not charged. | | 403 | `PLAN_TIER_INSUFFICIENT`, `PLAN_TIER_INSUFFICIENT_COVERAGE` | The filing (by `filing_id`) or the company (by `ticker`) is outside your plan. **Charged 28.** | | 402 | `CREDITS_INSUFFICIENT` | Balance below 28. | | 422 | — | Validation (e.g. more than one of `role_label`, `statement_type`, `block_index` given, or none). | **Example Request (role_label mode):** ```json { "ticker": "AAPL", "form_type": "10-K", "fiscal_year": 2024, "role_label": "CONSOLIDATED STATEMENTS OF OPERATIONS" } ``` **Example Request (statement_type mode):** ```json { "ticker": "AAPL", "form_type": "10-K", "fiscal_year": 2024, "statement_type": "Income Statement" } ``` **Example Response:** ```json { "ticker": "AAPL", "form_type": "10-K", "fiscal_year": 2024, "quarter": "FY", "matches": [ { "block_index": 1, "role_label": "CONSOLIDATED STATEMENTS OF OPERATIONS", "statement_type": ["Income Statement"], "matched_via": { "source": "statement_type", "query": "Income Statement", "matched_statement_type": "Income Statement" }, "block": { "elements": [ "... truncated ..." ] } } ], "credits_used": 28 } ``` ## `POST /data/filing-statements` **Purpose:** Discovery — list every statement block in a filing with its `block_index`, `statement_type` (array of canonical statement-type labels; more than one when the block combines several statements; `null` for non-financial blocks such as the cover page), and `role_label` (filer-specific XBRL string). Use this to find out which `statement_type` / `role_label` / `block_index` values a specific filing exposes before calling **[`POST /data/statement`](#post-datastatement)** or the convenience endpoints. **Filing selection:** standard (`filing_id` **or** `ticker` + `fiscal_year` + `form_type` + optional `quarter`). **Request:** | Field | Type | Required | Notes | |-------|------|----------|--------| | `filing_id` | integer | Conditional | | | `ticker` | string | Conditional | | | `form_type` | string | No | Default `10-K`. | | `fiscal_year` | integer | Conditional | | | `quarter` | string | No | | **Response:** | Field | Meaning | |-------|---------| | `ticker`, `form_type`, `fiscal_year`, `quarter` | Filing identity. | | `statements` | Array of `{block_index, statement_type, role_label}`, ordered by `block_index`. | | `credits_used` | Always **10** when successful. | **Errors:** | HTTP | `error_code` | When | |------|----------------|------| | 400 | `DATA_FILING_QUARTER_REQUIRED` | Ambiguous quarterly filings (charged). | | 404 | `DATA_FILING_NOT_FOUND` | Filing not found. **Still charged 10 credits.** | | 403 | `PLAN_TIER_INSUFFICIENT_HISTORY` | The filing, named by `ticker` and `fiscal_year`, is before your plan's history window. Not charged. | | 403 | `PLAN_TIER_INSUFFICIENT`, `PLAN_TIER_INSUFFICIENT_COVERAGE` | The filing (by `filing_id`) or the company (by `ticker`) is outside your plan. **Charged 10.** | | 402 | `CREDITS_INSUFFICIENT` | Insufficient credits. | | 422 | — | Validation. | **Example Request:** ```json { "ticker": "AAPL", "form_type": "10-K", "fiscal_year": 2024 } ``` **Example Response:** ```json { "ticker": "AAPL", "form_type": "10-K", "fiscal_year": 2024, "quarter": "FY", "statements": [ { "block_index": 0, "statement_type": null, "role_label": "Cover Page" }, { "block_index": 1, "statement_type": ["Income Statement"], "role_label": "CONSOLIDATED STATEMENTS OF OPERATIONS" }, { "block_index": 2, "statement_type": ["Comprehensive Income"],"role_label": "CONSOLIDATED STATEMENTS OF COMPREHENSIVE INCOME" }, { "block_index": 3, "statement_type": ["Balance Sheet"], "role_label": "CONSOLIDATED BALANCE SHEETS" }, { "block_index": 4, "statement_type": ["Stockholders Equity"], "role_label": "CONSOLIDATED STATEMENTS OF SHAREHOLDERS' EQUITY" }, { "block_index": 5, "statement_type": ["Cash Flow Statement"], "role_label": "CONSOLIDATED STATEMENTS OF CASH FLOWS" }, { "block_index": 6, "statement_type": ["Earnings Per Share"],"role_label": "Earnings Per Share - Computation of Basic and Diluted..." } ], "credits_used": 10 } ``` ## Statement endpoints (`/data/`) Five endpoints that fetch one specific statement directly by URL. Each is equivalent to [`POST /data/statement`](#post-datastatement) with the matching `statement_type` — fixed by the URL path, so `role_label`, `statement_type` and `block_index` are not accepted in the body. Flat **28 credits** per successful debit, debited before the filing is resolved (a missing filing or statement is still charged); rate limit **120/minute**. Available for SEC filings only. | Endpoint | Statement returned | |---|---| | `POST /data/income-statement` | Income Statement | | `POST /data/comprehensive-income` | Statement of Comprehensive Income | | `POST /data/balance-sheet` | Balance Sheet | | `POST /data/cash-flow-statement` | Cash Flow Statement | | `POST /data/equity-statement` | Statement of Stockholders' / Shareholders' Equity | **Request body:** same fields as [`POST /data/statement`](#post-datastatement) **minus** `role_label`, `statement_type` and `block_index`. | Field | Type | Required | Notes | |-------|------|----------|--------| | `filing_id` | integer | Conditional | | | `ticker` | string | Conditional | | | `form_type` | string | No | Default `10-K`. | | `fiscal_year` | integer | Conditional | | | `quarter` | string | No | | | `detail` | string | No | Default `"full"`. Same as `POST /data/statement`. See [Response detail](#response-detail). | **Response:** identical to [`POST /data/statement`](#post-datastatement) (`matches: [...]`). `matched_via.source` is always `"statement_type"`. **Errors:** identical to [`POST /data/statement`](#post-datastatement) (`statement_type` mode). **Example request:** ```json { "ticker": "AAPL", "form_type": "10-K", "fiscal_year": 2024 } ``` ## `POST /data/line-items` **Purpose:** Return structured facts for **one** filing by **line-item name** (e.g. `revenue`, `net income`, `operating expenses`). Names are resolved through a tiered L0–L3 path; per-line-item credit pricing. **Filing selection:** supply **`filing_id`**, or **`ticker`** and **`fiscal_year`** with optional **`form_type`** (default **`10-K`**) and **`quarter`**. Giving both, or `form_type` or `quarter` with `filing_id`, returns 422. **Request:** | Field | Type | Required | Notes | |-------|------|----------|--------| | `filing_id` | integer | Conditional | 1–10⁹. | | `ticker` | string | Conditional | Required if `filing_id` omitted. 1–32 characters. | | `form_type` | string | No | Default `10-K`, max 32. | | `fiscal_year` | integer | Conditional | Required if `filing_id` omitted. 1990–2100. | | `quarter` | string | No | Max 4 characters. | | `line_items` | array of string | Yes | Non-empty; max **50** entries; each entry max **256** characters. A name given twice is charged once. | | `detail` | string | No | Default `"full"`. `"light"` leaves out each result's `dimensional_breakdowns`. See [Response detail](#response-detail). | **Response:** `ticker`, `form_type`, `fiscal_year`, `quarter`, `source_url_prefix`, `results`, `credits_used`, `credits_by_line_item` (credits charged per requested line item), optional `_correction` / `_warnings`, optional `amendment_context`. Each entry in `results` carries `metric`, `concept`, `value`, `raw_value`, `unit`, `period`, `dimensions`, `dimensional_breakdowns`, `restated` / `prior` (same meaning as on **[`POST /data/facts`](#post-datafacts)**; `null` when the fact was not touched by an amendment), **`_resolution_level`** (`"L0"`, `"L1"`, `"L2"`, or `"L3"`), and **one of**: - **`fact_id`** (string) + **`source_locator`** (string) — the number appears at exactly one position in the source filing. - **`fact_ids`** (list of `{fact_id, source_locator}` objects) — the same logical fact (matching concept, value, period, dimensions, and breakdowns) is reported at multiple positions in the source filing (e.g. income statement + equity statement + cash flow). All positions are listed equal-rank. The two fields are mutually exclusive; each result row carries exactly one of them. When one line-item name matches more than one concept, `results` come ordered by Akkru smart ranking and a `_warnings` entry gives the number of matched concepts. Review all returned results and judge which one you need. Results are consolidated totals. Slice values (a product line, segment, or region) are read with `POST /data/facts/dimensional-breakdown` / `POST /data/line-items/dimensional-breakdown` from the total's `fact_id`, or with `POST /data/statement` for the full statement table. `is_consolidated_total` is a string: `"true"` (the source filing explicitly tags the value as a consolidated total), `"equivalent"` (the source filing does not explicitly tag the value as a consolidated total; the value is presented as an equivalent consolidated total; see `_warnings`), or `"false"`. `revenue` follows each filing's own reported top line; for financial-sector companies (banks, brokers, insurers) that top line is a net figure (e.g. net interest income plus net fee income, or insurance revenue). Per-share items that a filing tags only per share class or dividend type are read from the statements and notes via `POST /data/filing-statements` + `POST /data/statement`. **Credits:** tiered L0=10 … L3=50 per line item, partial-credit billing. Zero balance → **HTTP 402**. **Errors:** `400 DATA_FILING_QUARTER_REQUIRED`, `404 DATA_FILING_NOT_FOUND`, `403 PLAN_TIER_INSUFFICIENT_HISTORY` / `PLAN_TIER_INSUFFICIENT` / `PLAN_TIER_INSUFFICIENT_COVERAGE` (not charged), `402 CREDITS_INSUFFICIENT`, `422` validation. **Example Request:** ```json { "filing_id": 12345, "line_items": ["revenue", "net income"], "detail": "light" } ``` **Example response excerpt** (one single-position row + one multi-position row): ```json { "results": [ { "metric": "depreciation", "concept": "us-gaap_Depreciation", "fact_id": "f-665", "source_locator": "aapl-20250927.htm#fact-identifier-780", "value": 8000000000.0, "raw_value": "8.0", "unit": "usd", "period": "2024-09-29 ~ 2025-09-27", "is_consolidated_total": "true", "_resolution_level": "L1" }, { "metric": "revenue", "concept": "us-gaap_RevenueFromContractWithCustomerExcludingAssessedTax", "fact_ids": [ { "fact_id": "f-78", "source_locator": "aapl-20250927.htm#fact-identifier-95" }, { "fact_id": "f-392", "source_locator": "aapl-20250927.htm#fact-identifier-113" }, { "fact_id": "f-1021", "source_locator": "aapl-20250927.htm#fact-identifier-121" }, { "fact_id": "f-1113", "source_locator": "aapl-20250927.htm#fact-identifier-143" } ], "value": 416161000000.0, "raw_value": "416,161", "unit": "usd", "period": "2024-09-29 ~ 2025-09-27", "is_consolidated_total": "true", "_resolution_level": "L1" } ], "credits_used": 40 } ``` ## `POST /data/facts` **Purpose:** Return structured facts for **one** filing by **`fact_id`**. For line-item-name queries (e.g. `revenue`, `net income`) use **[`POST /data/line-items`](#post-dataline-items)** instead. **Filing selection:** supply **`filing_id`**, or **`ticker`** and **`fiscal_year`** with optional **`form_type`** (default **`10-K`**) and **`quarter`**. Giving both, or `form_type` or `quarter` with `filing_id`, returns 422. **Request:** | Field | Type | Required | Notes | |-------|------|----------|--------| | `filing_id` | integer | Conditional | 1–10⁹. | | `ticker` | string | Conditional | Required if `filing_id` omitted. 1–32 characters. | | `form_type` | string | No | Default `10-K`, max 32. | | `fiscal_year` | integer | Conditional | Required if `filing_id` omitted. 1990–2100. | | `quarter` | string | No | Max 4 characters. | | `fact_ids` | array of string | Yes | Non-empty; max **500** strings; each max **128** characters. | | `detail` | string | No | Default `"full"`. `"light"` leaves out each result's `dimensional_breakdowns`. See [Response detail](#response-detail). | **Response:** | Field | Meaning | |-------|---------| | `ticker`, `form_type`, `fiscal_year`, `quarter` | Filing identity. | | `source_url_prefix` | **Source-document URL base** for this filing on its regulator's platform (SEC viewer for US filings; DART, EDINET, filings.xbrl.org, cninfo for KR / JP / EU / CN). May be `null`. Join it with each fact's `source_locator` for the document URL. | | `results` | Array of facts (each includes `concept`, `fact_id`, optional `source_locator`, values, units, period fields, plus `dimensions`, `dimensional_breakdowns` and `is_consolidated_total` — same meaning as in [`POST /data/line-items`](#post-dataline-items)). `source_locator` may be `null` or a fragment / relative path (amendments may use a `../`-relative locator); callers concatenate it with `source_url_prefix` as-is. **Amendment-affected facts** also carry `restated: true` plus a `prior` object: for a value-**changed** fact `prior` holds the superseded value (`raw_value` / `calculated_value` / `unit` / `decimals` / `fact_id` / `source_locator`; `calculated_value` is the XBRL value as filed); for a fact **added** by the amendment `prior` is the sentinel `{ "added_by_amendment": "This fact was not present in the original filing; it was added by an amendment." }`. Both fields are always present; on original/unaffected facts they are `null`. | | `credits_used` | `ceil(deduped_fact_id_count / 5) × 10`. | | `amendment_context` | Optional; same idea as under filings when applicable. | | `_warnings` | Optional strings (duplicate ids deduplicated, missing ids not found in the filing). | **Errors:** | HTTP | `error_code` | When | |------|----------------|------| | 400 | `DATA_FILING_QUARTER_REQUIRED` | Several filings match without a quarter; message lists available quarters. | | 404 | `DATA_FILING_NOT_FOUND` | No filing for the given id or identity. | | 403 | `PLAN_TIER_INSUFFICIENT_HISTORY`, `PLAN_TIER_INSUFFICIENT`, `PLAN_TIER_INSUFFICIENT_COVERAGE` | The filing is outside your plan (see [History truncation notice](#history-truncation-notice), [Coverage scope notice](#coverage-scope-notice)). Not charged. | | 402 | `CREDITS_INSUFFICIENT` | Not enough credits. | | 422 | — | Validation (empty fact_ids, limits, filing selector). | **Example Request:** ```json { "filing_id": 12345, "fact_ids": ["ix_1", "ix_2"] } ``` ## `POST /data/facts/dimensional-breakdown` **Purpose:** Return one consolidated fact plus every slice fact it breaks down into. Slice facts are grouped by the set of XBRL axes their dimensions sit on. **Filing selection:** standard (`filing_id` **or** `ticker` + `fiscal_year` + `form_type` + optional `quarter`). **Request:** | Field | Type | Required | Notes | |-------|------|----------|--------| | `filing_id` | integer | Conditional | | | `ticker` | string | Conditional | | | `form_type` | string | No | Default `10-K`. | | `fiscal_year` | integer | Conditional | | | `quarter` | string | No | | | `fact_id` | string | **Yes** | The `fact_id` of a consolidated fact. | | `recursive` | boolean | No | Default `true`. When `false`, only the immediate children are returned. | | `detail` | string | No | Default `"full"`. Full and minimal views only: `"light"` returns the minimal view. See [Response detail](#response-detail). | **Response:** | Field | Meaning | |-------|---------| | `ticker`, `form_type`, `fiscal_year`, `quarter`, `source_url_prefix` | Filing identity. | | `root` | The fact identified by `fact_id`: `concept`, `value`, `raw_value`, `unit`, `period`, `dimensions`, `is_consolidated_total`, `fact_id`, `source_locator`, plus `restated` and `prior` (as on **[`POST /data/facts`](#post-datafacts)**) when an amendment changed it. Slice facts have the same fields. | | `groups` | Array of `{axes, facts}` entries. `axes` is the sorted list of XBRL axis keys shared by every fact in `facts`; `facts` is the list of slice facts. Sorted by descending fact count, ties broken lexicographically by `axes`. | | `groups[].facts[].groups` | Present only when `recursive=true` and that slice has slices of its own. Same shape, nested per level. | | `_warnings` | Optional. | | `credits_used` | `ceil((1 + N) / 5) × 10`, where `N` is the number of the fact's direct dimensional children. | **Member granularity within a group:** A single axis may carry both summary members and their detail components. Summary members overlap their detail components, so summing all facts in one group can double-count. **Credits:** `ceil((1 + N) / 5) × 10`, where `N` is the number of the fact's direct dimensional children. **10 credits are charged** on `DATA_FACT_NOT_FOUND`. A root with no breakdowns returns 200 with `groups: []` and is charged 10 credits. **Errors:** | HTTP | `error_code` | When | |------|----------------|------| | 400 | `DATA_FILING_QUARTER_REQUIRED` | Ambiguous quarterly filings. | | 404 | `DATA_FILING_NOT_FOUND` | Filing not found. | | 404 | `DATA_FACT_NOT_FOUND` | `fact_id` is not present in this filing. **Still charged 10 credits.** | | 403 | `PLAN_TIER_INSUFFICIENT_HISTORY`, `PLAN_TIER_INSUFFICIENT`, `PLAN_TIER_INSUFFICIENT_COVERAGE` | The filing is outside your plan. Not charged. | | 402 | `CREDITS_INSUFFICIENT` | Not enough credits. | | 422 | — | Validation. | **Example Request:** ```json { "ticker": "AAPL", "form_type": "10-K", "fiscal_year": 2025, "fact_id": "f-78" } ``` **Example Response (abridged):** ```json { "ticker": "AAPL", "form_type": "10-K", "fiscal_year": 2025, "quarter": "FY", "source_url_prefix": "...", "root": { "concept": "us-gaap_RevenueFromContractWithCustomerExcludingAssessedTax", "fact_id": "f-78", "value": 416161000000.0, "raw_value": "416,161", "unit": "usd", "period": "2024-09-29 ~ 2025-09-27", "is_consolidated_total": "true", "dimensions": [] }, "groups": [ { "axes": ["srt_ProductOrServiceAxis"], "facts": [ {"concept": "us-gaap_RevenueFromContractWithCustomerExcludingAssessedTax", "fact_id": "f-72", "value": 307003000000.0, "dimensions": [{"axis": "srt_ProductOrServiceAxis","member": "us-gaap_ProductMember"}]}, {"fact_id": "f-377", "value": 209586000000.0, "dimensions": [{"axis": "srt_ProductOrServiceAxis","member": "aapl_IPhoneMember"}]} ] }, { "axes": ["srt_ConsolidationItemsAxis","us-gaap_StatementBusinessSegmentsAxis"], "facts": [ {"fact_id": "f-1016", "value": 178353000000.0, "dimensions": [ {"axis":"srt_ConsolidationItemsAxis","member":"us-gaap_OperatingSegmentsMember"}, {"axis":"us-gaap_StatementBusinessSegmentsAxis","member":"aapl_AmericasSegmentMember"} ]} ] }, { "axes": ["srt_StatementGeographicalAxis"], "facts": [ {"fact_id": "f-1104", "value": 151790000000.0, "dimensions": [{"axis":"srt_StatementGeographicalAxis","member":"country_US"}]} ] } ], "credits_used": 30 } ``` ## `POST /data/line-items/dimensional-breakdown` **Purpose:** Resolve a line-item name (e.g. `revenue`, `net income`) and return the dimensional breakdown of every consolidated fact that matches. Each match is one root with its axis-grouped slice facts. When the name matches more than one concept, matches come pre-ordered by Akkru smart ranking (same ordering as `POST /data/line-items`); the order is a recommendation only — review all matches and judge which one you need. **Filing selection:** standard (`filing_id` **or** `ticker` + `fiscal_year` + `form_type` + optional `quarter`). **Request:** | Field | Type | Required | Notes | |-------|------|----------|--------| | `filing_id` | integer | Conditional | | | `ticker` | string | Conditional | | | `form_type` | string | No | Default `10-K`. | | `fiscal_year` | integer | Conditional | | | `quarter` | string | No | | | `line_item` | string | **Yes** | A single line-item name (e.g. `"revenue"`). | | `recursive` | boolean | No | Default `true`. | | `detail` | string | No | Default `"full"`. Full and minimal views only: `"light"` returns the minimal view. See [Response detail](#response-detail). | **Response:** | Field | Meaning | |-------|---------| | `ticker`, `form_type`, `fiscal_year`, `quarter`, `source_url_prefix` | Filing identity. | | `matches` | Array of `{root, groups, duplicate_root_fact_ids?}` entries. | | `matches[].root` | Same shape as `root` in **[`POST /data/facts/dimensional-breakdown`](#post-datafactsdimensional-breakdown)**, plus `metric` (echoes the request `line_item`) and `_resolution_level` (`"L0"`–`"L3"`). | | `matches[].groups` | Same shape and ordering as `groups` in **[`POST /data/facts/dimensional-breakdown`](#post-datafactsdimensional-breakdown)**. Each fact also carries `metric` and `_resolution_level`. | | `matches[].duplicate_root_fact_ids` | Optional. Other `fact_id` values that resolved to the same logical fact as `root`. | | `_correction` | Optional. Same shape as on **[`POST /data/line-items`](#post-dataline-items)**. | | `_warnings` | Optional. | | `credits_used` | Resolver tier credit + `ceil(N_total / 5) × 10`, where `N_total` is the slice facts returned across all roots. | **Member granularity within a group:** Same as **[`POST /data/facts/dimensional-breakdown`](#post-datafactsdimensional-breakdown)** — summary members and their detail components may coexist; summing all facts in one group can double-count. **Credits:** Tiered resolution credit (**L0=10 … L3=50**) + `ceil(N_total / 5) × 10`. Partial billing applies. **Errors:** | HTTP | `error_code` | When | |------|----------------|------| | 400 | `DATA_FILING_QUARTER_REQUIRED` | Ambiguous quarterly filings. | | 404 | `DATA_FILING_NOT_FOUND` | Filing not found. | | 403 | `PLAN_TIER_INSUFFICIENT_HISTORY`, `PLAN_TIER_INSUFFICIENT`, `PLAN_TIER_INSUFFICIENT_COVERAGE` | The filing is outside your plan. Not charged. | | 402 | `CREDITS_INSUFFICIENT` | Zero balance. | | 422 | — | Validation. | **Example Request:** ```json { "ticker": "AAPL", "form_type": "10-K", "fiscal_year": 2025, "line_item": "revenue" } ``` **Example Response (abridged):** ```json { "ticker": "AAPL", "form_type": "10-K", "fiscal_year": 2025, "quarter": "FY", "source_url_prefix": "...", "matches": [ { "root": { "metric": "revenue", "concept": "us-gaap_RevenueFromContractWithCustomerExcludingAssessedTax", "fact_id": "f-78", "value": 416161000000.0, "period": "2024-09-29 ~ 2025-09-27", "is_consolidated_total": "true", "dimensions": [], "_resolution_level": "L1" }, "duplicate_root_fact_ids": ["f-392","f-1021","f-1113"], "groups": [ /* ... */ ] }, { "root": { "metric": "revenue", "fact_id": "f-79", "value": 391035000000.0, "period": "2023-10-01 ~ 2024-09-28", "_resolution_level": "L1", "..." : "..." }, "duplicate_root_fact_ids": ["f-393","f-1050","f-1114"], "groups": [ /* ... */ ] }, { "root": { "metric": "revenue", "fact_id": "f-80", "value": 383285000000.0, "period": "2022-09-25 ~ 2023-09-30", "_resolution_level": "L1", "..." : "..." }, "duplicate_root_fact_ids": ["f-394","f-1079","f-1115"], "groups": [ /* ... */ ] } ], "credits_used": 110 } ``` ## `POST /data/compare/line-items` **Purpose:** Compare a list of **line-item names** (e.g. `revenue`, `net income`) across **up to 25 filings**. Names are resolved through the same L0–L3 tiered path as **[`POST /data/line-items`](#post-dataline-items)**; per-line-item × per-filing pricing applies. Results are consolidated totals, as in [`POST /data/line-items`](#post-dataline-items). **Request:** | Field | Type | Required | Notes | |-------|------|----------|--------| | `filings` | array | Yes | 1–25 rows. Each row: `filing_id` **or** (`ticker` + `fiscal_year` + optional `form_type` and `quarter`), same rules as **`POST /data/facts`**. | | `line_items` | array of string | Yes | Non-empty; max **50** strings; each max **256** chars. | | `detail` | string | No | Default `"full"`. `"light"` leaves out each fact's `dimensional_breakdowns` and each row's `classification.source.url`. See [Response detail](#response-detail). | **Response:** | Field | Meaning | |-------|---------| | `amendment_contexts` | Array parallel to `results`; each entry is an object or **`null`**. | | `results` | Each element: `ticker`, `form_type`, `fiscal_year`, `quarter`, **`source_url_prefix`** (filing-level SEC URL base, may be `null`), optional **`caveat`** (per-row; see [Filing caveats](#filing-caveats)), **`unresolved`** (resolved line items with no consolidated-total fact in that filing), **`facts`** (array of fact objects; each fact carries either `fact_id` + `source_locator` or `fact_ids`, as in **`POST /data/line-items`**, plus **`_resolution_level`** = `"L0"` … `"L3"` indicating which tier matched that line item), and — for **Pro+** callers — a per-row **`classification`** block (see [Industry classification (Pro+)](#industry-classification-pro)). | | `failed_filings` | Optional. Rows that could not be compared, each `{index, error_code, message}` with the error that row alone would return; these rows are not charged. | | `credits_used` | Per credit rules in [Credit summary](#credit-summary). | | `credits_by_line_item` | Credits charged per requested line item, summed over the compared filings. | | `_correction`, `_warnings` | Optional; same general meaning as **`POST /data/line-items`**. Multi-concept line items are ordered by Akkru smart ranking within each row's `facts`, same as `POST /data/line-items` (a recommendation only — review all results). A `_warnings` entry is appended when the compared filings' fiscal period end dates differ by more than 45 days. The dimensional-breakdown notice is aggregated into a single string listing affected filings + fact ids. Per-row caveats are also aggregated into top-level `_warnings` (deduplicated; see [Filing caveats](#filing-caveats)). When rows fail, a `_warnings` entry reads `{n} of {m} filings could not be compared; see failed_filings.` | **Partial-credit behavior:** This endpoint charges per line item × per filing with partial-credit billing. When your balance cannot cover the full request, the remaining line items return as **unresolved**; `_warnings` / `_correction` show which, so you can top up and re-issue for the rest. **Errors:** a row that cannot be resolved (`DATA_FILING_QUARTER_REQUIRED`, `DATA_FILING_NOT_FOUND`, a `PLAN_TIER_*` 403) is listed in `failed_filings`. When every row fails, the request returns the first row's error, with `failed_filings` in `detail`. | HTTP | `error_code` | When | |------|----------------|------| | 400 / 404 / 403 | the first row's code | Every row failed. | | 402 | `CREDITS_INSUFFICIENT` | Zero balance. | | 422 | — | Limits, missing line_items, a row without `filing_id` or `ticker` + `fiscal_year`, unknown row keys, or other validation. | **Example Request:** ```json { "filings": [ { "ticker": "AAPL", "form_type": "10-K", "fiscal_year": 2024 }, { "ticker": "AAPL", "form_type": "10-K", "fiscal_year": 2023 } ], "line_items": ["revenue"] } ``` **Example Response:** ```json { "amendment_contexts": [null, null], "results": [ { "ticker": "AAPL", "form_type": "10-K", "fiscal_year": 2024, "quarter": "FY", "source_url_prefix": "https://www.sec.gov/ix?doc=/Archives/edgar/data/.../aapl-20240928.htm", "facts": [ { "metric": "revenue", "concept": "us-gaap_Revenue...", "fact_id": "f-1", "source_locator": "#fact-identifier-f-1", "value": 383285000000.0 } ] }, { "ticker": "AAPL", "form_type": "10-K", "fiscal_year": 2023, "quarter": "FY", "source_url_prefix": "https://www.sec.gov/ix?doc=/Archives/edgar/data/.../aapl-20230930.htm", "facts": [ { "metric": "revenue", "concept": "us-gaap_Revenue...", "fact_id": "f-1", "source_locator": "#fact-identifier-f-1", "value": 394328000000.0 } ] } ], "credits_used": 40 } ``` ## `POST /data/compare/facts` **Purpose:** Compare XBRL **`fact_ids`** across **up to 25 filings**. Each filing row carries its own `fact_ids` list. **Request:** | Field | Type | Required | Notes | |-------|------|----------|--------| | `filings` | array | Yes | 1–25 rows. Each row: `filing_id` **or** (`ticker` + `fiscal_year` + optional `form_type` and `quarter`), **plus** a required non-empty `fact_ids` list (max **500** per row; **2500** total ids across the whole request; each id ≤ **128** chars). | | `detail` | string | No | Default `"full"`. `"light"` leaves out each fact's `dimensional_breakdowns` and each row's `classification.source.url`. See [Response detail](#response-detail). | **Response:** `results` (per row: `ticker`, `form_type`, `fiscal_year`, `quarter`, `source_url_prefix`, optional `caveat`, `facts` with the fields of [`POST /data/facts`](#post-datafacts), and for **Pro+** callers `classification`), `amendment_contexts`, optional `failed_filings` (as on [`POST /data/compare/line-items`](#post-datacompareline-items)), `credits_used` and optional `_warnings`. A `_warnings` entry is appended when the compared filings' fiscal period end dates differ by more than 45 days. **Partial-credit behavior:** Full request cost is `ceil(total_deduped_fact_ids / 5) × 10` credits over the compared rows. When your balance covers only part of it, you are charged that much and the response serves that many fact_ids (each 10 credits buy up to 5 ids; filings are processed in request order, and once the budget runs out the remaining filings come back with `facts: []`). A `_warnings` entry states how many ids were served of those requested, and `credits_used` is what was spent. A balance below 10 → **HTTP 402**. **Errors:** as on [`POST /data/compare/line-items`](#post-datacompareline-items): failed rows are listed in `failed_filings`; when every row fails, the request returns the first row's error with `failed_filings` in `detail`. | HTTP | `error_code` | When | |------|----------------|------| | 400 / 404 / 403 | the first row's code | Every row failed. | | 402 | `CREDITS_INSUFFICIENT` | Balance below 10. | | 422 | — | Limits, missing fact_ids, a row without `filing_id` or `ticker` + `fiscal_year`, unknown row keys, or other validation. | **Example Request:** ```json { "filings": [ { "filing_id": 12345, "fact_ids": ["ix_1", "ix_2"] }, { "filing_id": 12344, "fact_ids": ["ix_1"] } ] } ``` ## Response conventions The `/metric/*` endpoints require the **Starter plan or higher**; Free callers receive `403 PLAN_TIER_INSUFFICIENT` (see [API key, account, and plan errors](#api-key-account-and-plan-errors)). The `formula_override` request field is additionally gated to the **Pro plan or higher** — Starter callers must omit `formula_override`. Every metric returned by `/metric/*` endpoints carries a `status` field and a `derivation` field. The rest of the object's contents depend on these two. ### `status` | Value | Meaning | |---|---| | `ok` | Metric was computed; `value` is set. | | `not_applicable` | Metric does not apply to this filing. Carries a `reason` string; `value` is `null`. | | `missing_input` | A required XBRL fact is missing. Carries a `missing_symbols` list; `value` is `null`. | | `needs_price_data` | Price-sensitive metric called without `current_price`. `value` is `null`; pass `current_price` to upgrade to `ok`. | | `needs_user_formula` | The filing uses a non-standard concept combination. Pass `accept_suggested_formula=true` or supply `formula_override` to compute. `value` is `null`; a `suggested_formula` field is included. | | `needs_history` | A prior-period value is required (e.g. growth rates) but is not available for this filing. `value` is `null`. | | `divide_by_zero` | Denominator was zero. `value` is `null`. | | `eval_error` | Formula execution failed. `value` is `null`. | `not_applicable` takes precedence over every other status — once an NA rule fires for a metric, the response will be `not_applicable` regardless of what would otherwise apply. ### `derivation` | Value | Meaning | |---|---| | `derived` | Computed from multiple XBRL facts via the standard formula. | | `as_reported` | Single XBRL fact taken at face value, no formula run. | | `composite` | Built from multiple non-standard concepts (e.g. REIT CapEx = REInvestment + Maintenance). | | `segment_sum` | No consolidated total in the filing; summed across segment members. | | `class_sum` | Summed across asset / liability class members. | | `company_override` | A company-specific override rule produced the value. | | `proxy_substituted` | A proxy fact was used in place of the primary one (most often on ADR / foreign-issuer price-sensitive metrics). | | `TTM_rollforward` | A trailing-12-month value for a quarterly filing. Comparable to annual filings of the same metric without further adjustment. | | `user_formula_accepted` | Result of `accept_suggested_formula=true` — the returned `suggested_formula` was applied. | | `user_formula_custom` | Result of a caller-supplied `formula_override`. | | `user_must_compute` | Companion to `status="needs_user_formula"`. A caller-provided calculation is required. | | `not_applicable` | Companion to `status="not_applicable"`. | When a metric cannot be computed, `derivation` repeats its `status` (for example `missing_input` or `needs_price_data`). Branch on `status` first. ### `editable` | Value | Meaning | |---|---| | `true` | `formula_override` applies to this metric. | | `false` | `formula_override` does not apply to this metric. | ### Currency and FX A metric object may carry these three currency-related fields: | Field | Meaning | |---|---| | `unit` | Display unit. Either a currency code (`usd`, `eur`, `twd`, …) for absolute monetary metrics, or `ratio` / `percent` / `days` / `shares` etc. for non-monetary metrics. | | `currency` | Source currency for absolute monetary metrics. Absent on ratio / percent / unitless metrics. | | `fx_required` | `true` when the metric is denominated in a non-USD currency (caller may want to convert to USD before using the value). `false` when no conversion is needed (already USD, or unitless). | For price-sensitive metrics on foreign-issuer filings (20-F / 40-F whose `reporting_currency` is not USD), the metric object also carries a `price_used` block: | Subfield | Meaning | |---|---| | `close` | The price actually used in the formula (in the filer's reporting currency). | | `date` | Date of `close`. | | `source` | Identifier for the source of the price used. | | `original_adr_price_usd` | The USD ADR price supplied (or filing-date USD price). | | `adr_ratio` | ADR ratio (number of common shares per ADR). | | `fx_rate_local_per_usd` | Conversion factor used for the period (filing-date price blocks). | | `reporting_ccy` | Filer's reporting currency (e.g. `EUR`, `TWD`, `CAD`). | To convert a foreign-issuer absolute metric to USD: ```text title="Formula" value_usd = value / fx_rate_local_per_usd ``` For USD-reporting filings, `fx_required` is `false`, `currency` (when present) is `usd`, and `price_used` contains only `close`, `date`, `source`. ### Light and minimal views Every `/metric/*` endpoint except `POST /metric/filings` accepts `detail` ([Response detail](#response-detail)). - `"light"` leaves out each metric's `components`, and the `valuation_context` (`query_context` on `POST /metric/historical`) echo. - `"minimal"` keeps each metric's `value`, `unit`, `currency`, `period_basis`, `adjusted_value` and `concept_variant`; `status`, `reason` and `error` when `status` is not `ok`; `missing_symbols` when `status` is `missing_input`; `derivation` when `status` is `ok` and it is not `as_reported` or `derived`; and the `date` of `price_used`. ## Supported metric catalog The API exposes **82** metrics, listed below by category. Use the **name** column verbatim wherever the API takes a metric id (e.g. `metric_names` on `POST /metric/items`, `formula_override` keys, `metric_names` on `POST /metric/historical`). Names marked **★** are **price-sensitive** — their realtime values require `current_price` in the request body (see [`POST /metric/all`](#post-metricall)). ### Profitability (10) | Name | Unit | Formula | |------|------|---------| | `gross_margin` | ratio | `(Revenue - CostOfRevenue) / Revenue` | | `operating_margin` | ratio | `OperatingIncome / Revenue` | | `net_margin` | ratio | `NetIncome / Revenue` | | `ebitda_margin` | ratio | `(OperatingIncome + DepreciationAndAmortization) / Revenue` | | `nopat` | reporting currency | `NI_cont + NetFinancialExpenseAfterTax` | | `nopat_reported_oi_proxy` | reporting currency | `OperatingIncome * (1 - TaxRate)` | | `nopat_margin` | ratio | `NOPAT / Revenue` | | `owner_earnings_estimate` | reporting currency | `CFO - MaintenanceCapex - SBC_CF` | | `owner_earnings_cash_proxy` | reporting currency | `CFO - Capex - SBC_CF` | | `owner_earnings_per_share` | reporting currency | `OE_common / Shares_avg` | ### Returns (5) | Name | Unit | Formula | |------|------|---------| | `return_on_equity` | ratio | `NetIncome / ((Equity + EquityPrior) / 2)` | | `return_on_assets` | ratio | `NetIncome / ((Assets + AssetsPrior) / 2)` | | `return_on_invested_capital` | ratio | `NetIncome / (((Equity + LongTermDebt + ShortTermDebt) + (EquityPrior + LongTermDebtPrior + ShortTermDebtPrior)) / 2)` | | `return_on_tangible_equity` | ratio | `NetIncome / (((Equity - Goodwill - Intangibles) + (EquityPrior - GoodwillPrior - IntangiblesPrior)) / 2)` | | `return_on_net_operating_assets` | ratio | `NOPAT / AvgNOA` | ### Leverage (8) | Name | Unit | Formula | |------|------|---------| | `debt_to_equity` | ratio | `(LongTermDebt + ShortTermDebt) / Equity` | | `debt_to_assets` | ratio | `(LongTermDebt + ShortTermDebt) / Assets` | | `debt_to_ebitda` | ratio | `(LongTermDebt + ShortTermDebt) / (OperatingIncome + DepreciationAndAmortization)` | | `interest_coverage` | ratio | `OperatingIncome / InterestExpense` | | `net_debt` | reporting currency | `Debt - UnrestrictedCash` | | `net_debt_to_ebitda` | ratio | `NetDebt / OperatingEBITDA` | | `net_financial_obligations` | reporting currency | `FO - FA` | | `net_financial_expense_after_tax` | reporting currency | `(InterestExpenseDebt - InterestIncome) * (1 - TaxRate)` | ### Liquidity (3) | Name | Unit | Formula | |------|------|---------| | `current_ratio` | ratio | `CurrentAssets / CurrentLiabilities` | | `quick_ratio` | ratio | `(CurrentAssets - Inventory) / CurrentLiabilities` | | `cash_ratio` | ratio | `Cash / CurrentLiabilities` | ### Efficiency / activity (10) | Name | Unit | Formula | |------|------|---------| | `asset_turnover` | ratio | `Revenue / ((Assets + AssetsPrior) / 2)` | | `inventory_turnover` | ratio | `CostOfRevenue / Inventory` | | `receivables_turnover` | ratio | `Revenue / AccountsReceivable` | | `days_inventory` | days | `PeriodDays * Inventory / CostOfRevenue` | | `days_receivable` | days | `PeriodDays * AccountsReceivable / Revenue` | | `days_payable` | days | `PeriodDays * AccountsPayable / CostOfRevenue` | | `cash_conversion_cycle` | days | `days_inventory + days_receivable − days_payable` | | `payables_turnover` | ratio | `CostOfRevenue / ((AccountsPayable + AccountsPayablePrior) / 2)` | | `net_operating_assets` | reporting currency | `TotalAssets - TotalLiabilities + FO - FA` | | `net_operating_asset_turnover` | ratio | `Revenue / AvgNOA` | ### Cash flow & shareholder returns (18) | Name | Unit | Formula | |------|------|---------| | `free_cash_flow` | reporting currency | `CFO - Capex` | | `fcf_margin` | ratio | `(CFO - Capex) / Revenue` | | `payout_ratio` | ratio | `Dividends / NetIncome` | | `free_cash_flow_per_share` | reporting currency | `FCF / Shares_avg` | | `free_cash_flow_after_sbc` | reporting currency | `FCF - SBC_PL` | | `fcf_ex_sbc_addback` | reporting currency | `FCF - SBC_CF` | | `free_cash_flow_cagr_3y` | ratio | `(FCF_t / FCF_t-3)^(1/3) - 1` | | `free_cash_flow_cagr_5y` | ratio | `(FCF_t / FCF_t-5)^(1/5) - 1` | | `free_cash_flow_cagr_10y` | ratio | `(FCF_t / FCF_t-10)^(1/10) - 1` | | `free_cash_flow_per_share_cagr_3y` | ratio | `(FCF_per_share_t / FCF_per_share_t-3)^(1/3) - 1` | | `free_cash_flow_per_share_cagr_5y` | ratio | `(FCF_per_share_t / FCF_per_share_t-5)^(1/5) - 1` | | `free_cash_flow_per_share_cagr_10y` | ratio | `(FCF_per_share_t / FCF_per_share_t-10)^(1/10) - 1` | | `cfo_to_net_income` | ratio | `CFO / NI` | | `fcf_to_net_income` | ratio | `FCF / NI` | | `cash_distributions_to_fcf` | ratio | `(CommonCashDividends + PreferredCashDividends + NCICashDistributions) / FCF` | | `common_dividend_burden_on_group_fcf` | ratio | `CommonCashDividends / FCF` | | `sbc_to_revenue` | ratio | `SBC_PL / Revenue` | | `sbc_to_fcf` | ratio | `SBC_PL / FCF` | ### Valuation — price-sensitive (13) ★ These require `current_price` in the request body to compute their realtime values; without it the `realtime` block returns the standard *missing-price* hint. | Name | Unit | Formula | |------|------|---------| | `market_cap` ★ | reporting currency | `SharesOutstanding * Price` | | `enterprise_value` ★ | reporting currency | `MarketCap + LongTermDebt + ShortTermDebt - Cash` | | `pe_ratio` ★ | ratio | `Price / EPS` | | `price_to_book` ★ | ratio | `MarketCap / Equity` | | `price_to_sales` ★ | ratio | `MarketCap / Revenue` | | `price_to_cash_flow` ★ | ratio | `MarketCap / CFO` | | `ev_to_ebitda` ★ | ratio | `EnterpriseValue / (OperatingIncome + DepreciationAndAmortization)` | | `ev_to_revenue` ★ | ratio | `EnterpriseValue / Revenue` | | `ev_to_fcf` ★ | ratio | `EnterpriseValue / (CFO - Capex)` | | `fcf_yield` ★ | ratio | `(CFO - Capex) / MarketCap` | | `dividend_yield` ★ | ratio | `DividendsPerShare / Price` | | `buyback_yield` ★ | ratio | `StockRepurchases / MarketCap` | | `owner_earnings_yield` ★ | ratio | `OE_common / MarketCap` | ### Growth (15) Year-over-year (yoy) growth compares the current period to the same period one year earlier; quarter-over-quarter (qoq) compares the current quarter to the immediately preceding quarter. | Name | Unit | Formula | |------|------|---------| | `revenue_growth_yoy` | ratio | `(Revenue_t - Revenue_{t-4Q}) / Revenue_{t-4Q}` | | `revenue_growth_qoq` | ratio | `(Revenue_t - Revenue_{t-1Q}) / Revenue_{t-1Q}` | | `revenue_growth_qoq_single_quarter` | ratio | `(Revenue_Qn_single - Revenue_Q(n-1)_single) / Revenue_Q(n-1)_single` | | `eps_growth_yoy` | ratio | `(EPS_t - EPS_{t-4Q}) / EPS_{t-4Q}` | | `net_income_growth_yoy` | ratio | `(NI_t - NI_{t-4Q}) / NI_{t-4Q}` | | `fcf_growth_yoy` | ratio | `(FCF_t - FCF_{t-4Q}) / FCF_{t-4Q}` | | `revenue_cagr_3y` | ratio | `(Revenue_t / Revenue_t-3)^(1/3) - 1` | | `revenue_cagr_5y` | ratio | `(Revenue_t / Revenue_t-5)^(1/5) - 1` | | `revenue_cagr_10y` | ratio | `(Revenue_t / Revenue_t-10)^(1/10) - 1` | | `diluted_eps_cagr_3y` | ratio | `(DilutedEPS_t / DilutedEPS_t-3)^(1/3) - 1` | | `diluted_eps_cagr_5y` | ratio | `(DilutedEPS_t / DilutedEPS_t-5)^(1/5) - 1` | | `diluted_eps_cagr_10y` | ratio | `(DilutedEPS_t / DilutedEPS_t-10)^(1/10) - 1` | | `shares_outstanding_cagr_3y` | ratio | `(Shares_end_t / Shares_end_t-3)^(1/3) - 1` | | `shares_outstanding_cagr_5y` | ratio | `(Shares_end_t / Shares_end_t-5)^(1/5) - 1` | | `shares_outstanding_cagr_10y` | ratio | `(Shares_end_t / Shares_end_t-10)^(1/10) - 1` | Notes: - A filing may not have every metric in this catalog. - Non-USD reporters (20-F / 40-F filings whose `reporting_currency` is e.g. `brl`, `eur`) report `free_cash_flow` and `market_cap` / `enterprise_value` in their local currency; the per-metric `unit` field carries the actual currency. ## `POST /metric/filings` **Purpose:** List filings for a ticker that have **metrics available**, returning one row per filing with identifiers you use as **`metric_group_id`** on other metric routes. **Request:** | Field | Type | Required | Notes | |-------|------|----------|--------| | `ticker` | string | Yes | 1–32 characters. | | `fiscal_year` | integer | Conditional | 1990–2100. You must supply **`fiscal_year`** **or** **`as_of_date`** (`YYYY-MM-DD`). | | `form_types` | array of string | No | Max **8** entries; each max **32** characters. | | `quarter` | string | No | Max **4** characters. | | `as_of_date` | string | No | `YYYY-MM-DD`: exclude filings filed after this date. | **Response:** | Field | Meaning | |-------|---------| | `credits_used` | Always **10** when successful. | | `fiscal_year` | Echo of request. | | `as_of_date` | Echo of request. | | `company` | Company profile (`ticker`, `jurisdiction`, `cik`, `legal_name`) or `null`. | | `metric_groups` | Array of objects; each includes `metric_group_id`, filing identity fields, dates, reporting currency, and optional amendment flags. | | `form_types`, `quarter` | Present only if you sent them in the request. | | `_warnings` | Optional; present when dates exclude all rows. | **Errors:** | HTTP | `error_code` | When | |------|----------------|------| | 400 | `METRICS_UNSUPPORTED_FOR_KR`, `_JP`, `_EU`, `_CN` | Computed metrics are available for US (SEC) companies; the ticker is a Korean, Japanese, European or China A-share company (not charged). | | 403 | `PLAN_TIER_INSUFFICIENT_COVERAGE` | The company is outside your plan's coverage scope. **Still debits 10 credits.** | | 402 | `CREDITS_INSUFFICIENT` | Insufficient credits. | | 422 | — | Validation (e.g. neither `fiscal_year` nor `as_of_date`). | **Example Request:** ```json { "ticker": "AAPL", "fiscal_year": 2024 } ``` **Example Response:** ```json { "credits_used": 10, "fiscal_year": 2024, "as_of_date": null, "company": { "ticker": "AAPL", "cik": "0000320193", "legal_name": "Apple Inc." }, "metric_groups": [ { "metric_group_id": 9876, "ticker": "AAPL", "form_type": "10-K", "fiscal_year": 2024, "quarter": "FY", "period_end": "2024-09-28", "filing_date": "2024-11-01", "reporting_currency": "USD" } ] } ``` ## `POST /metric/all` **Purpose:** Return the **full metrics object** for one filing, including realtime price-sensitive metrics when the caller supplies `current_price`, and optional **formula** overrides. **Filing selection:** exactly one of **`metric_group_id`** (from **`POST /metric/filings`**), **`filing_id`**, or **`ticker`** and **`fiscal_year`** with optional **`form_type`** (default **`10-K`**) and **`quarter`**. **Request:** | Field | Type | Default | Notes | |-------|------|---------|--------| | `metric_group_id` | integer | — | Conditional. 1–10⁹. | | `filing_id` | integer | — | Conditional. 1–10⁹. | | `ticker` | string | — | Conditional, with `fiscal_year`. 1–32 characters. | | `fiscal_year` | integer | — | Conditional, with `ticker`. 1990–2100. | | `form_type` | string | `10-K` | Only with `ticker` and `fiscal_year`. | | `quarter` | string | `null` | Only with `ticker` and `fiscal_year`. | | `as_of_date` | string | `null` | `YYYY-MM-DD`: exclude this filing if its filing date is after this date. | | `accept_suggested_formula` | boolean | `false` | When `true`, applies suggested formula hints included with the filing’s metrics (if any). | | `formula_override` | object | `null` | Per-metric overrides. **Keys are metric names** (e.g. `"operating_margin"`). Values are objects containing `"concepts"` (array of strings, **at most 50** entries per metric) and `"operators"` (array of strings, e.g. `["+", "-"]`, length must be exactly `len(concepts) - 1`). A lone top-level `{ "concepts": ... }` object is **invalid**. | | `current_price` | number | `null` | USD price used to compute realtime price-sensitive metrics (`market_cap`, `pe_ratio`, `enterprise_value`, `price_to_book`, `price_to_sales`, `price_to_cash_flow`, `ev_to_ebitda`, `ev_to_revenue`, `ev_to_fcf`, `fcf_yield`, `dividend_yield`, `buyback_yield`, `owner_earnings_yield`). Must be `> 0`, `≤ 10,000,000`, with at most **4 decimal places**. Pass the USD price as-is for all filings, including foreign-issuer ADRs. Invalid values return **HTTP 422** without charging credits. When omitted, the `realtime` block is replaced by `{ "status": "missing", "hint": "..." }` and the same hint appears in `_warnings`. | | `current_fx_rate` | number | `null` | Optional fallback FX rate (units of the filing's `reporting_currency` per 1 USD), used only when an up-to-date conversion rate is temporarily unavailable for foreign-issuer ADR filings. Must be `> 0`, `≤ 1,000,000`, with at most **6 decimal places**. Invalid values return **HTTP 422** without charging credits. | | `detail` | string | `"full"` | `"light"` leaves out each metric's `components`. See [Light and minimal views](#light-and-minimal-views). | **Response:** | Field | Meaning | |-------|---------| | `credits_used` | **158**. | | `metric_group_id` | The metric group ID actually used (may be `null` if excluded by `as_of_date`). | | `valuation_context` | Echo of flags and formula inputs. | | `ticker`, `form_type`, `fiscal_year`, `quarter`, `cik`, `source_accession`, `primary_document`, `source_url_prefix` | Filing identity and SEC base URL. `source_url_prefix` may be `null`; combine it with each fact’s `source_locator` (see below) to build the SEC viewer URL. | | `segments` | Array of segment data. | | `price_insensitive_metrics` | Object containing metrics that do not depend on stock price. Within each metric, nested `fact_refs` / `components` entries that expose `fact_id` also expose **`source_locator`** (may be `null`). | | `price_sensitive_metrics` | Object containing metrics that depend on stock price: a `filing_date_price` + `historical` pair (the metrics computed from the filing-date stock price) and, when the filing has price-sensitive metrics, a `realtime` sub-object (computed from the request's `current_price`; when realtime cannot be computed it is `{ "status": "missing" \| "missing_fx_fallback", "hint": "..." }`). For foreign-issuer ADR filings each computed metric carries a `price_used` block — see [Response conventions](#response-conventions). Same `source_locator` convention on nested fact references where `fact_id` is present. **[`POST /metric/all/filing-date`](#post-metricallfiling-date)** returns the filing-date block only. | | `price_context` | Present whenever the response would include a `realtime` block. `status` is `"ok"` (price applied), `"missing"` (no `current_price` supplied), or `"missing_fx_fallback"` (foreign-issuer filing and an up-to-date conversion rate is temporarily unavailable). When `ok`, also includes `price`, `price_date`, `source: "user_supplied"`, and `fx_fallback_used: true` if the caller-supplied `current_fx_rate` was used because an up-to-date rate was unavailable. `mode` is always present; on the two non-`ok` statuses a `message` states what to send. | | `ttm_composite`, `dei_corrected` | Optional root fields, present when the filing has them. | | `amended` | Present (`true`) when this filing had a later amendment merged in. The returned metric values are already the amended figures. | | `corporate_actions` | Optional root field, present when the ticker has corporate action events in the lookback window. Contains `events_in_lookback` and `events_after_period_end` (relative to this filing's period end); each event carries `ex_date`, `ratio`, `type` (`forward` / `reverse`), `event_type` (e.g. `stock_split`, `stock_dividend`), `affects_total_shares`, `affects_holder_share_count`, and `relevant_to_metrics`. Also carries `adjustment_factor_to_today` (factor converting this filing's per-share basis to the current basis), `adjustment_factor_anchor` (the date the factor is anchored on), and `adjustment_factor_anchor_basis` (how the anchor is chosen; `period_end`). When `adjustment_factor_to_today` is not `1`, three per-share metrics — `pe_ratio`, `dividend_yield`, `eps_growth_yoy` — additionally carry `adjusted_value`, `adjustment_factor`, and `comparable_to_current_basis`, so values from this filing can be compared on the current per-share basis; when it is `1` the filing is already on that basis and those three fields are absent. Total values (revenue, market_cap, etc.) are unaffected. Tickers with no events in the window omit the field entirely. | | `_warnings` | Optional; warnings about amendments or formulas. | **Errors:** Errors before the charge (not charged): | HTTP | `error_code` | When | |------|----------------|------| | 404 | `METRIC_GROUP_NOT_FOUND` | Unknown `metric_group_id`. | | 404 | `DATA_FILING_NOT_FOUND` | No filing for the given `filing_id` or `ticker` + `fiscal_year`. | | 400 | `DATA_FILING_QUARTER_REQUIRED` | Several filings match without a quarter; message lists available quarters. | | 404 | `METRIC_SUMMARY_NOT_FOUND` | Filing has no metrics summary. | | 400 | `METRICS_UNSUPPORTED_FOR_KR`, `_JP`, `_EU`, `_CN` | The ticker is a Korean, Japanese, European or China A-share company. | | 403 | `PLAN_TIER_INSUFFICIENT_HISTORY` | `fiscal_year` is before your plan's history window. | | 403 | `PLAN_TIER_INSUFFICIENT_COVERAGE` | The company, named by `ticker`, is outside your plan's coverage scope. | | 403 | `PLAN_TIER_INSUFFICIENT` | The filing, named by `metric_group_id` or `filing_id`, is outside your plan. | | 403 | `PLAN_TIER_INSUFFICIENT_FORMULA_OVERRIDE` | `formula_override` below the Pro plan. | | 402 | `CREDITS_INSUFFICIENT` | Insufficient credits. | | 422 | `VALIDATION_ERROR` | Filing selection (`Provide exactly one of: metric_group_id, filing_id, or both ticker and fiscal_year.`, `form_type and quarter can only be used with ticker and fiscal_year.`); `current_price` is non-numeric, non-finite, `≤ 0`, `> 10,000,000`, or has more than 4 decimal places; **or** `current_fx_rate` is non-numeric, non-finite, `≤ 0`, `> 1,000,000`, or has more than 6 decimal places. | Errors after the charge (**charged 158**, `detail.credits_used`): | HTTP | `error_code` | When | |------|----------------|------| | 404 | `METRIC_SUMMARY_OBJECT_MISSING` | The metrics summary could not be retrieved. | | 500 | `METRIC_SUMMARY_INVALID_FORMAT` | The metrics summary data is invalid. | | 409 | `METRIC_FORMULA_OVERRIDE_INVALID` | Invalid `formula_override`. | | 422 | `METRIC_FORMULA_APPLY_FAILED` | Formula application failed. | **Example Request:** ```json { "metric_group_id": 12345, "current_price": 225.0, "formula_override": { "operating_margin": { "concepts": ["us-gaap_GrossProfit", "us-gaap_SellingGeneralAndAdministrativeExpense"], "operators": ["-"] } } } ``` **Example Response:** ```json { "credits_used": 158, "metric_group_id": 12345, "valuation_context": { "as_of_date": null, "accept_suggested_formula": false, "formula_override": null }, "ticker": "AAPL", "form_type": "10-K", "fiscal_year": 2024, "quarter": "FY", "cik": "0000320193", "source_accession": "0000320193-24-000123", "primary_document": "aapl-20240928.htm", "source_url_prefix": "https://www.sec.gov/ix?doc=/Archives/edgar/data/.../aapl-20240928.htm", "segments": [], "price_insensitive_metrics": { "revenue": { "value": 383285000000.0, "unit": "USD" } }, "price_sensitive_metrics": { "realtime": { "market_cap": { "value": 3404250000000.0, "unit": "USD" } } }, "price_context": { "mode": "user_supplied", "status": "ok", "price": 225.0, "price_date": "2026-05-18", "source": "user_supplied" }, "_warnings": [] } ``` **Example Response (filing affected by a stock split):** ```json { "ticker": "NVDA", "fiscal_year": 2025, "quarter": "Q1", "corporate_actions": { "events_after_period_end": [ { "ex_date": "2024-06-10", "ratio": 10.0, "type": "forward", "event_type": "stock_split", "affects_total_shares": true, "affects_holder_share_count": true, "relevant_to_metrics": true } ], "events_in_lookback": [ { "ex_date": "2021-07-20", "ratio": 4.0, "type": "forward", "event_type": "stock_split", "affects_total_shares": true, "affects_holder_share_count": true, "relevant_to_metrics": true }, { "ex_date": "2024-06-10", "ratio": 10.0, "type": "forward", "event_type": "stock_split", "affects_total_shares": true, "affects_holder_share_count": true, "relevant_to_metrics": true } ], "adjustment_factor_to_today": 10.0, "adjustment_factor_anchor": "2024-04-28", "adjustment_factor_anchor_basis": "period_end" }, "price_sensitive_metrics": { "realtime": { "pe_ratio": { "value": 24.25, "adjusted_value": 2.43, "adjustment_factor": 10.0, "comparable_to_current_basis": false } } } } ``` ## `POST /metric/all/filing-date` **Purpose:** Same metrics bundle as **[`POST /metric/all`](#post-metricall)**, with only the filing-date price block. **Request:** Same body fields as **`POST /metric/all`** *minus* `current_price` and `current_fx_rate`, with the same filing selection. | Field | Type | Default | Notes | |-------|------|---------|--------| | `metric_group_id`, `filing_id`, `ticker`, `fiscal_year`, `form_type`, `quarter` | | | Filing selection, same as **`POST /metric/all`**. | | `as_of_date` | string | `null` | Same as **`POST /metric/all`**. | | `accept_suggested_formula` | boolean | `false` | Same as **`POST /metric/all`**. | | `formula_override` | object | `null` | Same as **`POST /metric/all`**. | | `detail` | string | `"full"` | Same as **`POST /metric/all`**. See [Light and minimal views](#light-and-minimal-views). | **Note on realtime-only fields:** Sending `current_price` or `current_fx_rate` returns **`422 VALIDATION_ERROR`** (`type: extra_forbidden`) without charging credits. **Response:** Same shape as **`POST /metric/all`**, with `price_sensitive_metrics` holding `filing_date_price` + `historical` and no `price_context`. **Credits:** **158**, as **`POST /metric/all`**. **Errors:** Same as **`POST /metric/all`**. **Example Request:** ```json { "metric_group_id": 12345 } ``` ## `POST /metric/items` **Purpose:** Same sourcing as **`POST /metric/all`**, but returns **only** the metric names you list. **Request:** Same as **`POST /metric/all`**, plus: | Field | Type | Required | Notes | |-------|------|----------|--------| | `metric_names` | array of string | Yes | 1–100 names from the [catalog](#supported-metric-catalog); each max **256** characters. | | `detail` | string | No | Same as **`POST /metric/all`**. See [Light and minimal views](#light-and-minimal-views). | **Credits:** **158**, when at least one name is in the catalog. **Response:** | Field | Meaning | |-------|---------| | `credits_used` | **158**. | | `metric_group_id` | The metric group ID actually used. | | `valuation_context` | Echo of flags, formula inputs, and requested `metric_names`. | | `ticker`, `form_type`, `fiscal_year`, `quarter`, `cik`, `source_accession`, `primary_document`, `source_url_prefix` | Filing identity and SEC base URL. `source_url_prefix` may be `null`; combine it with each fact’s `source_locator` (see below) to build the SEC viewer URL. | | `price_insensitive_metrics` | Object containing the requested price-insensitive metrics. Nested `fact_refs` / `components` entries with `fact_id` also expose **`source_locator`** (may be `null`). | | `price_sensitive_metrics` | Object containing a `filing_date_price` + `historical` pair (the requested price-sensitive metrics computed from the filing-date stock price; `historical` is `{}` when none were requested) and, when price-sensitive metrics were requested, a `realtime` sub-object. The `realtime` sub-object follows the same convention as [`POST /metric/all`](#post-metricall): metric rows when `current_price` is supplied, `{ "status": "missing", "hint": "..." }` otherwise. Same `source_locator` convention on nested fact references where `fact_id` is present. | | `price_context` | Present whenever the response would include a `realtime` block (same shape as in [`POST /metric/all`](#post-metricall)). | | `segments` | Array of segment data. | | `ttm_composite`, `dei_corrected` | Optional root fields, present when the filing has them. | | `corporate_actions` | Optional root field; same shape and semantics as in [`POST /metric/all`](#post-metricall). The same per-metric split variants appear on `pe_ratio` / `dividend_yield` / `eps_growth_yoy` when you request them. | | `_metric_name_errors`, `_supported_metric_names`, `_supported_metric_names_note` | Present when some requested names are outside the catalog or not in this filing: one line per such name, plus every supported name. | | `_warnings` | Optional; warnings about amendments or formulas. | **Errors:** Same as **`POST /metric/all`**, plus: | HTTP | `error_code` | When | |------|----------------|------| | 400 | `METRIC_INVALID_METRIC_NAME` | No requested name is in the catalog; `detail` lists every supported name in `_supported_metric_names`. Not charged. | **Example Request:** ```json { "metric_group_id": 12345, "metric_names": ["gross_margin", "net_margin"] } ``` **Example Response:** ```json { "credits_used": 158, "metric_group_id": 12345, "valuation_context": { "as_of_date": null, "accept_suggested_formula": false, "formula_override": null, "metric_names": ["gross_margin", "net_margin"] }, "ticker": "AAPL", "form_type": "10-K", "fiscal_year": 2024, "quarter": "FY", "cik": "0000320193", "source_accession": "0000320193-24-000123", "primary_document": "aapl-20240928.htm", "source_url_prefix": "https://www.sec.gov/ix?doc=/Archives/edgar/data/.../aapl-20240928.htm", "price_insensitive_metrics": { "gross_margin": { "value": 0.4621, "unit": "ratio" }, "net_margin": { "value": 0.2397, "unit": "ratio" } }, "price_sensitive_metrics": { "filing_date_price": 259.48, "historical": {} } } ``` ## `POST /metric/historical` **Purpose:** Return metrics for **many periods** (quarterly or annual) for one ticker, **paginated**. Price-sensitive values use **filing-date figures only** (no live market refresh). **Request:** | Field | Type | Default | Notes | |-------|------|---------|--------| | `ticker` | string | — | **Required.** 1–32 characters. | | `period_type` | string | `quarterly` | Either **`quarterly`** or **`annual`**. `annual` covers `10-K` plus the foreign-issuer annual reports `20-F` and `40-F`; `quarterly` covers `10-Q` only (foreign issuers have no quarterly counterpart). | | `start_period_start` | string | `null` | Optional filter: period start **ISO date** (`YYYY-MM-DD`). | | `end_period_end` | string | `null` | Optional filter: same date rules. | | `metric_names` | array | `null` | If omitted or null, **all** metrics returned for each period; if set, only those names from the [catalog](#supported-metric-catalog). Max **100** names. | | `as_of_date` | string | `null` | Same meaning as **`/metric/all`**. | | `accept_suggested_formula` | boolean | `false` | | | `formula_override` | object | `null` | Same structure rules as **`/metric/all`** (including **≤ 50** `concepts` per metric). | | `sort` | string | `period_end_asc` | **`period_end_asc`** or **`period_end_desc`**. | | `page` | integer | `1` | Page index, 1–10⁶. | | `page_size` | integer | `3` | 1–**5** (maximum page size). | | `detail` | string | `"full"` | Same as **`POST /metric/all`**, applied to every `periods[*]`. See [Light and minimal views](#light-and-minimal-views). | **Credits:** **55** (base) **+ 148 × (number of filing rows on the current page)**. If the base debit succeeds but the per-row debit fails, you receive **`402`** with `credits_used: 55`, every matching filing in `metric_groups` (same shape as [`POST /metric/filings`](#post-metricfilings), not paged) and `company`. **Response:** | Field | Meaning | |-------|---------| | `page`, `page_size`, `total_items`, `has_more`, `next_page` | Paging; `next_page` is `null` on the last page. | | `credits_used` | Number of credits deducted for this request. | | `ticker` | The company's symbol. | | `query_context` | Echo of the request parameters used for the query. | | `periods` | Array of period objects. Each includes filing metadata (including **`source_url_prefix`** per period, may be `null`), `price_insensitive_metrics`, `price_sensitive_metrics` (each a map of metric name to metric object, at the filing-date price), and optional root meta fields. Within each metric object, `fact_refs` / `components` entries that expose `fact_id` also expose **`source_locator`** (may be `null`). Each period may carry its own **`corporate_actions`** field, an **`amended`** flag (`true` when that period's filing had a merged amendment), and per-metric split variants as described in [`POST /metric/all`](#post-metricall); when comparing a per-share metric across periods that straddle a split, use `adjusted_value` instead of raw `value`. | | `_warnings` | Optional; warnings about amendments or formulas. | **Errors:** | HTTP | `error_code` | When | |------|----------------|------| | 400 | `METRIC_INVALID_METRIC_NAME` | A name in `metric_names` is outside the catalog; `detail` lists every supported name in `_supported_metric_names`. Not charged. | | 400 | `METRIC_INVALID_METRIC_NAME` | A returned period lacks a requested name. **Charged** (`detail.credits_used`). | | 400 | `METRICS_UNSUPPORTED_FOR_KR`, `_JP`, `_EU`, `_CN` | The ticker is a Korean, Japanese, European or China A-share company (not charged). | | 403 | `PLAN_TIER_INSUFFICIENT_FORMULA_OVERRIDE` | `formula_override` below the Pro plan (not charged). | | 403 | `PLAN_TIER_INSUFFICIENT_COVERAGE` | The company is outside your plan's coverage scope (not charged). | | 402 | `CREDITS_INSUFFICIENT` | Insufficient credits for base or per-row charges. | | 404 | `METRIC_SUMMARY_OBJECT_MISSING` | The metrics summary could not be retrieved. **Charged** (`detail.credits_used`). | | 500 | `METRIC_SUMMARY_INVALID_FORMAT` | The metrics summary data is invalid. **Charged** (`detail.credits_used`). | | 409 | `METRIC_FORMULA_OVERRIDE_INVALID` | Invalid `formula_override`. **Charged** (`detail.credits_used`). | | 422 | `METRIC_FORMULA_APPLY_FAILED` | Formula application failed. **Charged** (`detail.credits_used`). | | 422 | `VALIDATION_ERROR` | Validation (`period_type`, `sort`, limits). | **Example Request:** ```json { "ticker": "AAPL", "period_type": "quarterly", "page": 1, "page_size": 2 } ``` **Example Response:** ```json { "page": 1, "page_size": 2, "total_items": 10, "has_more": true, "next_page": 2, "credits_used": 351, "ticker": "AAPL", "query_context": { "period_type": "quarterly", "start_period_start": null, "end_period_end": null, "as_of_date": null, "accept_suggested_formula": false, "formula_override": null, "metric_names": null, "sort": "period_end_asc" }, "periods": [ { "metric_group_id": 9876, "period_start": "2024-07-01", "period_end": "2024-09-28", "filing_date": "2024-11-01", "ticker": "AAPL", "form_type": "10-K", "fiscal_year": 2024, "quarter": "Q4", "cik": "0000320193", "source_accession": "0000320193-24-000123", "primary_document": "aapl-20240928.htm", "source_url_prefix": "https://www.sec.gov/ix?doc=/Archives/edgar/data/.../aapl-20240928.htm", "segments": [], "price_insensitive_metrics": { "revenue": { "value": 94930000000.0, "unit": "USD" } }, "price_sensitive_metrics": { "market_cap": { "value": 3300000000000.0, "unit": "USD" } } } ] } ``` ## Category endpoints (`/metric/`) Seven endpoints returning curated metric sets — margins, growth, leverage, efficiency, cash-flow, valuation. Flat **158 credits**, rate limit **60/minute**. | Endpoint | Metrics returned | |---|---| | `POST /metric/profitability` | `gross_margin`, `operating_margin`, `net_margin`, `ebitda_margin`, `return_on_equity`, `return_on_assets`, `return_on_invested_capital`, `return_on_tangible_equity`, `fcf_margin`, `nopat`, `nopat_reported_oi_proxy`, `nopat_margin`, `return_on_net_operating_assets`, `owner_earnings_estimate`, `owner_earnings_cash_proxy`, `owner_earnings_per_share` (16) | | `POST /metric/growth` | `revenue_growth_yoy`, `revenue_growth_qoq`, `revenue_growth_qoq_single_quarter`, `eps_growth_yoy`, `net_income_growth_yoy`, `fcf_growth_yoy`, `revenue_cagr_3y`, `revenue_cagr_5y`, `revenue_cagr_10y`, `diluted_eps_cagr_3y`, `diluted_eps_cagr_5y`, `diluted_eps_cagr_10y`, `shares_outstanding_cagr_3y`, `shares_outstanding_cagr_5y`, `shares_outstanding_cagr_10y` (15) | | `POST /metric/financial-health` | `debt_to_equity`, `debt_to_assets`, `debt_to_ebitda`, `interest_coverage`, `current_ratio`, `quick_ratio`, `cash_ratio`, `net_debt`, `net_debt_to_ebitda`, `net_financial_obligations`, `net_financial_expense_after_tax` (11) | | `POST /metric/efficiency` | `asset_turnover`, `inventory_turnover`, `receivables_turnover`, `days_inventory`, `days_receivable`, `days_payable`, `cash_conversion_cycle`, `payables_turnover`, `net_operating_assets`, `net_operating_asset_turnover` (10) | | `POST /metric/cash-flow` | `free_cash_flow`, `fcf_margin`, `payout_ratio`, `free_cash_flow_per_share`, `free_cash_flow_after_sbc`, `fcf_ex_sbc_addback`, `free_cash_flow_cagr_3y`, `free_cash_flow_cagr_5y`, `free_cash_flow_cagr_10y`, `free_cash_flow_per_share_cagr_3y`, `free_cash_flow_per_share_cagr_5y`, `free_cash_flow_per_share_cagr_10y`, `cfo_to_net_income`, `fcf_to_net_income`, `cash_distributions_to_fcf`, `common_dividend_burden_on_group_fcf`, `sbc_to_revenue`, `sbc_to_fcf` (18 — `fcf_margin` also in `/metric/profitability`) | | `POST /metric/valuation` | All 13 price-sensitive ratios: `market_cap`, `enterprise_value`, `pe_ratio`, `price_to_book`, `price_to_sales`, `price_to_cash_flow`, `ev_to_ebitda`, `ev_to_revenue`, `ev_to_fcf`, `fcf_yield`, `dividend_yield`, `buyback_yield`, `owner_earnings_yield`. Accepts `current_price` for realtime; returns both `realtime` and `filing_date_price` blocks. | | `POST /metric/valuation/filing-date` | Same 13 valuation ratios as above but **only** the filing-date price block — `current_price` and `current_fx_rate` are rejected with `422 VALIDATION_ERROR`. | **Request body** (5 simple categories + `/metric/valuation`): the filing selection of [`POST /metric/all`](#post-metricall) (`metric_group_id`, `filing_id`, or `ticker` + `fiscal_year`). Optional: `accept_suggested_formula`, `formula_override`, `as_of_date`, `current_price`, `current_fx_rate`, `detail` — same semantics as on [`POST /metric/all`](#post-metricall). `metric_names` is **not** accepted (the category fixes the metric set; sending it returns `422 VALIDATION_ERROR`). **Request body** (`/metric/valuation/filing-date`): same as above minus `current_price` / `current_fx_rate` — see [`POST /metric/all/filing-date`](#post-metricallfiling-date). `detail` is accepted on this endpoint as well. **Response shape:** `ticker`, `form_type`, `fiscal_year`, `quarter`, `cik`, `source_accession`, `primary_document`, `metric_group_id`, `source_url_prefix`, `valuation_context`, `segments`, `price_insensitive_metrics`, `price_sensitive_metrics`, `credits_used`, plus the conditional `price_context` and the optional root fields `ttm_composite`, `dei_corrected`, `corporate_actions` and `_warnings`. When some of the category's metrics are not in this filing, the response also carries `_metric_name_errors`, `_supported_metric_names` and `_supported_metric_names_note` (still 158 credits). For `/metric/valuation` and `/metric/valuation/filing-date` the `price_insensitive_metrics` block is always `{}` (all 13 valuation ratios are price-sensitive). **Errors:** same as [`POST /metric/all`](#post-metricall). ## `POST /screener/metrics` **Purpose:** Return filings that match a DSL filter tree, grouped by company (default) or flattened. Query the universe of US-listed filers by composing metric conditions ("ROE > 20% for the last 5 years AND PE < 20"). Supports OR/NOT, time-window modifiers (`for_latest` / `for_consecutive` / `for_at_least`), 1–120 period lookback, USD-normalized values for ADR foreign filers, and paging up to 500 cumulative results. > **Plan-tier gate:** `POST /screener/metrics`, `POST /screener/ownership`, `POST /screener/initial-holdings`, `POST /screener/institutional-holdings` and `POST /screener/events` require the **Pro plan or higher**; Free / Starter callers receive `403 PLAN_TIER_INSUFFICIENT` (see [API key, account, and plan errors](#api-key-account-and-plan-errors)). [`GET /screener/metrics/filters`](#get-screenermetricsfilters) requires the **Starter plan or higher**. > **Pricing note:** Filters that touch price-sensitive metrics (`market_cap`, `enterprise_value`, all 13 valuation ratios) use the price observed on each filer's filing date; these dates differ across filers. **Request body** (unknown fields return 422): | Field | Type | Default | Notes | |---|---|---|---| | `as_of_date` | ISO date | today (UTC) | Must be ≤ today. Filings with `filing_date > as_of_date` are excluded. | | `lookback` | int 1–120 | 1 | Most recent N filings per company within scope. | | `include_quarterly` | bool | `false` | `false` → annual only (10-K / 20-F / 40-F). `true` adds 10-Q. | | `tickers` | string[] | omitted | Whitelist, max 100. Case-insensitive (normalized to upper). Empty or omitted = full universe. | | `exclude_tickers` | string[] | `[]` | Blacklist, max 100. | | `usd_only` | bool | `false` | When `true`, exclude foreign-currency reporters. | | `sectors` | string[] | omitted | Restrict the universe to these canonical sector buckets (the 12 in [Industry classification (Pro+)](#industry-classification-pro)). Omitted = no sector restriction. | | `where.filter` | DSL tree | (required) | See [Filter DSL (`/screener/metrics`)](#filter-dsl-screenermetrics). Leaf count 1–10, nesting depth ≤ 4. | | `where.sort_by` | string | see [Filter DSL (`/screener/metrics`)](#filter-dsl-screenermetrics) | Metric name, `"ticker"`, `"period_end"`, `"filing_date"`, or `"match_count"`. | | `where.sort_order` | `"asc"` \| `"desc"` | `"asc"` | | | `include_metrics_using_filing_date_price` | bool | `true` | `false` rejects price-sensitive metrics in `filter` / `sort_by` / `include_metrics`. | | `exclude_derivations` | string[] | `[]` | Subset of `derived`, `as_reported`, `composite`, `class_sum`, `segment_sum`, `company_override`, `proxy_substituted`, `TTM_rollforward`. | | `include_metrics` | string[] | `[]` | Extra metric names (≤ 10) to include in the response beyond filter-referenced ones. | | `group_by_ticker` | bool | `true` | `true` → grouped by company with nested `filings[]`. `false` → flat per-filing rows. | | `page` | int ≥ 1 | 1 | 1-indexed. | | `page_size` | int 1–100 | 50 | Counts companies (when grouped) or filings (when flat). | | `detail` | string | `"full"` | `"light"` leaves out each company's `classification.source.url` and the `lookback_applied` and `include_quarterly_applied` echoes. See [Response detail](#response-detail). | **Pagination cap:** `page × page_size ≤ 500` (422 above it). When the next page would pass the cap, `has_more` is `false`, `next_page` is `null`, and `_warnings` says the limit was reached. **Response (`group_by_ticker=true`, default):** ```json { "page": 1, "page_size": 50, "has_more": true, "next_page": 2, "as_of_date_applied": "2024-12-31", "lookback_applied": 5, "include_quarterly_applied": false, "results": [ { "ticker": "AAPL", "match_count": 5, "filings": [ { "metric_id": 46, "form_type": "10-K", "fiscal_year": 2024, "quarter": "FY", "period_end": "2024-09-28", "filing_date": "2024-11-01", "reporting_currency": "usd", "metrics": { "return_on_equity": {"value": 1.5774, "derivation": "derived", "unit": "ratio"}, "pe_ratio": {"value": 33.21, "derivation": "derived", "unit": "ratio", "price_date": "2024-11-01"}, "market_cap": {"value": 3.37e12, "derivation": "as_reported", "unit": "usd", "price_date": "2024-11-01"} } } /* T-1, T-2, … up to lookback filings within company */ ] } ], "credits_used": 242 } ``` **Response (`group_by_ticker=false`):** identical envelope, but `results[]` is a flat list of `{ticker, metric_id, form_type, fiscal_year, quarter, period_end, filing_date, reporting_currency, metrics}` — one row per matching filing. For **Pro+** callers each `results[]` entry (grouped or flat) also carries an industry **`classification`** block when the company has one — see [Industry classification (Pro+)](#industry-classification-pro). **`match_count`** is the number of filings within `lookback` that satisfy the **whole** filter tree on a per-filing basis (using each filing's own metric values). **Foreign-currency filers (ADRs)** carry `fx_rate_used` + `currency` on FX-converted metric entries: ```json "market_cap": { "value": 2.42e11, // USD-converted from JPY "derivation": "as_reported", "unit": "usd", "currency": "jpy", "fx_rate_used": 145.2, "price_date": "2024-06-30" } ``` All screener filtering, sorting, and comparison use the USD-converted value. USD reporters omit `fx_rate_used` and `currency`. **Within-company `filings[]` ordering** is `filing_date DESC, period_end DESC` (newest first). For time-series ordering, use `group_by_ticker=false` with `sort_by="period_end"` or `"filing_date"`. **Errors:** `422 VALIDATION_ERROR` (schema; a metric name outside the catalog also returns `_supported_metric_names`), `402 CREDITS_INSUFFICIENT`, `403 PLAN_TIER_INSUFFICIENT` below Pro, **`504 QUERY_TIMEOUT`** when the query exceeds the 30-second server timeout (charged). **Example Request:** ```json { "tickers": ["NVDA", "AMD", "AVGO", "QCOM", "TXN", "INTC", "MU", "ADI"], "lookback": 4, "include_quarterly": true, "where": { "filter": { "metric": "gross_margin", "op": ">", "value": 0.5, "for_latest": 4 }, "sort_by": "gross_margin", "sort_order": "desc" }, "page_size": 20 } ``` ### Filter DSL (`/screener/metrics`) #### Leaf node ```json {"metric": "", "op": "", "value": , "for_latest": | "for_consecutive": | "for_at_least": } ``` | Operator | Value shape | Notes | |---|---|---| | `>`, `>=`, `<`, `<=` | single number | | | `between` | `[lo, hi]` (`lo ≤ hi`) | Inclusive on both ends. | `=` and `!=` are not supported. `value` must be numeric. `null` is rejected. Filings where the metric value is missing are excluded from filter comparisons (no synthetic match). #### Temporal modifiers (mutually exclusive, at most one per leaf) | Modifier | Meaning | |---|---| | *(none)* | Latest filing in `lookback` must satisfy. Equivalent to `for_latest: 1`. | | `for_latest: N` | Most recent N filings (right-anchored) all satisfy. | | `for_consecutive: N` | Some N adjacent filings within `lookback` all satisfy (sliding window over `filing_date`). | | `for_at_least: N` | At least N filings within `lookback` satisfy (any positions). | `N ≥ 1` and `N ≤ lookback`. Tickers without enough filings in `lookback` to evaluate the modifier are filtered out. #### Composite nodes ```json {"and": [, , …]} {"or": [, , …]} {"not": } ``` `where.filter` may itself be a bare leaf (no wrapper required for single-condition queries). #### Limits - Leaf nodes total: **1–10** (0 → rejected as "filter required"; >10 → rejected as "too complex") - Nesting depth: **≤ 4** - `include_metrics` length: **≤ 10** - `tickers`, `exclude_tickers`: each **≤ 100** entries ### Credit formula (`/screener/metrics`) `POST /screener/metrics` charges per call (paginate ⇒ each page bills independently): ```text title="Formula" credits = max(65, 425 − tickerDiscount // ceil(200 × (100 − n_tickers) / 100); 0 (whole universe, or ≥ 100 tickers) … 198 (1 ticker) − lookbackDiscount // 0 (lookback ≥ 30) … 78 (lookback = 1) − quarterlyDiscount // 60 when include_quarterly=false, else 0 + lookbackSurcharge // 0 (lookback ≤ 30) … 240 (lookback = 120) + filterSurcharge // 40 × (leaves − 1), 0 … 360 + temporalSurcharge // per-leaf 60 (for_latest / for_at_least) or 100 (for_consecutive), capped 600 + includeMetricsSurcharge) // 20 × |include_metrics \ filter_metrics|, 0 … 200 ``` Examples: | Scenario | Credits | |---|---| | 1 ticker, lookback=1, annual only, 1 leaf (best case) | **89** | | Whole universe, lookback=30, quarterly+annual, 1 leaf | **425** | | 2 tickers, lookback=5, annual, 2 leaves, 1 `for_latest`, 2 extra `include_metrics` | **242** | | Whole universe, lookback=120 (Business or Enterprise plan), 10 leaves all `for_consecutive`, 10 extra include_metrics | **1825** (worst case) | `lookback` is priced after it is clamped to your plan's history window. **Charge applies even when `results` is empty, and on `504 QUERY_TIMEOUT`**. Errors returned before the charge (`422`, `402`, `403`, authentication errors, `429`) are not charged. `GET /screener/metrics/filters` is free. ## `GET /screener/metrics/filters` **Purpose:** Discovery — returns the supported metric catalog, operators, temporal modifiers, form types, derivations, sectors, and one complete example request. **0 credits.** Requires the **Starter plan or higher**. ```json { "metrics": [ {"name": "return_on_equity", "unit": "ratio", "price_sensitive": false}, {"name": "market_cap", "unit": "usd", "price_sensitive": true} /* ... 82 total ... */ ], "operators": ["<", "<=", ">", ">=", "between"], "temporal_modifiers": ["for_latest", "for_consecutive", "for_at_least"], "form_types": ["10-K", "10-Q", "20-F", "40-F"], "derivations": ["TTM_rollforward", "as_reported", "class_sum", "company_override", "composite", "derived", "proxy_substituted", "segment_sum"], "sectors": ["Technology", "Healthcare", "Finance", "Consumer Discretionary", "Consumer Staples", "Communications", "Industrials", "Energy", "Utilities", "Materials", "Real Estate", "Other"], "example_request": { /* full POST /screener/metrics body */ }, "credits_used": 0 } ``` `sectors` lists the 12 canonical buckets accepted by the `POST /screener/metrics` `sectors` filter ([Industry classification (Pro+)](#industry-classification-pro)); it is `null` below the Pro plan. ## Transaction object Insider trades (Form 4), initial beneficial-ownership statements (Form 3), and institutional holdings reports (Form 13F) reported to the SEC. US filings only. For the Form 4 / Form 3 endpoints, the plan coverage scope ([Coverage scope notice](#coverage-scope-notice)) and history window ([History truncation notice](#history-truncation-notice)) apply as they do elsewhere, on the filing's `filing_date`; the 13F endpoints are organized by the filing **manager** (institution). These endpoints are available on every plan; full-library screening is [`POST /screener/ownership`](#post-screenerownership), [`POST /screener/initial-holdings`](#post-screenerinitial-holdings) and [`POST /screener/institutional-holdings`](#post-screenerinstitutional-holdings), which require **Pro or higher**. Credits are deducted before the query runs, so a `404` or `403` raised afterwards is still charged. Returned by `POST /ownership/transactions`, `POST /ownership/transaction-ids`, and `POST /screener/ownership`. | Field | Meaning | |-------|---------| | `id` | Transaction id. Pass to `POST /ownership/transaction-ids`. | | `is_derivative` | Derivative table row (`true`) or non-derivative (`false`). | | `transaction_form_type` | `"4"` or `"5"`. | | `transaction_date`, `transaction_code` | As filed. | | `transaction_type` | Official SEC name for `transaction_code`. | | `transaction_type_group` | One of the five SEC groupings — see [`GET /ownership/transaction-types`](#get-ownershiptransaction-types). | | `acquired_disposed_code` | `"A"` acquired, `"D"` disposed, or `null`. The trade's direction. | | `shares`, `price_per_share`, `transaction_value`, `shares_owned_following` | As filed. `transaction_value` may be `null` or `0`. | | `transaction_note` | Filer-side note explaining a `null` / `0` value. `null` when absent. | | `principal_amount_not_shares` | `true` when `shares` holds a debt principal amount. | | `security_title`, `direct_or_indirect`, `nature_of_ownership` | As filed. | | `footnote_refs` | Footnote ids for this transaction. Resolve against the filing's `footnotes` map. | | `source_locator` | Combine with the filing's `source_url_prefix` to build the SEC URL. | | `restated` | `null`, `"cancelled"`, `"modified"`, or `"added"` — set when an amendment changed this transaction. | | `prior` | Present only when `restated` is set. The pre-amendment values. | | `split_adjusted` | Present only when the filed values are not on the current per-share basis. See below. | | `data_quality_flags` | Present only when at least one rule fires. See below. | Derivative rows additionally carry `conversion_or_exercise_price`, `exercise_date`, `expiration_date`, `underlying_security_title`, `underlying_security_shares`, `underlying_security_value`, and `value_owned_following`. ### `split_adjusted` `shares` and `price_per_share` are in the units of the transaction's own trade date. When those differ from the current per-share basis, the block is present: ```json "split_adjusted": { "shares": 4000.0, "price_per_share": 125.86, "shares_owned_following": 48000.0, "underlying_security_shares": null, "conversion_or_exercise_price": null, "split_adjustment_factor": 4.0 } ``` Absent means the filed values are on the current per-share basis. A field is `null` when the split does not change it (for example a debt principal). `split_adjustment_factor` carries the same meaning as `adjustment_factor` on the metrics API ([`POST /metric/all`](#post-metricall)). ### `data_quality_flags` Rows that fail a consistency check carry one or more of: `future_transaction_date`, `future_deemed_execution_date`, `zero_price_open_market`, `derivative_date_order`, `negative_shares`, `negative_price`, `negative_transaction_value`, `negative_shares_owned_following`, `value_mismatch`, `manual_flags`. Rows flagged `manual_flags` also carry a `manual_flags` array of `{code, note}` entries describing the issue. Flagged rows are excluded from `POST /ownership/transactions`, `POST /ownership/stats` and `POST /screener/ownership` unless `include_anomalies=true` (`trade_filters.include_anomalies` on the screener). Each endpoint reports how many it withheld: the listing in `anomalies_excluded_on_page` (this page only), stats and the screener in `anomalies_excluded_count` (the whole requested range). ### `computed` `POST /screener/ownership` rows additionally carry a `computed` block with `shares_owned_before` and `own_pct_change`. Each entry has `value`, `status` (`ok` / `unavailable`), `unit`, `formula`, `computed_as`, and `fact_refs` pointing at the inputs. When an input is missing, the entry has only `value` (`null`), `status` (`"unavailable"`) and `computed_as`, which states the reason. ## `POST /ownership/transactions` **Purpose:** Anchored listing of insider-trade filings and their transactions. Requires `ticker` (or `cik`) and/or `insider_cik`; unanchored queries belong to [`POST /screener/ownership`](#post-screenerownership). **Request:** | Field | Type | Default | Notes | |---|---|---|---| | `ticker` | string | — | Uppercased automatically. | | `cik` | string | — | The company's CIK, instead of `ticker`. Digits only, ≤ 10; leading zeros optional. | | `insider_cik` | string | — | Digits only, ≤ 10; leading zeros optional. | | `transaction_code` | string[] | omitted | ≤ 20 entries. Unknown codes are dropped with a `_warnings` entry. | | `transaction_form_type` | `"4"` \| `"5"` | omitted | | | `relationship` | string[] | omitted | Any of `is_director`, `is_officer`, `is_ten_percent_owner`, `is_other`. OR semantics, evaluated per filing. | | `include_unresolved_amendments` | bool | `false` | | | `exclude_likely_merged` | bool | `false` | | | `include_anomalies` | bool | `false` | | | `page` | int ≥ 1 | 1 | | | `page_size` | int 1–100 | 50 | Counts filings. | | `detail` | string | `"full"` | `"light"` leaves out each filing's `footnotes` and each transaction's `footnote_refs`. See [Response detail](#response-detail). | At least one of `ticker` / `cik` / `insider_cik` is required, and not both `ticker` and `cik` (422 otherwise). **Response:** | Field | Meaning | |---|---| | `page`, `page_size`, `has_more`, `next_page` | Pagination. | | `anomalies_excluded_on_page` | How many transactions **on this page** were withheld because they failed a consistency check. `0` when `include_anomalies=true`. | | `filings` | Array. Each carries `ticker`, `issuer`, `issuer_cik`, `accession_number`, `form_type`, `filing_date`, `period_of_report`, `date_of_original_submission`, `merge_status`, `remarks`, `source_url_prefix`, `insiders`, `footnotes`, `transactions`, and `amendments` (present only when amendments were merged). | | `filings[].issuer_cik` | The issuer CIK declared by the filing itself. `null` when the filing does not provide issuer identity. | | `filings[].insiders` | `cik`, `name`, `is_director`, `is_officer`, `is_ten_percent_owner`, `is_other`, `officer_title`, `other_text`. | | `filings[].footnotes` | Map of footnote id → text for this filing. | | `_warnings` | Optional. | | `credits_used` | Always **30**. | **Credits:** **30 per page.** **Errors:** `404 OWNERSHIP_COMPANY_NOT_FOUND` (charged), `403 PLAN_TIER_INSUFFICIENT_COVERAGE` when the company is outside your plan's coverage scope (charged), `422 VALIDATION_ERROR`, `402 CREDITS_INSUFFICIENT`. **Example Request:** ```json { "ticker": "NVDA", "transaction_code": ["P", "S"], "page_size": 10 } ``` ## `POST /ownership/stats` **Purpose:** Aggregate statistics over one company and/or one insider, plus the ids of every transaction that contributed. **Request:** | Field | Type | Default | Notes | |---|---|---|---| | `ticker` | string | — | | | `cik` | string | — | The company's CIK, instead of `ticker`. | | `insider_cik` | string | — | | | `start_date`, `as_of_date` | ISO date | — | Window on `transaction_date`; `as_of_date` also excludes filings submitted after it. `as_of_date` ≤ today; `start_date` ≤ `as_of_date`. | | `transaction_code` | string[] | omitted | ≤ 20 entries. | | `method` | `"ad"` \| `"ps"` | `"ad"` | `ad` splits on `acquired_disposed_code`. `ps` treats P as a buy and S as a sell, and narrows the scope to those two codes. | | `include_anomalies` | bool | `false` | | | `relationship` | string[] | omitted | Any of `is_director`, `is_officer`, `is_ten_percent_owner`, `is_other`. OR semantics, evaluated per filing. | | `is_derivative` | bool | omitted | | | `exclude_likely_merged` | bool | `false` | | | `include_unresolved_amendments` | bool | `false` | | | `ids_page` | int ≥ 1 | 1 | Paginates `transaction_ids` only. | | `ids_page_size` | int 1–1000 | 200 | | | `detail` | string | `"full"` | `"light"` leaves out the `method_applied` and `start_date_applied` echoes. See [Response detail](#response-detail). | At least one of `ticker` / `cik` / `insider_cik` is required, and not both `ticker` and `cik`. **Response:** `stats`, `method_applied`, `start_date_applied`, `as_of_date_applied`, `anomalies_excluded_count`, `credits_used`, optional `corporate_actions`, optional `_warnings`, then `ids_page`, `ids_has_more`, `ids_next_page` (`null` on the last page), `transaction_ids`. Key names inside `stats` follow `method`: `acquired` / `disposed` for `ad`, `bought` / `sold` for `ps`. | `stats` field | Meaning | |---|---| | `value_acquired`, `value_disposed`, `net_value` | Cash value totals. Transactions with no cash value contribute 0. | | `shares_acquired`, `shares_disposed`, `net_shares` | Share totals on the split-adjusted basis, excluding rows where `principal_amount_not_shares` is `true`. | | `avg_price_acquired`, `avg_price_disposed` | Total value ÷ total split-adjusted shares over the transactions that have a cash value, on the same basis as `shares_*`. `null` when there are none. | | `txn_count`, `txn_count_acquired`, `txn_count_disposed` | Counts. | | `txn_count_with_value` | Transactions carrying a non-zero cash value. | | `no_value_txn_count` | Transactions with no cash value. | | `ad_code_missing_count` | Transactions counted in neither direction. | | `principal_amount_txn_count` | Debt-principal rows excluded from `shares_*` and `avg_price_*`. | | `distinct_insiders` | Distinct reporting owners in scope. | | `filings_with_multiple_filers` | Joint filings in scope. | | `max_txn_value_acquired`, `max_txn_value_disposed` | Largest single transaction per side. `null` when the side is empty. | | `avg_value_per_txn_acquired`, `avg_value_per_txn_disposed` | Mean over transactions that have a cash value. | | `earliest_transaction_date`, `latest_transaction_date` | Range actually covered. | | `corporate_action_crossing` | `true` when the window spans a corporate action. | `corporate_actions` is present when the request names a company (`ticker` or `cik`) that has corporate actions on file, except with `detail="minimal"`: an array of `{ex_date, ratio, type, event_type}`. `_warnings` names the count and the parameter that changes it whenever transactions were excluded, skipped, or carry no value. **Credits:** **40 base**, plus **ceil(n / 1000) × 5** where `n` is the number of participating transactions. Both charges are recorded as one usage entry. **Errors:** `404 OWNERSHIP_COMPANY_NOT_FOUND` (charged), `403 PLAN_TIER_INSUFFICIENT_COVERAGE` when the company is outside your plan's coverage scope (charged), `422 VALIDATION_ERROR`, `402 CREDITS_INSUFFICIENT`. **Example Request:** ```json { "ticker": "NVDA", "start_date": "2025-01-01", "as_of_date": "2025-12-31", "method": "ps" } ``` ## `POST /ownership/transaction-ids` **Purpose:** Fetch transactions by id — the detail companion to the `transaction_ids` returned by [`POST /ownership/stats`](#post-ownershipstats). **Request:** | Field | Type | Default | Notes | |---|---|---|---| | `transaction_ids` | int[] | — | **Required.** 1–100 positive integers. Duplicates are removed with a `_warnings` entry. | | `page` | int ≥ 1 | 1 | | | `page_size` | int 1–100 | 100 | Counts filings. | | `detail` | string | `"full"` | `"light"` leaves out each filing's `footnotes` and each transaction's `footnote_refs`. See [Response detail](#response-detail). | **Response:** the paging fields and `filings` of [`POST /ownership/transactions`](#post-ownershiptransactions), plus `missing_ids` when some ids were not found and `restricted_ids` when some exist but are outside your plan's history window or coverage scope. Both are charged for. **Credits:** **ceil(n / 5) × 10** on the deduplicated id count (max **100**). **Errors:** `404 OWNERSHIP_TRANSACTION_NOT_FOUND` when **none** of the requested ids exist (charged; the response carries `missing_ids`). `403 PLAN_TIER_INSUFFICIENT` when every requested id that exists is outside your plan's scope (charged; the response carries `restricted_ids`). Partial misses and partial restrictions return 200. `422 VALIDATION_ERROR`, `402 CREDITS_INSUFFICIENT`. **Example Request:** ```json { "transaction_ids": [5144965, 5144966, 5144967] } ``` ## `POST /ownership/names` **Purpose:** All insiders of one company, aggregated per CIK across its Form 4 and/or Form 3 filings. **Request:** | Field | Type | Notes | |---|---|---| | `ticker` | string | Exactly one of `ticker` or `cik`. | | `cik` | string | The company's CIK. Digits only, ≤ 10; leading zeros optional. | | `form` | string | `4`, `3` or `both` (default): which filings are aggregated. | | `relationship` | string[] | Any of `ever_director`, `ever_officer`, `ever_ten_percent_owner`, `ever_other` (a role ever reported on those filings). OR semantics. | **Response:** `names`, `credits_used`, and optional `_warnings`. Each name carries: | Field | Meaning | |---|---| | `owner_cik`, `owner_name` | Spelling from this insider's most recent filing. | | `name_changed` | `true` when earlier filings spelled the name differently. | | `caveat` | Present only when `name_changed` is `true`. | | `ever_director`, `ever_officer`, `ever_ten_percent_owner`, `ever_other` | `true` when any filing reported that role. | | `latest_officer_title` | Most recent non-null officer title. `null` when never reported. | | `officer_title_as_of` | Filing date `latest_officer_title` came from. | | `filing_count` | Filings of this company naming this insider, over the forms in `form`. | | `form4_filing_count`, `form3_filing_count` | The same count per form. | | `earliest_filing_date`, `latest_filing_date` | Range. | **Credits:** **30.** **Errors:** `404 OWNERSHIP_COMPANY_NOT_FOUND` (charged), `403 PLAN_TIER_INSUFFICIENT_COVERAGE` when the company is outside your plan's coverage scope (charged). **Example Request:** ```json { "ticker": "NVDA", "relationship": ["ever_officer"] } ``` ## `GET /ownership/tickers` **Purpose:** Discovery — one row per company with insider-trade or initial-holdings coverage, one page at a time. **Request:** | Query | Type | Default | Notes | |---|---|---|---| | `form` | string | `both` | `4` (insider transactions), `3` (initial holdings) or `both`. | | `page` | integer | `1` | 1–1,000,000. | | `page_size` | integer | `500` | 1–500. | **Response:** `tickers` (array of `{ticker, jurisdiction, cik, forms}`), `page`, `page_size`, `has_more`, `next_page`, `credits_used`, and optional `_warnings`. `forms` lists what the ticker has on file: `"4"` insider transactions, `"3"` initial holdings. **Credits:** **30 per page.** **Errors:** `422 VALIDATION_ERROR` (an unknown query parameter or a value out of range; not charged), `402 CREDITS_INSUFFICIENT`. ## `GET /ownership/transaction-types` **Purpose:** The SEC transaction-code catalog — 20 codes with their official name and grouping. **Response:** `transaction_types` (array of `{code, name, group}`), `source_url` (the SEC form the wording is copied from), and `credits_used`. **Credits:** **0.** No charge, no usage entry. **Errors:** `422 VALIDATION_ERROR` when any query parameter is sent. ## `POST /screener/ownership` **Purpose:** Full-library transaction screening. Trade-level conditions plus company-level aggregate gates; returns the matching transactions. **Request:** | Field | Type | Default | Notes | |---|---|---|---| | `start_date`, `as_of_date` | ISO date | — | Window on `transaction_date`; `as_of_date` also excludes filings submitted after it. `as_of_date` ≤ today; `start_date` ≤ `as_of_date`. | | `tickers`, `exclude_tickers` | string[] | omitted | ≤ 100 each. | | `sectors` | string[] | omitted | The 12 canonical buckets ([Industry classification (Pro+)](#industry-classification-pro)). | | `trade_filters` | object | omitted | See [Filters (`/screener/ownership`)](#filters-screenerownership). | | `aggregate_filters` | object[] | omitted | ≤ 8. Company-level gates — see [Filters (`/screener/ownership`)](#filters-screenerownership). | | `group_by_ticker` | bool | `true` | `true` → grouped by company. `false` → flat rows. | | `sort_by` | string | — | Grouped: `ticker`, `txn_count`. Flat: `transaction_date`, `filing_date`, `transaction_value`, `shares`, `price_per_share`, `own_pct_change`, `split_adjusted_shares`, `split_adjusted_price`. | | `sort_order` | `"desc"` \| `"asc"` | `"desc"` | | | `page` | int ≥ 1 | 1 | | | `page_size` | int 1–100 | 50 | Counts transactions in both modes: with `group_by_ticker=true` a page holds that many transactions, however few companies they come from. | | `detail` | string | `"full"` | `"light"` leaves out each row's `footnote_refs` and `computed.*.fact_refs`, and the `start_date_applied` echo; `"minimal"` also leaves out `accession_number` and `company_id`. See [Response detail](#response-detail). | **Pagination cap:** `page × page_size ≤ 500` (422 above it). When the next page would pass the cap, `has_more` is `false`, `next_page` is `null`, and `_warnings` says the limit was reached. **Response:** | Field | Meaning | |---|---| | `page`, `page_size`, `has_more`, `next_page` | Pagination. | | `as_of_date_applied`, `start_date_applied` | Window actually used. | | `results` | `group_by_ticker=true`. Each entry: `ticker`, `issuer`, `issuer_cik`, `txn_count` (the company's full hit count), `transactions`. | | `transactions` | `group_by_ticker=false`. Flat rows, each additionally carrying `ticker`, `issuer`, `issuer_cik` and `company_id`. | | `anomalies_excluded_count` | Transactions excluded by the consistency checks; `0` when `trade_filters.include_anomalies=true`. | | `credits_used`, `_warnings` | | Every row carries `accession_number`, `filing_date`, `source_url_prefix`, `insiders`, the [transaction object](#transaction-object), and `computed`. **Errors:** `422 VALIDATION_ERROR`, `402 CREDITS_INSUFFICIENT`, `403 PLAN_TIER_INSUFFICIENT` below Pro, `504 QUERY_TIMEOUT` at the 30-second server timeout (charged). **Example Request:** ```json { "start_date": "2026-07-01", "as_of_date": "2026-09-30", "trade_filters": { "transaction_code": ["P"], "conditions": [ { "field": "transaction_value", "op": ">=", "value": 1000000 } ] }, "group_by_ticker": false, "sort_by": "transaction_value", "page_size": 20 } ``` ### Filters (`/screener/ownership`) **`trade_filters`:** | Field | Type | Notes | |---|---|---| | `transaction_code` | string[] | ≤ 20. Unknown codes dropped with a warning. | | `relationship` | string[] | `is_director`, `is_officer`, `is_ten_percent_owner`, `is_other`. OR semantics. | | `is_derivative` | bool | | | `principal_amount_not_shares` | bool | Omit for no filter, `true` for debt-principal rows only, `false` to exclude them. | | `include_anomalies` | bool | Default `false`. | | `exclude_likely_merged` | bool | Default `false`. | | `include_unresolved_amendments` | bool | Default `false`. | | `conditions` | object[] | ≤ 8. `{field, op, value}`. `field` ∈ `transaction_value`, `price_per_share`, `shares`, `own_pct_change`, `split_adjusted_shares`, `split_adjusted_price`. | **`aggregate_filters`:** `{metric, op, value}`, `metric` ∈ `value_acquired`, `value_disposed`, `net_value`, `shares_acquired`, `shares_disposed`, `net_shares`, `txn_count`, `txn_count_acquired`, `txn_count_disposed`, `max_txn_value_acquired`, `max_txn_value_disposed`, `distinct_insiders`. **Operators** (both filter types): `>`, `>=`, `<`, `<=`, `between` (`[lo, hi]`, `lo ≤ hi`). ### Credit formula (`/screener/ownership`) `POST /screener/ownership` charges per call: ```text title="Formula" credits = max(65, 200 − tickerDiscount // 100 − min(n_tickers, 100); 0 when tickers is omitted − shortWindowDiscount // 40 when the window is ≤ 90 days + fullHistorySurcharge // 80 when start_date is omitted + 40 × conditions) // trade conditions + aggregate filters ``` Range **65–920**. Charged even when the result set is empty, and on `504 QUERY_TIMEOUT`. **No charge** on `422 VALIDATION_ERROR`, `402 CREDITS_INSUFFICIENT`, or `403 PLAN_TIER_INSUFFICIENT` (all rejected before any deduction). ## Holding object Returned by `POST /ownership/initial-holdings`, `POST /ownership/initial-holding-ids`, and `POST /screener/initial-holdings`. A Form 3 reports the positions held on becoming an insider. | Field | Meaning | |-------|---------| | `id` | Holding id. Pass to `POST /ownership/initial-holding-ids`. | | `is_derivative` | Derivative table row (`true`) or non-derivative (`false`). | | `security_title`, `direct_or_indirect`, `nature_of_ownership` | As filed. | | `shares_owned` | Amount of securities beneficially owned, as filed. `null` on derivative rows and on cancelled rows. | | `footnote_refs` | Footnote ids for this holding. Resolve against the filing's `footnotes` map. | | `source_locator` | Combine with the filing's `source_url_prefix` to build the SEC URL. | | `restated` | `null`, `"cancelled"`, `"modified"`, or `"added"` — set when an amendment changed this holding. | | `prior` | Present only when `restated` is set. The pre-amendment values. | | `split_adjusted` | Present only when the filed values are not on the current per-share basis. See below. | | `data_quality_flags` | Present only when at least one rule fires. See below. | Derivative rows additionally carry `conversion_or_exercise_price`, `exercise_date`, `expiration_date`, `underlying_security_title`, `underlying_security_shares`, and `underlying_security_value`. ### `split_adjusted` Same meaning and presence rule as on the [transaction object](#split_adjusted): present only when the filed values are not on the current per-share basis. ```json "split_adjusted": { "shares_owned": 4000.0, "underlying_security_shares": null, "conversion_or_exercise_price": null, "split_adjustment_factor": 4.0 } ``` ### `data_quality_flags` Rows that fail a consistency check carry one or more of: `missing_shares_owned`, `missing_underlying_amount`, `derivative_date_order`, `negative_shares_owned`, `negative_underlying_security_shares`, `negative_underlying_security_value`, `negative_conversion_or_exercise_price`, `manual_flags`. Rows flagged `manual_flags` also carry a `manual_flags` array of `{code, note}` entries describing the issue. Flagged rows are excluded from `POST /ownership/initial-holdings`, `POST /ownership/initial-holdings/stats` and `POST /screener/initial-holdings` unless `include_anomalies=true` (`holding_filters.include_anomalies` on the screener). Each endpoint reports how many it withheld: the listing in `anomalies_excluded_on_page` (this page only), stats and the screener in `anomalies_excluded_count` (the whole requested range). ## `POST /ownership/initial-holdings` **Purpose:** Anchored listing of initial beneficial-ownership filings (Form 3) and their holdings. Requires `ticker` (or `cik`) and/or `insider_cik`; unanchored queries belong to [`POST /screener/initial-holdings`](#post-screenerinitial-holdings). **Request:** | Field | Type | Default | Notes | |---|---|---|---| | `ticker` | string | — | Uppercased automatically. | | `cik` | string | — | The company's CIK, instead of `ticker`. Digits only, ≤ 10; leading zeros optional. | | `insider_cik` | string | — | Digits only, ≤ 10; leading zeros optional. | | `relationship` | string[] | omitted | Any of `is_director`, `is_officer`, `is_ten_percent_owner`, `is_other`. OR semantics, evaluated per filing. | | `no_securities_owned` | bool | omitted | `true` → only filings that report no holdings; `false` → only filings with holdings; omitted → both. | | `include_unresolved_amendments` | bool | `false` | | | `exclude_likely_merged` | bool | `false` | | | `include_anomalies` | bool | `false` | | | `page` | int ≥ 1 | 1 | | | `page_size` | int 1–100 | 50 | Counts filings. | | `detail` | string | `"full"` | `"light"` leaves out each filing's `footnotes` and each holding's `footnote_refs`. See [Response detail](#response-detail). | At least one of `ticker` / `cik` / `insider_cik` is required, and not both `ticker` and `cik` (422 otherwise). **Response:** | Field | Meaning | |---|---| | `page`, `page_size`, `has_more`, `next_page` | Pagination. | | `anomalies_excluded_on_page` | How many holdings **on this page** were withheld because they failed a consistency check. `0` when `include_anomalies=true`. | | `filings` | Array. Each carries `ticker`, `issuer`, `issuer_cik`, `accession_number`, `form_type`, `filing_date`, `period_of_report`, `date_of_original_submission`, `merge_status`, `remarks`, `no_securities_owned`, `source_url_prefix`, `insiders`, `footnotes`, `holdings`, and `amendments` (present only when amendments were merged). | | `filings[].no_securities_owned` | `true` when the filer reported holding no securities; such filings have an empty `holdings` array. | | `filings[].insiders` | `cik`, `name`, `is_director`, `is_officer`, `is_ten_percent_owner`, `is_other`, `officer_title`, `other_text`. | | `filings[].footnotes` | Map of footnote id → text for this filing. | | `_warnings` | Optional. | | `credits_used` | Always **30**. | **Credits:** **30 per page.** **Errors:** `404 OWNERSHIP_COMPANY_NOT_FOUND` (charged), `403 PLAN_TIER_INSUFFICIENT_COVERAGE` when the company is outside your plan's coverage scope (charged), `422 VALIDATION_ERROR`, `402 CREDITS_INSUFFICIENT`. **Example Request:** ```json { "ticker": "NVDA", "page_size": 10 } ``` ## `POST /ownership/initial-holdings/stats` **Purpose:** Aggregate statistics over the Form 3 filings of one company and/or one insider, plus the ids of every holding that contributed. **Request:** | Field | Type | Default | Notes | |---|---|---|---| | `ticker` | string | — | | | `cik` | string | — | The company's CIK, instead of `ticker`. | | `insider_cik` | string | — | | | `start_date`, `as_of_date` | ISO date | — | Window on `filing_date`. `as_of_date` ≤ today; `start_date` ≤ `as_of_date`. | | `include_anomalies` | bool | `false` | | | `relationship` | string[] | omitted | Any of `is_director`, `is_officer`, `is_ten_percent_owner`, `is_other`. OR semantics, evaluated per filing. | | `is_derivative` | bool | omitted | Restricts the holding totals; filing counts are unaffected. | | `exclude_likely_merged` | bool | `false` | | | `include_unresolved_amendments` | bool | `false` | | | `ids_page` | int ≥ 1 | 1 | Paginates `holding_ids` only. | | `ids_page_size` | int 1–1000 | 200 | | | `detail` | string | `"full"` | `"light"` leaves out the `start_date_applied` echo. See [Response detail](#response-detail). | At least one of `ticker` / `cik` / `insider_cik` is required, and not both `ticker` and `cik`. **Response:** `stats`, `start_date_applied`, `as_of_date_applied`, `anomalies_excluded_count`, `credits_used`, optional `corporate_actions`, optional `_warnings`, then `ids_page`, `ids_has_more`, `ids_next_page` (`null` on the last page), `holding_ids`. | `stats` field | Meaning | |---|---| | `filing_count` | Form 3 filings in scope. | | `no_securities_filing_count` | Of those, filings that report no holdings. | | `distinct_insiders` | Distinct reporting owners in scope. | | `filings_with_multiple_filers` | Joint filings in scope. | | `holdings_count`, `holdings_count_non_derivative`, `holdings_count_derivative` | Holding rows in scope. | | `shares_owned_total` | Sum of `shares_owned` over non-derivative rows, on the split-adjusted basis. | | `underlying_shares_total` | Sum of `underlying_security_shares` over derivative rows, on the split-adjusted basis. | | `earliest_filing_date`, `latest_filing_date` | Range actually covered. | | `corporate_action_crossing` | `true` when the window spans a corporate action. | `corporate_actions` is present when the request names a company (`ticker` or `cik`) that has corporate actions on file, except with `detail="minimal"`: an array of `{ex_date, ratio, type, event_type}`. `_warnings` names the count and the parameter that changes it whenever holdings were excluded. **Credits:** **40 base**, plus **ceil(n / 1000) × 5** where `n` is the number of participating holdings. Both charges are recorded as one usage entry. **Errors:** `404 OWNERSHIP_COMPANY_NOT_FOUND` (charged), `403 PLAN_TIER_INSUFFICIENT_COVERAGE` when the company is outside your plan's coverage scope (charged), `422 VALIDATION_ERROR`, `402 CREDITS_INSUFFICIENT`. **Example Request:** ```json { "ticker": "NVDA", "start_date": "2024-01-01" } ``` ## `POST /ownership/initial-holding-ids` **Purpose:** Fetch holdings by id — the detail companion to the `holding_ids` returned by [`POST /ownership/initial-holdings/stats`](#post-ownershipinitial-holdingsstats). **Request:** | Field | Type | Default | Notes | |---|---|---|---| | `holding_ids` | int[] | — | **Required.** 1–100 positive integers. Duplicates are removed with a `_warnings` entry. | | `page` | int ≥ 1 | 1 | | | `page_size` | int 1–100 | 100 | Counts filings. | | `detail` | string | `"full"` | `"light"` leaves out each filing's `footnotes` and each holding's `footnote_refs`. See [Response detail](#response-detail). | **Response:** the paging fields and `filings` of [`POST /ownership/initial-holdings`](#post-ownershipinitial-holdings), plus `missing_ids` when some ids were not found and `restricted_ids` when some exist but are outside your plan's history window or coverage scope. Both are charged for. **Credits:** **ceil(n / 5) × 10** on the deduplicated id count (max **100**). **Errors:** `404 OWNERSHIP_HOLDING_NOT_FOUND` when **none** of the requested ids exist (charged; the response carries `missing_ids`). `403 PLAN_TIER_INSUFFICIENT` when every requested id that exists is outside your plan's scope (charged; the response carries `restricted_ids`). Partial misses and partial restrictions return 200. `422 VALIDATION_ERROR`, `402 CREDITS_INSUFFICIENT`. **Example Request:** ```json { "holding_ids": [529404] } ``` ## `POST /screener/initial-holdings` **Purpose:** Full-library screening of initial holdings (Form 3). Holding-level conditions plus company-level aggregate gates; returns the matching holdings. Requires **Pro or higher**. **Request:** | Field | Type | Default | Notes | |---|---|---|---| | `start_date`, `as_of_date` | ISO date | — | Window on `filing_date`. `as_of_date` ≤ today; `start_date` ≤ `as_of_date`. | | `tickers`, `exclude_tickers` | string[] | omitted | ≤ 100 each. | | `sectors` | string[] | omitted | The 12 canonical buckets ([Industry classification (Pro+)](#industry-classification-pro)). | | `holding_filters` | object | omitted | See below. | | `aggregate_filters` | object[] | omitted | ≤ 8. Company-level gates — see below. | | `group_by_ticker` | bool | `true` | `true` → grouped by company. `false` → flat rows. | | `sort_by` | string | — | Grouped: `ticker`, `holdings_count`, `shares_owned_total`. Flat: `filing_date`, `shares_owned`, `split_adjusted_shares_owned`, `underlying_security_shares`, `conversion_or_exercise_price`. | | `sort_order` | `"desc"` \| `"asc"` | `"desc"` | | | `page` | int ≥ 1 | 1 | | | `page_size` | int 1–100 | 50 | Counts holdings in both modes: with `group_by_ticker=true` a page holds that many holdings, however few companies they come from. | | `detail` | string | `"full"` | `"light"` leaves out each row's `footnote_refs` and the `start_date_applied` echo; `"minimal"` also leaves out `accession_number` and `company_id`. See [Response detail](#response-detail). | **Pagination cap:** `page × page_size ≤ 500` (422 above it). When the next page would pass the cap, `has_more` is `false`, `next_page` is `null`, and `_warnings` says the limit was reached. **`holding_filters`:** | Field | Type | Notes | |---|---|---| | `relationship` | string[] | `is_director`, `is_officer`, `is_ten_percent_owner`, `is_other`. OR semantics. | | `is_derivative` | bool | | | `direct_or_indirect` | `"D"` \| `"I"` | | | `include_anomalies` | bool | Default `false`. | | `exclude_likely_merged` | bool | Default `false`. | | `include_unresolved_amendments` | bool | Default `false`. | | `conditions` | object[] | ≤ 8. `{field, op, value}`. `field` ∈ `shares_owned`, `split_adjusted_shares_owned`, `underlying_security_shares`, `split_adjusted_underlying_security_shares`, `conversion_or_exercise_price`. | **`aggregate_filters`:** `{metric, op, value}`, `metric` ∈ `filing_count`, `no_securities_filing_count`, `distinct_insiders`, `holdings_count`, `shares_owned_total`. `filing_count` and `no_securities_filing_count` count filings, including filings that report no holdings; `holdings_count` and `shares_owned_total` are measured on the matching holdings. **Operators** (both filter types): `>`, `>=`, `<`, `<=`, `between` (`[lo, hi]`, `lo ≤ hi`). **Response:** | Field | Meaning | |---|---| | `page`, `page_size`, `has_more`, `next_page` | Pagination. | | `as_of_date_applied`, `start_date_applied` | Window actually used. | | `results` | `group_by_ticker=true`. Each entry: `ticker`, `issuer`, `issuer_cik`, `holdings_count` and `shares_owned_total` (the company's full hit values), `holdings`. | | `holdings` | `group_by_ticker=false`. Flat rows, each additionally carrying `ticker`, `issuer`, `issuer_cik` and `company_id`. | | `anomalies_excluded_count` | Holdings excluded by the consistency checks; `0` when `holding_filters.include_anomalies=true`. | | `credits_used`, `_warnings` | | Every row carries `accession_number`, `filing_date`, `period_of_report`, `no_securities_owned`, `source_url_prefix`, `insiders`, and the [holding object](#holding-object). **Credits:** the [Credit formula (`/screener/ownership`)](#credit-formula-screenerownership) formula, with `conditions` = holding conditions + aggregate filters. Range **65–920**. **Errors:** `422 VALIDATION_ERROR`, `402 CREDITS_INSUFFICIENT`, `403 PLAN_TIER_INSUFFICIENT` below Pro, `504 QUERY_TIMEOUT` at the 30-second server timeout (charged). **Example Request:** ```json { "start_date": "2026-07-01", "as_of_date": "2026-09-30", "holding_filters": { "relationship": ["is_director"], "is_derivative": false }, "group_by_ticker": false, "sort_by": "shares_owned", "page_size": 20 } ``` ## Snapshot object Returned by [`POST /screener/institutional-holdings`](#post-screenerinstitutional-holdings) (as `matches[]`, with `cik` and `name`) and [`POST /ownership/institutional-holdings/manager-history`](#post-ownershipinstitutional-holdingsmanager-history) (as `quarters[]`, without them, plus `quarter`). One row = one manager × one calendar quarter, after amendments are merged. | Field | Meaning | |-------|---------| | `cik`, `name` | The filing manager. Screener rows only. | | `period` | Calendar quarter end the report covers. | | `quarter` | Manager-history rows only: the `YYYYQn` label of `period`, as taken by the portfolio endpoint; `unknown` when `period` is not a calendar quarter end. | | `filing_date`, `accession` | The filing this quarter's data comes from. | | `is_combination_report` | `true` = 13F COMBINATION REPORT (the filer also reports holdings managed by other managers), `false` = 13F HOLDINGS REPORT. | | `confidential` | The quarter carries confidential-treatment holdings. | | `is_amended` | Amendments were merged into this quarter. The full archive is on the portfolio endpoint's quarter header. | | `unit_multiplier` | `1`, or the whole-quarter unit-correction multiplier applied to the filed values. When it is not `1`, `unit_multiplier_reason` (`corrected_error` or `pre2023_rule`) is present; the key is omitted when null. | | `total_positions_value` | Total value of the stock holdings, USD. | | `total_derivatives_notional` | Total notional of the option holdings, USD. | | `cover_table_value` | The cover-page total as filed, verbatim. | | `positions_count`, `derivatives_count` | Live stock / option rows in the quarter. | | `portfolio_value_qoq_pct` | Quarter-over-quarter change of `total_positions_value`, percent. | | `top1_security_pct`, `top10_security_pct` | Portfolio share of the largest / ten largest stock holdings, percent (stock holdings only). | | `est_turnover` | Estimated traded value versus the prior quarter, USD. | | `activity_counts` | Map of row activity → count: `NEW`, `ADD`, `REDUCE`, `HOLD`, `SOLD_OUT`, `CUSIP_CHANGE`. | | `sec_url` | The URL opens the filing's EDGAR index page; see the files listed there for full details. | A quarter with **no prior filed quarter** to compare against has null `portfolio_value_qoq_pct`, `est_turnover` and `activity_counts`. Quarters marked `confidential` in the returned result are also flagged in `_warnings`. ## Institutional holding object Returned by [`POST /ownership/institutional-holdings/portfolio`](#post-ownershipinstitutional-holdingsportfolio) and [`POST /ownership/institutional-holdings/security`](#post-ownershipinstitutional-holdingssecurity) (flat mode) as `transactions[]`. Security rows additionally carry `manager_cik` / `manager_name`. Three row kinds, told apart by `type`: - **`positions`** — a stock holding. - **`derivatives`** — an option holding (`put_call` says which side). - **`exited`** — a position closed out this quarter: identity plus the closing deltas only (`d_shares`, and `d_value` or `d_notional_value_usd`). | Field | Meaning | |-------|---------| | `type`, `period` | Row kind and calendar quarter end. | | `cusip`, `ticker`, `current_ticker`, `ticker_status`, `issuer`, `issuer_norm`, `class`, `security_type` | Security identity. `ticker` is the symbol matched to the CUSIP, `current_ticker` the current one (`null` when none). `issuer` is the name as filed, `issuer_norm` the normalized name, `class` the share-class text as filed. `ticker_status` is `us_listing`, `when_issued`, `non_us_listing`, `none` (no matching listed ticker), or null. Exited rows have no `ticker_status` or `security_type`. | | `put_call` | `"Put"` / `"Call"` on option rows; null on stock rows. When the row kinds are mixed it is one of the fields telling them apart. | | `shares_or_principal_amount` | `SH` = the row's `shares` is a share count; `PRN` = a principal amount in USD (debt securities); null = a row cancelled by an amendment, or missing in the original filing. | | `shares` | Share count or principal amount, per the previous field. | | `vote_sole`, `vote_shared`, `vote_none` | Voting-authority split as filed. | | `discretion` | Investment discretion as filed (`SOLE`, `DFND`, `OTR` and combinations). | | `source_accessions` | The amendment filings this row's current values come from; null = the quarter's main filing. | | `activity` | `NEW` / `ADD` / `REDUCE` / `HOLD` / `CUSIP_CHANGE` versus the prior quarter. Null when there is no prior filed quarter to compare against. Exited rows have no activity. | | `predecessor_cusip` | On `CUSIP_CHANGE` rows: the CUSIP this security was held under in the prior quarter. | | `shares_before_cusip_change` | Shares held under the predecessor CUSIP; present only when non-null, directly after `predecessor_cusip`. | | `d_pct` | Share change versus the prior quarter, percent (`d_shares` is the absolute change). | | `unit_multiplier` | Row-level unit-correction multiplier (can be fractional, e.g. `0.001`); present when this row's filed value was individually corrected. | | `restated` | `added` / `modified` / `cancelled` when an amendment changed this row; null otherwise. A cancelled row is a tombstone: its current-value fields are null and the old values sit in `prior_versions`. | | `prior_versions` | Pre-amendment field values, newest first. | | `submgr_breakdown` | Sub-manager split of the position: `{submgr_index, submgr_name, shares, pct_of_position}`. | | `filer_flags` | Present only when the row is flagged: `zero_shares_with_value` (0 shares filed together with a value above 0), `implied_price_outlier` (value ÷ shares is at least 5× away from the security's closing price on the last trading day of the quarter). The filed values are returned as filed. | Stock rows additionally carry `value` (USD), `weight` (this holding's share of the quarter's `total_positions_value` — a percent **string** with two decimals, e.g. `"61.88%"`; null on cancelled rows), `rank` (1 = the quarter's largest stock holding), `avg_price`, and `d_value`. Option rows carry `notional_value_usd`, `underlying_price_implied`, and `d_notional_value_usd`. **Warnings** (`_warnings`, present only when non-empty) on the portfolio / security endpoints flag: - an amendment whose **claimed action type differs from its actual action** (portfolio only — see the `claimed_type` and `action` fields in `quarter.amendments_merged`); - **unit-correction multipliers** in the returned result, whole-quarter or row-level — see the `unit_multiplier` fields; - **`CUSIP_CHANGE` rows** in the returned result — see each row's `predecessor_cusip`; - a quarter **with no prior filed quarter** in the returned result — `activity`, `d_shares`, `d_value`, `d_pct` and the quarter's `est_turnover`, `portfolio_value_qoq_pct`, `activity_counts` are null there; - **flagged rows** in the returned result — see each row's `filer_flags`; - **cancelled rows** in the returned result — see each row's `restated`. ## `POST /ownership/institutional-holdings/managers` **Purpose:** Find 13F managers by name or CIK: managers whose latest name starts with `query` (under 3 characters) or contains it (3 characters or more), case-insensitive, and, when `query` is all digits, the manager with that CIK. Up to 8, largest latest portfolio first. **Request:** | Field | Type | Default | Notes | |---|---|---|---| | `query` | string | — | **Required.** 1–64 characters. A blank `query` returns no managers and is not charged. | **Response:** `managers` (up to 8 of `{cik, name, latest_quarter, latest_total_value}`; `latest_quarter` is the `YYYYQn` label of the manager's latest quarter, or `null`) and `credits_used`. **Credits:** **10.** **Errors:** `422 VALIDATION_ERROR`, `402 CREDITS_INSUFFICIENT`. **Example Request:** ```json { "query": "berkshire" } ``` **Example Response:** ```json { "managers": [ {"cik": "1067983", "name": "BERKSHIRE HATHAWAY INC", "latest_quarter": "2025Q4", "latest_total_value": 274160000000.0} ], "credits_used": 10 } ``` ## `POST /ownership/institutional-holdings/manager-history` **Purpose:** One manager's 13F history — one [snapshot object](#snapshot-object) per quarter filed, newest first by default. **Request:** | Field | Type | Default | Notes | |---|---|---|---| | `cik` | string | — | 13F filer CIK, digits without leading zeros. Provide exactly one of `cik` / `name`. | | `name` | string | — | Manager name, filed or normalized spelling. Whitespace and case are ignored; otherwise the match is exact. | | `sort_order` | `"desc"` \| `"asc"` | `"desc"` | By `period`. | | `page` | int ≥ 1 | 1 | | | `page_size` | int 1–100 | 50 | Counts quarters. | | `detail` | string | `"full"` | Full and minimal views only: `"light"` returns the minimal view. See [Response detail](#response-detail). | **Response:** `manager` (`cik`, `name`, `sec_url_prefix` — the manager's EDGAR directory prefix), `quarters` (snapshot rows), `page`, `page_size`, `total_items`, `has_more`, `next_page`, `credits_used`, and `_warnings` (a note on the EDGAR links in the full view; a note when a returned quarter has confidential holdings). **Credits:** **30.** **Errors:** `404 OWNERSHIP_MANAGER_NOT_FOUND` when no single manager matches (charged). `422 VALIDATION_ERROR`, `402 CREDITS_INSUFFICIENT`. **Example Request:** ```json { "cik": "1067983", "page_size": 8 } ``` ## `POST /ownership/institutional-holdings/portfolio` **Purpose:** One manager × one quarter — the holdings detail as [institutional holding objects](#institutional-holding-object), under a quarter header that repeats the snapshot numbers and carries the amendment archive. **Request:** | Field | Type | Default | Notes | |---|---|---|---| | `cik` / `name` | string | — | Exactly one, as in [`POST /ownership/institutional-holdings/manager-history`](#post-ownershipinstitutional-holdingsmanager-history). | | `quarter` | string | — | **Required.** Calendar quarter label `YYYYQn`, e.g. `2026Q1` (Q1 = Mar 31, Q2 = Jun 30, Q3 = Sep 30, Q4 = Dec 31). | | `type` | string | omitted | `positions` / `derivatives` / `exited`. Omitted = all three; each row carries its own `type`. The response echoes the filter as `types`. | | `activity` | string[] | omitted | ≤ 6 of `NEW`, `ADD`, `REDUCE`, `HOLD`, `CUSIP_CHANGE`. Unknown values are dropped with a `_warnings` entry. With `type="exited"` it matches nothing (exited rows have no activity) and `_warnings` says so. | | `restated` | string[] | omitted | ≤ 3 of `added`, `modified`, `cancelled`. | | `cusip` | string | omitted | 9 characters; pins one security inside the quarter. Give `cusip` or `ticker`, not both. | | `ticker` | string | omitted | Uppercased automatically; any symbol the company has traded under. | | `sort_by` | string | omitted | `period`, `d_shares`, `ticker`, `issuer_norm`, `type` (row kind as text, alphabetical: `derivatives` < `exited` < `positions`). Omitted = the filed row order. | | `sort_order` | `"desc"` \| `"asc"` | `"desc"` | | | `page` | int ≥ 1 | 1 | | | `page_size` | int 1–100 | 50 | Counts rows after filtering, all kinds together. | | `detail` | string | `"full"` | `"light"` leaves out each holding's `submgr_breakdown` and the `types` echo. With `sort_by` `issuer_norm`, `"minimal"` returns the light view. See [Response detail](#response-detail). | **Response:** `manager` (as in [`POST /ownership/institutional-holdings/manager-history`](#post-ownershipinstitutional-holdingsmanager-history)); `quarter` — a [snapshot object](#snapshot-object) plus `accessions` (every filing applied to the quarter, in order), `sec_locators` (accession → EDGAR index-page path; combine with the manager's `sec_url_prefix`), `amendments_merged` (see below) and `prior_versions` (superseded cover pages); then `types`, `transactions`, `page`, `page_size`, `total_items`, `has_more`, `next_page`, `credits_used`, and `_warnings` (see the [institutional holding object](#institutional-holding-object)). `amendments_merged` — one entry per amendment applied to the quarter: `accession`, `filing_date`, `claimed_type` (the type the amendment declared for itself, or null), `action` (what it actually did: `REPLACE` / `MERGE_ADD` / `DUPLICATE_SUPERSEDED` / `REJECTED`), `cover_total`, `confidential`, and `positions_added` / `positions_restated` / `positions_cancelled`. **Credits:** **30 per page.** **Errors:** `404 OWNERSHIP_MANAGER_NOT_FOUND` (charged); `404 OWNERSHIP_MANAGER_QUARTER_NOT_FOUND` when the manager exists but no 13F data was found for that quarter (charged); `422 VALIDATION_ERROR`, `402 CREDITS_INSUFFICIENT`. **Example Request:** ```json { "cik": "1067983", "quarter": "2026Q2", "type": "positions", "sort_by": "d_shares", "page_size": 20 } ``` ## `POST /ownership/institutional-holdings/security` **Purpose:** One security's holder rows across managers — who holds it, quarter by quarter. Flat mode returns [institutional holding objects](#institutional-holding-object) with `manager_cik` / `manager_name` and `source_urls` (`{accession, url}` for each filing the row cites; `url` may be `null`) on each row; `group_by_quarter=true` switches to one aggregate row per quarter. **Request:** | Field | Type | Default | Notes | |---|---|---|---| | `cusip` | string | — | 9 characters. Provide exactly one of `cusip` / `ticker`. | | `ticker` | string | — | Uppercased automatically; any symbol the company has traded under. A ticker can match several CUSIPs; rows for all of them are included, `securities` lists each one, and a `_warnings` entry says how many matched. | | `quarter` | string | omitted | `YYYYQn`. Omitted = every quarter, newest first. | | `type` | string | omitted | As in [`POST /ownership/institutional-holdings/portfolio`](#post-ownershipinstitutional-holdingsportfolio). | | `activity` | string[] | omitted | As in [`POST /ownership/institutional-holdings/portfolio`](#post-ownershipinstitutional-holdingsportfolio). | | `group_by_quarter` | bool | `false` | `true` → one aggregate row per quarter (`period`, `holders`, `total_shares`, `total_value`, computed over live stock rows), unpaged; `type` / `activity` / `sort_by` / `page` are ignored with a warning. | | `sort_by` | string | omitted | `period`, `d_shares`, `ticker`, `issuer_norm`, `type`, `shares`, `value`. Omitted = newest quarter first. | | `sort_order` | `"desc"` \| `"asc"` | `"desc"` | | | `page` | int ≥ 1 | 1 | | | `page_size` | int 1–100 | 50 | | | `detail` | string | `"full"` | `"light"` leaves out each holding's `submgr_breakdown` and the `types` and `group_by_quarter` echoes. With `sort_by` `issuer_norm` in flat mode, `"minimal"` returns the light view. See [Response detail](#response-detail). | **Response:** `securities` — one entry per matched CUSIP: `cusip`, `ticker`, `current_ticker`, `ticker_status`, `issuer_norm`, `security_type`, `first_seen` / `last_seen` (first / latest quarter end the security appears in), `latest_holders` (holder count at `last_seen`); then `group_by_quarter`, `credits_used`, and either the flat fields (`types`, `transactions`, `page`, `page_size`, `total_items`, `has_more`, `next_page`) or the grouped ones (`transactions`, `total_items`, unpaged). **Credits:** **30 per page** (flat mode); **40 flat** (`group_by_quarter=true`, unpaged). **Errors:** `404 OWNERSHIP_SECURITY_NOT_FOUND` (charged), `422 VALIDATION_ERROR`, `402 CREDITS_INSUFFICIENT`. **Example Request:** ```json { "ticker": "AAPL", "quarter": "2026Q2", "type": "positions", "sort_by": "shares", "page_size": 20 } ``` ## `POST /screener/institutional-holdings` **Purpose:** Screen SEC Form 13F institutional filings across the whole library. One row = one manager-quarter, carrying that quarter's headline numbers (the [snapshot object](#snapshot-object), plus the manager's `cik` and `name`). An empty body is the full listing, ordered by `total_positions_value` descending. Requires **Pro or higher**. **Request:** | Field | Type | Default | Notes | |---|---|---|---| | `start_date`, `end_date` | ISO date | omitted | Bound the calendar **quarter end**: quarters whose period end falls inside the range participate. Give one date to bound one side only; omit both to scan every quarter. | | `conditions` | object[] | omitted | ≤ 8 of `{field, op, value}` — see below. | | `is_amended` | bool | omitted | `true` → only quarters with merged amendments; `false` → only quarters without. | | `confidential` | bool | omitted | Filter on the confidential-treatment flag. | | `is_combination_report` | bool | omitted | `true` → 13F COMBINATION REPORT quarters (the filer also reports holdings managed by other managers); `false` → 13F HOLDINGS REPORT quarters. | | `sort_by` | string | `total_positions_value` | One of `total_positions_value`, `positions_count`, `derivatives_count`, `total_derivatives_notional`, `portfolio_value_qoq_pct`, `top1_security_pct`, `top10_security_pct`, `est_turnover`, `period`, `filing_date`. | | `sort_order` | `"desc"` \| `"asc"` | `"desc"` | | | `page` | int ≥ 1 | 1 | | | `page_size` | int 1–100 | 50 | | | `detail` | string | `"full"` | Full and minimal views only: `"light"` returns the minimal view. A `cover_table_value` condition returns the full view. See [Response detail](#response-detail). | **Pagination cap:** `page × page_size ≤ 500` (422 above it). When the next page would pass the cap, `has_more` is `false`, `next_page` is `null`, and `_warnings` says the limit was reached. **`conditions`:** each is `{field, op, value}` with `op` ∈ `>`, `>=`, `<`, `<=`, `between` (`[lo, hi]`, `lo ≤ hi`, inclusive on both ends). `field` is one of `total_positions_value`, `positions_count`, `derivatives_count`, `total_derivatives_notional`, `portfolio_value_qoq_pct`, `top1_security_pct`, `top10_security_pct`, `est_turnover`, `cover_table_value`, `new_count`, `add_count`, `reduce_count`, `hold_count`, `sold_out_count` (the five counters read the quarter's `activity_counts`), or `filing_date` (values as ISO date strings). A quarter where the compared field is null never matches. A quarter with no prior filed quarter to compare against has null `portfolio_value_qoq_pct`, `est_turnover` and `activity_counts`. **Response:** `matches` (snapshot rows with `cik` / `name`), `page`, `page_size`, `total_items`, `has_more`, `next_page`, `credits_used`, and `_warnings`: a note on the EDGAR links (full view), a note when the returned rows span more than one quarter (the same manager can appear once per quarter), and a note when a returned quarter has confidential holdings. **Errors:** `422 VALIDATION_ERROR`, `402 CREDITS_INSUFFICIENT`, `403 PLAN_TIER_INSUFFICIENT` below Pro (all rejected before any deduction), `504 QUERY_TIMEOUT` at the 30-second server timeout (charged). **Example Request:** ```json { "start_date": "2026-06-30", "end_date": "2026-06-30", "conditions": [ { "field": "total_positions_value", "op": ">=", "value": 100000000000 } ], "page_size": 20 } ``` ### Credit formula (`/screener/institutional-holdings`) `POST /screener/institutional-holdings` charges per call (paginate ⇒ each page bills independently): ```text title="Formula" credits = max(65, 200 + 40 × conditions // numeric conditions + boolean filters actually passed − narrowWindowDiscount // 40 when both dates are given and span ≤ 184 days (at most two quarters) + noWindowSurcharge) // 80 when neither date is given ``` Range **160–720**. | Scenario | Credits | |---|---| | Empty body (full listing) | **280** | | One quarter (`start_date` = `end_date`), 1 condition | **200** | | 1 condition + `is_amended`, no dates | **360** | Charged even when `matches` is empty, and on `504 QUERY_TIMEOUT`. **No charge** on `422 VALIDATION_ERROR`, `402 CREDITS_INSUFFICIENT`, or `403 PLAN_TIER_INSUFFICIENT` (all rejected before any deduction). ## Event objects Corporate event summaries, original filing text, attachments and amendment history for US companies. The `/events/*` endpoints require **Starter or higher**. Cross-company and date-filtered searches use [`POST /screener/events`](#post-screenerevents). ### Event filing object Returned by `POST /events/filings`, `POST /events/filing` and `POST /screener/events`. | Field | Meaning | |---|---| | `id` | Filing identifier, used as `filing_id` on `POST /events/filing`. | | `ticker`, `issuer_cik` | Company symbol, and the 10-digit CIK this filing was filed under. | | `accession_number` | SEC accession number. | | `form_type` | Filing type as reported. | | `filing_date` | Filing date, `YYYY-MM-DD`. | | `period_of_report` | Reported event date, `YYYY-MM-DD`. | | `items` | Item codes represented by the filing's current sections. | | `items_declared` | Item codes declared in the filing. | | `merge_status` | Amendment association: `null` (none), `confirmed`, `likely`, or `unresolved` (standalone amendment). | | `source_url_prefix` | Base URL for resolving each section's `source_locator`, including relative `../` paths. | ### Event section object Returned in `sections` by `POST /events/filing` and `POST /screener/events`. | Field | Meaning | |---|---| | `item`, `title` | Item code and section title. | | `summary` | Current event summary, including available amendments. | | `source_accession`, `source_locator` | Source accession and document path for the summary. Resolve the path against the filing's `source_url_prefix`. | | `source_filing_date` | Filing date of `source_accession`, `YYYY-MM-DD`. | | `restated` | `null`, `added`, `modified` or `cancelled`. | | `prior` | Previous summaries, when available: `{accession, filing_date, summary}` entries, newest first. Returned only by `POST /events/filing`. | The detail response also includes `amendments` when available. Each entry contains `accession`, `source_locator`, `amendment_type`, `amendment_filing_date`, `sections_added`, `sections_restated`, `merge_key` (amendment reference label), and `amendment_reason` (text or `null`). Attachments are returned as `exhibits` when requested. Each entry contains `exhibit`, `description`, `source_locator`, `source_accession` and `text` (`null` when the attachment has no text). ### Event warnings `_warnings` is omitted when there are no notices. Identical messages appear once. - Different `items` and `items_declared` sets produce a filing-level notice. List and screening responses combine the affected filing count for that page into one notice. - Selecting `items` on the detail endpoint produces a notice if sections are omitted. - Reading a standalone unresolved amendment produces a notice. - Returned attachments without text produce a notice. - History limits, the company's other symbols or CIKs ([Company symbols and CIKs](#company-symbols-and-ciks)) and the screening pagination cap may produce notices. ## `GET /events/types` **Purpose:** List the 33 supported Item codes, their official English titles and the official source URL. **Request:** No parameters. **Response:** `items` (array of `{item, title}`), `source_url`, and `credits_used`. **Credits:** **0**. **Errors:** `403 PLAN_TIER_INSUFFICIENT` below Starter; `422 VALIDATION_ERROR` when any query parameter is sent. Authentication and rate-limit errors follow [Errors](#errors). **Example Request:** ```http GET /api/v1/events/types X-API-Key: ``` **Example Response:** ```json { "items": [ { "item": "2.02", "title": "Results of Operations and Financial Condition" }, { "item": "5.02", "title": "Departure of Directors or Certain Officers; Election of Directors; Appointment of Certain Officers; Compensatory Arrangements of Certain Officers" } ], "source_url": "https://www.sec.gov/files/form8-k.pdf", "credits_used": 0 } ``` ## `POST /events/filings` **Purpose:** List one company's event filings, newest first. The returned `id` identifies a filing for [`POST /events/filing`](#post-eventsfiling). **Request:** | Field | Type | Default | Notes | |---|---|---|---| | `ticker` | string | omitted | Exactly one of `ticker` or `cik`. 1–32 characters; case-insensitive; surrounding whitespace ignored. | | `cik` | string | omitted | Exactly one of `ticker` or `cik`. 1–10 digits; leading zeros may be omitted. | | `page` | int ≥ 1 | 1 | | | `page_size` | int 1–100 | 50 | | | `detail` | string | `"full"` | Full and minimal views only: `"light"` returns the minimal view. See [Response detail](#response-detail). | **Response:** `page`, `page_size`, `has_more`, `next_page`, `filings` ([event filing objects](#event-filing-object)), `credits_used`, and optional `_warnings`. Empty pages return `filings: []`; the last page has `next_page: null`. This list returns filing metadata and excludes standalone unresolved amendments. Item/date filters and the option to include those amendments are available on [`POST /screener/events`](#post-screenerevents). **Credits:** **10 per page**, including empty pages. **Errors:** `404 EVENTS_COMPANY_NOT_FOUND` (charged), `422 VALIDATION_ERROR`, `402 CREDITS_INSUFFICIENT`, `403 PLAN_TIER_INSUFFICIENT` below Starter. **Example Request:** ```json { "ticker": "CNP", "page": 1, "page_size": 1 } ``` **Example Response:** ```json { "page": 1, "page_size": 1, "has_more": true, "next_page": 2, "filings": [ { "id": 4688, "ticker": "CNP", "issuer_cik": "0001130310", "accession_number": "0001130310-23-000002", "form_type": "8-K", "filing_date": "2023-01-03", "period_of_report": "2023-01-03", "items": [ "5.02", "7.01", "9.01" ], "items_declared": [ "5.02", "7.01", "9.01" ], "merge_status": "confirmed", "source_url_prefix": "https://www.sec.gov/Archives/edgar/data/1130310/000113031023000002/" } ], "credits_used": 10 } ``` ## `POST /events/filing` **Purpose:** Read one event filing, with optional Item selection, original text and attachments. **Request:** | Field | Type | Default | Notes | |---|---|---|---| | `filing_id` | integer | required | An `id` from `/events/filings` or `/screener/events`. 1–9223372036854775807; strings and booleans are rejected. | | `items` | string[] | omitted | 1–33 codes from [`GET /events/types`](#get-eventstypes); duplicates removed. Omit or send `null` for all sections. | | `include_original_raw_text` | bool | `false` | Include complete original filing text as `raw_text`, at no additional cost. | | `include_exhibits` | bool | `false` | Include the filing's attachments as `exhibits`, at no additional cost. | | `as_of_date` | ISO date | omitted | Read this filing only if it was filed on or before this date. Must not be in the future. | | `detail` | string | `"full"` | Full and minimal views only: `"light"` returns the minimal view. With `include_original_raw_text` or `include_exhibits`, the full view is returned. See [Response detail](#response-detail). | **Response:** `filing` ([event filing object](#event-filing-object)) with `sections` ([event section objects](#event-section-object)), available `amendments`, and `raw_text` / `exhibits` when requested; then `credits_used` and optional `_warnings`. `items` filters only `sections`. Filing metadata, amendment records and requested original text remain complete. Valid Item codes with no matching sections return `sections: []`. **Credits:** **30 per call**, including requests with no matching sections. **Errors:** `404 EVENTS_FILING_NOT_FOUND` (charged), `404 EVENTS_FILING_NOT_YET_FILED` (charged; the filing is later than `as_of_date`), `403 PLAN_TIER_INSUFFICIENT` when the filing is outside your plan (charged) or below Starter, `422 VALIDATION_ERROR`, `402 CREDITS_INSUFFICIENT`. **Example Request:** ```json { "filing_id": 4688, "items": [ "5.02" ], "include_original_raw_text": false, "include_exhibits": false, "as_of_date": null } ``` **Example Response:** ```json { "filing": { "id": 4688, "ticker": "CNP", "issuer_cik": "0001130310", "accession_number": "0001130310-23-000002", "form_type": "8-K", "filing_date": "2023-01-03", "period_of_report": "2023-01-03", "items": [ "5.02", "7.01", "9.01" ], "items_declared": [ "5.02", "7.01", "9.01" ], "merge_status": "confirmed", "source_url_prefix": "https://www.sec.gov/Archives/edgar/data/1130310/000113031023000002/", "sections": [ { "item": "5.02", "title": "Departure of Directors or Certain Officers; Election of Directors; Appointment of Certain Officers; Compensatory Arrangements of Certain Officers", "summary": "On January 3, 2023, CenterPoint Energy, Inc. announced a new organizational structure effective immediately. Chief Executive Officer David J. Lesar continues in his role; President and Chief Operating Officer Jason P. Wells continues and will also serve as Chief Financial Officer until a successor is appointed…", "source_accession": "0001130310-23-000028", "source_filing_date": "2023-02-21", "restated": "modified", "source_locator": "../000113031023000028/cnp-20230217.htm" } ], "amendments": [ { "accession": "0001130310-23-000028", "source_locator": "../000113031023000028/cnp-20230217.htm", "amendment_type": "merged", "amendment_filing_date": "2023-02-21", "sections_added": 0, "sections_restated": 2, "merge_key": "explicit_reference", "amendment_reason": "This Current Report on Form 8-K/A amends our Current Report on Form 8-K filed with the Securities and Exchange Commission on January 3, 2023 and dated as of January 3, 2023." } ] }, "credits_used": 30, "_warnings": [ "Some sections were omitted because the request included items. To retrieve all sections for this filing, omit the items field." ] } ``` ## `POST /screener/events` **Purpose:** Screen corporate event filings by company, filing date and Item code. Returns matching section summaries grouped by filing. Requires **Pro or higher**. **Request:** | Field | Type | Default | Notes | |---|---|---|---| | `tickers` | string[] | omitted | 1–100 symbols, each 1–32 characters. Case-insensitive; duplicates removed. Omitted = all available companies. | | `start_date`, `end_date` | ISO date | omitted | Inclusive bounds on `filing_date`; `start_date` ≤ `end_date`. Either bound may be omitted. | | `as_of_date` | ISO date | omitted | Exclude filings filed after this date: an `end_date` with no start. Must not be in the future or earlier than `start_date`. | | `items` | string[] | omitted | 1–33 codes from [`GET /events/types`](#get-eventstypes); duplicates removed. Omitted = all Items. | | `item_match` | `"any"` \| `"all"` | `"any"` | Match at least one or all requested Item codes in a filing. Applies only when `items` is supplied. | | `include_unresolved_amendments` | bool | `false` | Include standalone amendments without an associated original filing. | | `exclude_likely_merged` | bool | `false` | Exclude filings with `merge_status="likely"`. | | `page` | int ≥ 1 | 1 | | | `page_size` | int 1–10 | 5 | Filings per page. | | `detail` | string | `"full"` | Full and minimal views only: `"light"` returns the minimal view. See [Response detail](#response-detail). | **Pagination cap:** `page × page_size ≤ 500` (422 above it). When the next page would pass the cap, `has_more` is `false`, `next_page` is `null`, and `_warnings` says the limit was reached. **Response:** | Field | Meaning | |---|---| | `page`, `page_size`, `has_more`, `next_page` | Pagination. `next_page` is `null` on the last page. | | `filings` | [Event filing objects](#event-filing-object), each with a `sections` array of matching [event section objects](#event-section-object). Empty results return `[]`. | | `credits_used`, `_warnings` | Credits charged and optional [event warnings](#event-warnings). | Results are ordered by `filing_date` descending. Each issuer and accession appears once, including when several share-class symbols match. With `items`, only matching sections are returned; the filing's `items` and `items_declared` remain complete. Original text, `prior` and `amendments` are on [`POST /events/filing`](#post-eventsfiling). **Credits:** **65–280 per page**, using the [Credit formula (`/screener/events`)](#credit-formula-screenerevents) formula. **Errors:** `422 VALIDATION_ERROR`, `402 CREDITS_INSUFFICIENT`, `403 PLAN_TIER_INSUFFICIENT` below Pro, `504 EVENTS_QUERY_TIMEOUT` at the 30-second query timeout (charged). **Example Request:** ```json { "tickers": [ "CNP" ], "start_date": "2023-01-01", "end_date": "2023-01-31", "items": [ "5.02" ], "page": 1, "page_size": 5 } ``` **Example Response:** ```json { "page": 1, "page_size": 5, "has_more": false, "next_page": null, "filings": [ { "id": 4688, "ticker": "CNP", "issuer_cik": "0001130310", "accession_number": "0001130310-23-000002", "form_type": "8-K", "filing_date": "2023-01-03", "period_of_report": "2023-01-03", "items": [ "5.02", "7.01", "9.01" ], "items_declared": [ "5.02", "7.01", "9.01" ], "merge_status": "confirmed", "source_url_prefix": "https://www.sec.gov/Archives/edgar/data/1130310/000113031023000002/", "sections": [ { "item": "5.02", "title": "Departure of Directors or Certain Officers; Election of Directors; Appointment of Certain Officers; Compensatory Arrangements of Certain Officers", "summary": "On January 3, 2023, CenterPoint Energy, Inc. announced a new organizational structure effective immediately. Chief Executive Officer David J. Lesar continues in his role; President and Chief Operating Officer Jason P. Wells continues and will also serve as Chief Financial Officer until a successor is appointed…", "source_accession": "0001130310-23-000028", "source_filing_date": "2023-02-21", "restated": "modified", "source_locator": "../000113031023000028/cnp-20230217.htm" } ] } ], "credits_used": 65 } ``` ### Credit formula (`/screener/events`) `POST /screener/events` charges per page: ```text title="Formula" credits = max(65, 200 − tickerDiscount // 100 − n distinct requested tickers; 0 when omitted − shortWindowDiscount // 40 when both dates are supplied and differ by ≤ 90 days + fullHistorySurcharge) // 80 when start_date is omitted ``` Range **65–280**. | Request scope | Credits per page | |---|---:| | One ticker, both dates within 90 days | 65 | | All companies, both dates within 90 days | 160 | | All companies, a longer range with `start_date` | 200 | | All companies, no `start_date` | 280 | Charged even when `filings` is empty, and on `504 EVENTS_QUERY_TIMEOUT`. No charge on validation, authentication, endpoint-tier, insufficient-credit or rate-limit errors.