AkkruData API & MCP — User Guide

This document describes the /data and /metric HTTP APIs: request and response fields, HTTP status codes, credit usage, and rate limits. It is intended for application integrators.

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).

Table of Contents

1. Conventions

1.1 Authentication

All requests to /data/*, /metric/*, /screener/*, and /ownership/* require:

For POST requests with a JSON body, also send:

1.2 Success and error payloads

Structured errors return JSON of the form:

{
  "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 or bearer token), 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.

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 Section 8.

1.3 Credits

Credits are deducted from the account tied to your API key. Amounts and timing are listed under each endpoint and in Section 2. 402 Payment Required indicates insufficient credits for that operation.

1.4 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.

1.5 Examples Disclaimer

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.

1.6 Filing caveats

A filing may carry a free-text disclaimer about its extraction completeness — for example, when a portion of the original filing was deliberately excluded from the extracted facts. When present, the disclaimer surfaces in two places on every endpoint that returns filing information, facts, or statements:

• A caveat field on the filing information itself (top-level for single-filing responses; per-row in results[] for compare endpoints; per-item in filings[] for the listing endpoint). Either null / absent (no caveat), or a string.
• A _warnings entry of the form Filing <TICKER> <FORM> FY<YEAR>[ <QUARTER>] has caveat: <text>. Compare endpoints aggregate per-filing caveats into a single deduplicated _warnings list.

The caveat is informational and does not affect billing or response status.

1.7 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 §2.

Reference: a Starter plan (20,000 credits / month) covers about 330 three-item line-item queries, 240 three-statement pulls, or 135 /metric/all snapshots per month — pick the mix that fits your workflow.

1.8 History truncation notice

List, range, and discovery endpoints attach a generic _warnings entry when results would be larger on a higher plan. Affected endpoints: POST /data/filings, POST /data/company (the coverage map), POST /metric/filings, POST /metric/historical, POST /screener/metrics, and 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). For /screener/metrics the lookback is additionally auto-clamped to your plan's window so you are only billed for the portion you can access. Single-filing endpoints (/data/facts, /data/statement, /data/line-items, etc.) instead return 403 PLAN_TIER_INSUFFICIENT_HISTORY when the requested filing is out of window. POST /ownership/transaction-ids lists out-of-window ids in restricted_ids and returns that 403 only when every id found is out of scope.

1.9 Coverage scope notice

Each plan covers a subset of companies. Single-company endpoints return 403 PLAN_TIER_INSUFFICIENT_COVERAGE with detail.required_tier when the requested company is outside your plan's scope. /ownership/* endpoints do this whenever the request is anchored on a ticker. List, discovery, /screener/metrics, /screener/ownership, /screener/initial-holdings, and /ownership/* requests not anchored on a ticker are silently filtered to your plan's scope and attach a generic _warnings entry when companies are excluded. POST /ownership/transaction-ids and POST /ownership/initial-holding-ids report out-of-scope ids in restricted_ids instead.

1.10 Industry classification (Pro+)

Pro-plan and higher responses attach an industry classification block per company on GET /data/company/list, POST /data/compare/line-items, POST /data/compare/facts, and POST /screener/metrics results. Sub-Pro callers receive the same responses without it; attaching it costs no extra credits.

"classification": {
  "sectors": ["Technology"],
  "source": { "scheme": "US_SIC", "code": "3571", "url": "https://www.sec.gov/search-filings/standard-industrial-classification-sic-code-list" }
}

The 12 canonical buckets: Technology, Healthcare, Finance, Consumer Discretionary, Consumer Staples, Communications, Industrials, Energy, Utilities, Materials, Real Estate, Other. POST /screener/metrics (§6.1) and POST /screener/ownership (§6.5) both accept a sectors filter over these.

2. Credit summary

Credit charges for /data, /metric, /screener, and /ownership are as follows.

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 may include _correction and _warnings when resolution is non-trivial.

3. Rate limits

Per-account limits (requests per minute, per route):

4. Data API

Filing caveats apply to every endpoint in this section. When a filing carries a free-text disclaimer, it is echoed as a caveat field on the filing information and mirrored to the response's _warnings list. See §1.6 Filing caveats for the exact shape; per-endpoint sections below only call it out where the placement differs (lists, compare).

4.1 POST /data/filings

Purpose: List filings available for one company and one fiscal year, optionally filtered by form type and quarter.

Request:

Response:

Optional amendment_context may appear on a filing item when restatement or amendment information is available (English summary and optional references).

Errors:

Example Request:

{
  "ticker": "AAPL",
  "fiscal_year": 2024,
  "form_type": "10-K"
}

Example MCP tool call:

list_filings(ticker="AAPL", fiscal_year=2024, form_type="10-K")

Example Response:

{
  "credits_used": 10,
  "fiscal_year": 2024,
  "company": {
    "ticker": "AAPL",
    "cik": "0000320193",
    "legal_name": "Apple Inc."
  },
  "filings": [
    {
      "id": 12345,
      "ticker": "AAPL",
      "form_type": "10-K",
      "fiscal_year": 2024,
      "quarter": "FY",
      "total_facts": 1500,
      "total_blocks": 12,
      "has_excel": true
    }
  ]
}

4.2 POST /data/company

Purpose: Resolve one company by ticker, cik, dart_corp_code, or edinet_code and return its identity plus a coverage summary — every form_type × fiscal_year × quarter we hold for that issuer. Use this as the entry point when you only know a company name/ticker and need to discover what filings exist.

Request:

Response:

Charging: A DATA_COMPANY_NOT_FOUND response is still charged 8 credits.

Errors:

Example Request:

{
  "ticker": "AAPL"
}

Example MCP tool call:

lookup_company(ticker="AAPL")

Example Response:

{
  "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",
  "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
}

4.3 GET /data/company/list

Purpose: Discovery — return every company covered. Cache the result locally and refresh at most once per day.

Request:

Response:

Errors:

Example Request:

GET /api/v1/data/company/list
X-API-Key: <your-api-key>

Example MCP tool call:

list_companies()

Example Response:

{
  "companies": [
    {"ticker": "AAPL",   "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",   "jurisdiction": "US", "cik": "0000789019"},
    {"ticker": "005930", "jurisdiction": "KR", "dart_corp_code": "00126380"},
    {"ticker": "1332",   "jurisdiction": "JP", "edinet_code": "E00014"},
    {"ticker": "VIRI_F", "jurisdiction": "EU", "lei": "969500FCVQ5SLAAUJV59"},
    {"ticker": "600519_CN", "jurisdiction": "CN", "uscc": "9152000071430580XT"}
  ],
  "credits_used": 175
}

4.4 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 supply ticker, fiscal_year, form_type (default 10-K), and optional quarter. If filing_id is present with identity fields, filing_id wins.

Request:

Response: ticker, form_type, fiscal_year, quarter, source_url_prefix, results, credits_used, 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; 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 pre-ordered by Akkru smart ranking, and the multi-tag _warnings entry lists the matched concepts in that same order. The order is a recommendation only — review all returned results and judge which one you need.

Results are consolidated totals only. A value reported on a dimension (a single product line, segment, or region) is never returned by name, even when a printed statement row carries that name. Two ways to read slice values: POST /data/facts/dimensional-breakdown / POST /data/line-items/dimensional-breakdown starting from the total's fact_id, or POST /data/statement to read 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 attribute was inferred by the akkru engine — a note is appended to _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), so it is not directly comparable to the gross sales reported by non-financial companies.

Some filings tag per-share items (dividends per share, share counts) only per share class or dividend type; rows carrying such classifications do not resolve by name. They remain readable in the source 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: DATA_FILING_NOT_FOUND, DATA_FILING_QUARTER_REQUIRED, CREDITS_ZERO_BALANCE.

Example Request:

{
  "filing_id": 12345,
  "line_items": ["revenue", "net income"],
  "light_weight_mode": true
}

Example MCP tool call:

query_line_items(filing_id=12345, line_items=["revenue", "net income"], light_weight_mode=True)

Example response excerpt (one single-position row + one multi-position row):

{
  "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
}

4.5 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 instead.

Filing selection: supply filing_id, or supply ticker, fiscal_year, form_type (default 10-K), and optional quarter. If filing_id is present with identity fields, filing_id wins.

Request:

Response:

Light-weight mode (light_weight_mode=true): each results[*].dimensional_breakdowns is set to null. A notice is appended to _warnings.

Errors:

Example Request:

{
  "filing_id": 12345,
  "fact_ids": ["ix_1", "ix_2"]
}

Example MCP tool call:

get_filing_facts(filing_id=12345, fact_ids=["ix_1", "ix_2"])

4.6 POST /data/statement

Purpose: Return one or more financial statement block(s) (JSON) for a filing. Two 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 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.

For the 5 main statements prefer the dedicated statement endpoints (/data/income-statement etc.) — same response shape, with the target spelled in the URL.

Filing selection: same pattern as POST /data/facts (filing_id or ticker + fiscal_year + form_type + optional quarter).

Request:

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 mode: 28 flat, debited before the filing is resolved (balance below 28 → HTTP 402).

Response:

Light-weight mode (light_weight_mode=true) — applied to every match's block:

• block.child_components → replaced by a placeholder string
• In every block.parent_xbrl_table.mapped_xbrl_facts[*]:
  • xbrl_fact: concept_ns, concept_local, item_type, decimals, sign_attr, sign_from_xbrl, format
  • html_locator: xlsx_cell

A notice is appended to _warnings.

Errors:

Example Request (role_label mode):

{
  "ticker": "AAPL",
  "form_type": "10-K",
  "fiscal_year": 2024,
  "role_label": "CONSOLIDATED STATEMENTS OF OPERATIONS"
}

Example Request (statement_type mode):

{
  "ticker": "AAPL",
  "form_type": "10-K",
  "fiscal_year": 2024,
  "statement_type": "Income Statement"
}

Example MCP tool call:

get_filing_statement(ticker="AAPL", form_type="10-K", fiscal_year=2024,
                    statement_type="Income Statement")

Example Response:

{
  "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
}

4.7 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 exactly which statement_type / role_label values a specific filing exposes before calling POST /data/statement or the convenience endpoints.

Filing selection: standard (filing_id or ticker + fiscal_year + form_type + optional quarter).

Request:

Response:

Errors:

Example Request:

{
  "ticker": "AAPL",
  "form_type": "10-K",
  "fiscal_year": 2024
}

Example MCP tool call:

list_filing_statements(ticker="AAPL", form_type="10-K", fiscal_year=2024)

Example Response:

{
  "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
}

4.8 Statement endpoints (/data/<statement>)

Five endpoints that fetch one specific statement directly by URL. Each is equivalent to POST /data/statement with the matching statement_type — fixed by the URL path, so role_label and statement_type 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.

Request body: same fields as POST /data/statement minus role_label and statement_type.

Response: identical to POST /data/statement (matches: [...]). matched_via.source is always "statement_type".

Errors: identical to POST /data/statement (statement_type mode).

Example request:

{ "ticker": "AAPL", "form_type": "10-K", "fiscal_year": 2024 }

Example MCP tool calls:

get_income_statement(ticker="AAPL", form_type="10-K", fiscal_year=2024, light_weight_mode=True)
get_comprehensive_income(ticker="AAPL", form_type="10-K", fiscal_year=2024)
get_balance_sheet(ticker="AAPL", form_type="10-K", fiscal_year=2024)
get_cash_flow_statement(ticker="AAPL", form_type="10-K", fiscal_year=2024)
get_equity_statement(ticker="AAPL", form_type="10-K", fiscal_year=2024)

4.9 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:

Response:

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. 10 credits are charged on DATA_FACT_NOT_FOUND. A root with no breakdowns returns 200 with groups: [] and is charged 10 credits.

Errors:

Example Request:

{
  "ticker": "AAPL",
  "form_type": "10-K",
  "fiscal_year": 2025,
  "fact_id": "f-78"
}

Example MCP tool call:

get_dimensional_breakdown_by_fact_id(
    ticker="AAPL", form_type="10-K", fiscal_year=2025, fact_id="f-78"
)

Example Response (abridged):

{
  "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"}],
         "groups": []},
        {"fact_id": "f-377", "value": 209586000000.0,
         "dimensions": [{"axis": "srt_ProductOrServiceAxis","member": "aapl_IPhoneMember"}],
         "groups": []}
      ]
    },
    {
      "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"}
         ],
         "groups": []}
      ]
    },
    {
      "axes": ["srt_StatementGeographicalAxis"],
      "facts": [
        {"fact_id": "f-1104", "value": 151790000000.0,
         "dimensions": [{"axis":"srt_StatementGeographicalAxis","member":"country_US"}],
         "groups": []}
      ]
    }
  ],
  "credits_used": 28
}

4.10 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:

Response:

Member granularity within a group: Same as POST /data/facts/dimensional-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:

Example Request:

{
  "ticker": "AAPL",
  "form_type": "10-K",
  "fiscal_year": 2025,
  "line_item": "revenue"
}

Example MCP tool call:

get_dimensional_breakdown_by_line_item(
    ticker="AAPL", form_type="10-K", fiscal_year=2025, line_item="revenue"
)

Example Response (abridged):

{
  "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": [ /* same shape as 4.9 */ ]
    },
    {
      "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
}

4.11 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; per-line-item × per-filing pricing applies. Results are consolidated totals only, same as §4.4.

Request:

Response:

Light-weight mode (light_weight_mode=true): each results[*].facts[*].dimensional_breakdowns is set to null. A notice is appended to top-level _warnings.

Partial-credit behavior: This endpoint charges per line item × per filing with partial-credit billing. If your balance is too low to cover the full request mid-run, later line items will return as unresolved rather than abort the whole call; check _warnings / _correction to see which were skipped, then top up and re-issue for the rest.

Errors:

Example Request:

{
  "filings": [
    { "ticker": "AAPL", "form_type": "10-K", "fiscal_year": 2024 },
    { "ticker": "AAPL", "form_type": "10-K", "fiscal_year": 2023 }
  ],
  "line_items": ["revenue"]
}

Example MCP tool call:

compare_line_items(
    filings=[
        {"ticker": "AAPL", "form_type": "10-K", "fiscal_year": 2024},
        {"ticker": "AAPL", "form_type": "10-K", "fiscal_year": 2023},
    ],
    line_items=["revenue"],
)

Example Response:

{
  "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": 80
}

4.12 POST /data/compare/facts

Purpose: Compare XBRL fact_ids across up to 25 filings. Each filing row carries its own fact_ids list.

Request:

Response: Same shape as POST /data/compare/line-items. A _warnings entry is appended when the compared filings' fiscal period end dates differ by more than 45 days.

Light-weight mode (light_weight_mode=true): each results[*].facts[*].dimensional_breakdowns is set to null. A notice is appended to top-level _warnings.

Partial-credit behavior: Full request cost is ceil(total_deduped_fact_ids / 5) × 10 credits. The endpoint uses partial-credit billing, so if your balance can only cover part of the request you'll be charged that much and the response serves a proportional subset of the fact_ids (each 10 credits buy up to 5 ids; filings are processed in request order — once the budget runs out the remaining filings come back with facts: []). A _warnings[0] line states how many ids were served vs requested, and credits_used reflects what was actually spent. Zero balance → HTTP 402.

Errors:

Example Request:

{
  "filings": [
    { "filing_id": 12345, "fact_ids": ["ix_1", "ix_2"] },
    { "filing_id": 12344, "fact_ids": ["ix_1"] }
  ]
}

Example MCP tool call:

compare_facts(
    filings=[
        {"filing_id": 12345, "fact_ids": ["ix_1", "ix_2"]},
        {"filing_id": 12344, "fact_ids": ["ix_1"]},
    ],
)

4.13 GET /data/filings/{filing_id}/excel

Purpose: Obtain a time-limited download URL for the filing’s Excel attachment when the file is available.

Path parameter: filing_id (integer).

Response:

Errors:

Example MCP tool call:

get_filing_excel(filing_id=12345)

Example Response:

{
  "ticker": "AAPL",
  "fiscal_year": 2024,
  "download_url": "https://api.akkrudata.ai/...",
  "expires_in": 3600,
  "credits_used": 300
}

5. Metrics API

All routes accept X-API-Key as in Section 1. Endpoints in this section require the Starter plan or higher; Free callers receive 403 PLAN_TIER_INSUFFICIENT (see Section 8). The formula_override request field is additionally gated to the Pro plan or higher — Starter callers can use these endpoints but must omit formula_override.

Response conventions

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

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

When a metric cannot be computed, derivation does not name a computation path — it mirrors that metric's status, so values such as missing_input and needs_price_data also appear here. Branch on status first.

Currency and FX

A metric object may carry these three currency-related fields:

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:

To convert a foreign-issuer absolute metric to USD:

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-weight mode

All /metric/* endpoints accept light_weight_mode (boolean, default false). When true, each returned metric object is reduced to its essential fields. The following per-metric fields are removed:

Fields retained: value, status, derivation, unit, currency, fx_required, fx_rate_used, formula, price_used, and any per-metric flags (split_adjusted_value etc.).

A notice is appended to _warnings. Credits are charged identically. Re-issue with light_weight_mode=false (or omit it) for the full payload.

5.0 Supported metric catalog

The API exposes 43 metrics, listed below by category. Use the name column verbatim wherever the API or MCP tools take 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 §5.2).

Profitability (4)

Returns (4)

Leverage (4)

Liquidity (3)

Efficiency / activity (7)

Cash flow & shareholder returns (3)

Valuation — price-sensitive (12) ★

These require current_price in the request body to compute their realtime values; without it the realtime block returns the standard missing-price hint instead.

Tip: populate current_price from any realtime quote source (e.g. Finnhub, Alpha Vantage, yfinance).

Growth (6)

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.

Notes:

• A given filing may not have every metric — values requiring symbols absent from that filing simply do not appear in the response. The catalog above lists everything the API can return, not what every filing contains.
• 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.

5.1 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:

Response:

Errors:

Example Request:

{
  "ticker": "AAPL",
  "fiscal_year": 2024
}

Example MCP tool call:

list_metric_snapshots(ticker="AAPL", fiscal_year=2024)

Example Response:

{
  "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"
    }
  ]
}

5.2 POST /metric/all

Purpose: Return the full metrics object for one metric_group_id, including realtime price-sensitive metrics when the caller supplies current_price, and optional formula overrides.

Request:

Response:

Errors:

Example Request:

{
  "metric_group_id": 12345,
  "current_price": 225.0,
  "formula_override": {
    "operating_margin": {
      "concepts": ["us-gaap_GrossProfit", "us-gaap_SellingGeneralAndAdministrativeExpense"],
      "operators": ["-"]
    }
  }
}

Example MCP tool call:

get_metrics_bundle(
    metric_group_id=12345,
    current_price=225.0,
    formula_override={
        "operating_margin": {
            "concepts": ["us-gaap_GrossProfit", "us-gaap_SellingGeneralAndAdministrativeExpense"],
            "operators": ["-"],
        }
    },
)

Example Response:

{
  "credits_used": 148,
  "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):

{
  "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,
        "split_adjusted_value": 2.43,
        "split_adjustment_factor": 10.0,
        "comparable_to_post_split_basis": false
      }
    }
  }
}

5.3 POST /metric/all/filing-date

Purpose: Same metrics bundle as POST /metric/all, but returns only the filing-date price block — no realtime computation. Use this when you don't need today's market price (analyzing historical filings, batch loads, or any case where current stock price is irrelevant).

Request: Same body fields as POST /metric/all minus current_price and current_fx_rate. See the note below.

Note on realtime-only fields: Sending current_price or current_fx_rate returns 422 VALIDATION_ERROR (type: extra_forbidden) without charging credits. If you need realtime price-sensitive metrics, call POST /metric/all instead.

Response: Same shape as POST /metric/all except price_sensitive_metrics contains only filing_date_price + historical (no realtime); price_context is not present.

Credits: Same flat 148 as POST /metric/all.

Errors: Same as POST /metric/all.

Example Request:

{
  "metric_group_id": 12345
}

Example MCP tool call:

get_metrics_bundle_filing_date(metric_group_id=12345)

5.4 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:

Credits: 148 per successful debit.

Response:

Errors: Same classes as POST /metric/all, plus:

Example Request:

{
  "metric_group_id": 12345,
  "metric_names": ["revenue", "net_income"]
}

Example MCP tool call:

get_metrics_subset(metric_group_id=12345, metric_names=["revenue", "net_income"])

Example Response:

{
  "credits_used": 148,
  "metric_group_id": 12345,
  "metric_group_id": 12345,
  "valuation_context": {    "as_of_date": null,
    "accept_suggested_formula": false,
    "formula_override": null,
    "metric_names": ["revenue", "net_income"]
  },
  "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": {
    "revenue": { "value": 383285000000.0, "unit": "USD" },
    "net_income": { "value": 93736000000.0, "unit": "USD" }
  },
  "price_sensitive_metrics": {}
}

5.5 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:

Credits: 55 (base) + 148 × (number of rows in periods for this response). If the base debit succeeds but the per-row debit fails, you receive 402 with an explanation; the base 55 credits are spent.

Response:

Errors:

Example Request:

{
  "ticker": "AAPL",
  "period_type": "quarterly",
  "page": 1,
  "page_size": 2
}

Example MCP tool call:

get_metrics_timeseries(ticker="AAPL", period_type="quarterly", page=1, page_size=2)

Example Response:

{
  "page_info": {
    "current_page": 1,
    "total_pages": 5,
    "page_size": 2,
    "total_items": 10,
    "next_page_hint": "Use the same request body with \"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": {
        "filing_date_price": 222.91,
        "historical": {
          "market_cap": { "value": 3300000000000.0, "unit": "USD" }
        }
      }
    }
  ]
}

5.6 Category endpoints (/metric/<category>)

Seven endpoints returning curated metric sets — margins, growth, leverage, efficiency, cash-flow, valuation. Use these when you want a coherent slice of metrics without enumerating names. Flat 148 credits, rate limit 60/minute.

Request body (5 simple categories + /metric/valuation): metric_group_id required (1–10⁹). Optional: accept_suggested_formula, formula_override, as_of_date, current_price, current_fx_rate, light_weight_mode — same semantics as on POST /metric/all. 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. light_weight_mode 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. For /metric/valuation and /metric/valuation/filing-date the price_insensitive_metrics block is always {} (all 12 valuation ratios are price-sensitive).

Errors: METRIC_GROUP_NOT_FOUND, CREDITS_INSUFFICIENT, standard 422 VALIDATION_ERROR.

Example MCP tool call:

get_profitability_metrics(metric_group_id=46)

6. Screener API

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.

§6.5 screens insider trades rather than metrics; its rows use the transaction object defined in §7. §6.9 screens institutional 13F filings; its rows use the snapshot object, also defined in §7.

Plan-tier gate: Every endpoint in this section requires the Pro plan or higher; Free / Starter callers receive 403 PLAN_TIER_INSUFFICIENT (see Section 8). The MCP wrappers (search_stocks, list_screener_filters, search_insider_trades) forward the same REST endpoints and surface the same 403 envelope.

Pricing note: Filters that touch price-sensitive metrics (market_cap, enterprise_value, all 12 valuation ratios) use the price observed on each filer's filing date; these dates differ across filers. For same-day cross-ticker comparison, call POST /metric/all per ticker with a common current_price.

6.1 POST /screener/metrics

Purpose: Return filings that match a DSL filter tree, grouped by ticker (default) or flattened.

Request body (APIRequest, extra="forbid"):

Pagination cap: page × page_size ≤ 500 (validation 422). Use larger page_size rather than more pages. Tighten filters to look beyond the first 500 results.

Response (group_by_ticker=true, default):

{
  "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 ticker */
      ]
    }
  ],
  "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.

Each results[] entry (grouped or flat) also carries an industry classification block — see §1.10.

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:

"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-ticker filings[] ordering is fixed at filing_date DESC, period_end DESC (newest first), independent of where.sort_order. For time-series ordering, use group_by_ticker=false with sort_by="period_end" or "filing_date".

Errors: 422 VALIDATION_ERROR (schema), 402 CREDITS_INSUFFICIENT, 504 QUERY_TIMEOUT when the query exceeds the 30-second server timeout (the request is charged; tighten filters and retry).

Example MCP tool call:

search_stocks(lookback=5, include_quarterly=False,
              where={"filter": {"metric": "return_on_equity", "op": ">", "value": 0.2, "for_latest": 5}},
              page_size=10)

6.2 GET /screener/metrics/filters

Purpose: Discovery — returns the supported metric catalog, operators, temporal modifiers, form types, derivations, and one complete example request. 10 credits.

{
  "metrics": [
    {"name": "return_on_equity", "unit": "ratio", "price_sensitive": false},
    {"name": "market_cap", "unit": "usd", "price_sensitive": true}
    /* ... 43 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 */ }
}

sectors lists the 12 canonical buckets accepted by the POST /screener/metrics sectors filter (§1.10).

Example MCP tool call:

list_screener_filters()

6.3 Filter DSL (/screener/metrics)

Leaf node

{"metric": "<name>", "op": "<operator>", "value": <number | [lo, hi]>,
 "for_latest": <N> | "for_consecutive": <N> | "for_at_least": <N>}

= / != are not supported in v1. For equality matching use between [v − ε, v + ε].

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)

N ≥ 1 and N ≤ lookback. Tickers without enough filings in lookback to evaluate the modifier are filtered out.

Composite nodes

{"and": [<node>, <node>, …]}
{"or":  [<node>, <node>, …]}
{"not": <node>}

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

6.4 Credit formula (/screener/metrics)

POST /screener/metrics charges per call (paginate ⇒ each page bills independently):

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:

Charge applies even when results is empty, and on 504 QUERY_TIMEOUT. No charge only on 422 VALIDATION_ERROR, 402 CREDITS_INSUFFICIENT, or 403 PLAN_TIER_INSUFFICIENT (all rejected before any deduction).

GET /screener/metrics/filters charges 10 credits flat.

6.5 POST /screener/ownership

Purpose: Full-library transaction screening. Trade-level conditions plus company-level aggregate gates; returns the matching transactions.

Request:

Pagination cap: page × page_size ≤ 500 (422).

Response:

Every row carries accession_number, filing_date, source_url_prefix, insiders, the 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 MCP tool call:

search_insider_trades(start_date="2026-04-01", tickers=["AAPL"],
                      trade_filters={"transaction_code": ["P", "S"]}, page_size=10)

6.6 Filters (/screener/ownership)

trade_filters:

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).

6.7 Credit formula (/screener/ownership)

POST /screener/ownership charges per call:

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).

6.8 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:

Pagination cap: page × page_size ≤ 500 (422).

holding_filters:

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:

Every row carries accession_number, filing_date, period_of_report, no_securities_owned, source_url_prefix, insiders, and the holding object.

Credits: the §6.7 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 MCP tool call:

search_initial_holdings(tickers=["TSLA"], holding_filters={"is_derivative": False}, page_size=10)

6.9 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 defined in §7, 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:

Pagination cap: page × page_size ≤ 500 (422).

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. In particular, each manager's earliest quarter in the data window has null portfolio_value_qoq_pct, est_turnover and activity_counts (no prior quarter to compare against), so conditions on those fields never match it.

Response: matches (snapshot rows with cik / name), total_matches, page, page_size, credits_used, and — exactly when the returned rows cover more than one quarter — a _warnings entry saying the rows span quarters and the same manager can appear once per quarter.

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 MCP tool call:

search_institutional_holdings(start_date="2026-01-01", end_date="2026-03-31",
                    conditions=[{"field": "total_positions_value", "op": ">=", "value": 100000000000}],
                    page_size=10)

6.10 Credit formula (/screener/institutional-holdings)

POST /screener/institutional-holdings charges per call (paginate ⇒ each page bills independently):

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.

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).

7. Ownership API

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 (§1.9) and history window (§1.8) apply as they do elsewhere, on the filing's filing_date; the 13F endpoints are organized by the filing manager (institution), not by company. The endpoints in this section are available on every plan; full-library screening is POST /screener/ownership, POST /screener/initial-holdings and POST /screener/institutional-holdings in Section 6, which require Pro or higher.

Credits are deducted before the query runs, so a 404 or 403 raised afterwards is still charged.

Transaction object

Returned by POST /ownership/transactions, POST /ownership/transaction-ids, and POST /screener/ownership.

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:

"split_adjusted": {
  "shares": 4000.0,
  "price_per_share": 125.86,
  "shares_owned_following": 48000.0,
  "split_adjustment_factor": 4.0,
  "comparable_to_post_split_basis": false
}

Absent means the filed values are already on the current per-share basis. split_adjustment_factor and comparable_to_post_split_basis carry the same meaning and the same presence rule as on the metrics API (§5.2).

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, value is null, status is "unavailable", and computed_as states the reason.

7.1 POST /ownership/transactions

Purpose: Anchored listing of insider-trade filings and their transactions. Requires ticker and/or insider_cik; unanchored queries belong to §6.5.

Request:

At least one of ticker / insider_cik is required (422 otherwise).

Response:

Credits: 30 per page.

Errors: 404 OWNERSHIP_COMPANY_NOT_FOUND (charged), 403 PLAN_TIER_INSUFFICIENT_COVERAGE when the ticker is outside your plan's coverage scope (charged), 422 VALIDATION_ERROR, 402 CREDITS_INSUFFICIENT.

Example MCP tool call:

list_insider_transactions(ticker="AAPL", transaction_code=["P", "S"], page_size=5)

7.2 POST /ownership/stats

Purpose: Aggregate statistics over one company and/or one insider, plus the ids of every transaction that contributed.

Request:

At least one of ticker / insider_cik is required.

Response: stats, method_applied, start_date_applied, as_of_date_applied, anomalies_excluded_count, credits_used, optional corporate_actions, optional _warnings, then ids_total, ids_page, ids_has_more, transaction_ids.

Key names inside stats follow method: acquired / disposed for ad, bought / sold for ps.

corporate_actions is present only when the request is anchored on a ticker that has corporate actions on file: 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 ticker is outside your plan's coverage scope (charged), 422 VALIDATION_ERROR, 402 CREDITS_INSUFFICIENT.

Example MCP tool call:

get_insider_stats(ticker="AAPL", start_date="2025-01-01", method="ad")

7.3 POST /ownership/transaction-ids

Purpose: Fetch transactions by id — the detail companion to the transaction_ids returned by §7.2.

Request:

Response: same envelope as §7.1, plus missing_ids when some ids were not found and restricted_ids when some exist but are outside your plan's scope. Both are charged for.

Credits: ceil(n / 5) × 10 on the deduplicated id count (max 200).

Errors: 404 OWNERSHIP_TRANSACTION_NOT_FOUND when none of the requested ids exist (charged; the response carries missing_ids). 403 PLAN_TIER_INSUFFICIENT_HISTORY 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 MCP tool call:

get_insider_transactions_by_id(transaction_ids=[123456, 123457])

7.4 GET /ownership/tickers

Purpose: Discovery — every ticker with insider-trade or initial-holdings coverage. Unpaginated; cache the result.

Response: tickers (array of {ticker, jurisdiction, cik, forms}), credits_used, and optional _warnings. forms lists what the ticker has on file: "4" insider transactions, "3" initial holdings.

Credits: 175.

Errors: 402 CREDITS_INSUFFICIENT.

Example MCP tool call:

list_insider_tickers()

7.5 POST /ownership/names

Purpose: All insiders of one company, aggregated per CIK across its Form 4 and Form 3 filings.

Request:

Response: names, credits_used, and optional _warnings. Each name carries:

Credits: 30.

Errors: 404 OWNERSHIP_COMPANY_NOT_FOUND (charged), 403 PLAN_TIER_INSUFFICIENT_COVERAGE when the ticker is outside your plan's coverage scope (charged).

Example MCP tool call:

list_company_insiders(ticker="AAPL", relationship=["ever_officer"])

7.6 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.

Example MCP tool call:

list_insider_transaction_types()

Holding object

Returned by POST /ownership/initial-holdings, POST /ownership/initial-holding-ids, and POST /screener/initial-holdings. A Form 3 reports positions held on becoming an insider, so a holding has no transaction date, code, price, or direction.

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: present only when the filed values are not on the current per-share basis.

"split_adjusted": {
  "shares_owned": 4000.0,
  "underlying_security_shares": null,
  "conversion_or_exercise_price": null,
  "split_adjustment_factor": 4.0,
  "comparable_to_post_split_basis": false
}

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).

7.7 POST /ownership/initial-holdings

Purpose: Anchored listing of initial beneficial-ownership filings (Form 3) and their holdings. Requires ticker and/or insider_cik; unanchored queries belong to §6.8.

Request:

At least one of ticker / insider_cik is required (422 otherwise).

Response:

Credits: 30 per page.

Errors: 404 OWNERSHIP_COMPANY_NOT_FOUND (charged), 403 PLAN_TIER_INSUFFICIENT_COVERAGE when the ticker is outside your plan's coverage scope (charged), 422 VALIDATION_ERROR, 402 CREDITS_INSUFFICIENT.

Example MCP tool call:

list_initial_holdings(ticker="TSLA", page_size=5)

7.8 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:

At least one of ticker / insider_cik is required.

Response: stats, start_date_applied, as_of_date_applied, anomalies_excluded_count, credits_used, optional corporate_actions, optional _warnings, then ids_total, ids_page, ids_has_more, holding_ids.

corporate_actions is present only when the request is anchored on a ticker that has corporate actions on file: 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 ticker is outside your plan's coverage scope (charged), 422 VALIDATION_ERROR, 402 CREDITS_INSUFFICIENT.

Example MCP tool call:

get_initial_holding_stats(ticker="TSLA", start_date="2020-01-01")

7.9 POST /ownership/initial-holding-ids

Purpose: Fetch holdings by id — the detail companion to the holding_ids returned by §7.8.

Request:

Response: same envelope as §7.7, plus missing_ids when some ids were not found and restricted_ids when some exist but are outside your plan's scope. Both are charged for.

Credits: ceil(n / 5) × 10 on the deduplicated id count (max 200).

Errors: 404 OWNERSHIP_HOLDING_NOT_FOUND when none of the requested ids exist (charged; the response carries missing_ids). 403 PLAN_TIER_INSUFFICIENT_HISTORY 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 MCP tool call:

get_initial_holdings_by_id(holding_ids=[1234, 1235])

Snapshot object

Returned by POST /screener/institutional-holdings (as matches[], with cik and name) and POST /ownership/institutional-holdings/manager-history (as quarters[], without them — the manager identity sits once at the top of that response). One row = one manager × one calendar quarter, after amendments are merged.

Each manager's earliest quarter in the data window has no prior quarter to compare against: its portfolio_value_qoq_pct, est_turnover and activity_counts are null and must not be read as everything being new.

Institutional holding object

Returned by POST /ownership/institutional-holdings/portfolio and POST /ownership/institutional-holdings/security (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).

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 manager's earliest data-window 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 and must not be read as everything being new.

7.10 POST /ownership/institutional-holdings/manager-history

Purpose: One manager's 13F history — one snapshot object per quarter filed, newest first by default.

Request:

Response: manager (cik, name, sec_url_prefix — the manager's EDGAR directory prefix), quarters (snapshot rows), total_quarters, page, page_size, credits_used.

Credits: 30.

Errors: 404 OWNERSHIP_MANAGER_NOT_FOUND when no single manager matches (charged) — several managers can file under the same or a similar name; query by CIK instead. 422 VALIDATION_ERROR, 402 CREDITS_INSUFFICIENT.

Example MCP tool call:

get_institutional_manager_history(cik="1000097", page_size=8)

7.11 POST /ownership/institutional-holdings/portfolio

Purpose: One manager × one quarter — the holdings detail as institutional holding objects, under a quarter header that repeats the snapshot numbers and carries the amendment archive.

Request:

Response: manager (as in §7.10); quarter — a 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, total_transactions, page, page_size, credits_used, and _warnings (see the 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.