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.

A small number of authentication failures (401 missing API key, 403 invalid API key) still return "detail" as a plain string. Any other 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 L1 (alias) 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 (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, 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 reports 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"}
  ],
  "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 are mutually exclusive on the wire — a row carries either the singular pair or the plural list, never both. Iterate by reading whichever is present.

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 raw XBRL 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). Resolved through a tiered exact / llm path against the filing's role labels. 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. Not yet available for Korean (DART), Japanese (EDINET), or European (ESEF) filings — coming soon (not charged); use role_label mode for KR/JP/EU.

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 (exact) / 48 (llm), partial-credit billing. Zero-balance → HTTP 402.
• statement_type mode: 28 flat. No charge for DATA_STATEMENT_NOT_AVAILABLE_IN_FILING.

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_sheet, 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 (canonical statement-type label; may be 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, rate limit 60/minute. No charge on DATA_STATEMENT_NOT_AVAILABLE_IN_FILING. Not yet available for Korean (DART), Japanese (EDINET), or European (ESEF) filings — coming soon (not charged).

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.

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.

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.

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": {
    "splits_after_period_end": [
      { "ex_date": "2024-06-10", "ratio": 10.0, "type": "forward" }
    ],
    "splits_in_lookback": [
      { "ex_date": "2021-07-20", "ratio": 4.0,  "type": "forward" },
      { "ex_date": "2024-06-10", "ratio": 10.0, "type": "forward" }
    ],
    "split_factor_to_today": 10.0,
    "summary": "10:1 forward split on 2024-06-10. Multiply per-share values from this filing by 10 to compare with current-basis quotes."
  },
  "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.

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.

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 15-second server timeout (the request is charged; tighten filters and retry).

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

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 (the query runs before it times out — that compute is the billable unit). 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 15-second server timeout (charged).

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

7. Ownership API

Insider trades reported to the SEC. US filings only. The plan coverage scope (§1.9) and history window (§1.8) apply as they do elsewhere, on the filing's filing_date. The endpoints in this section are available on every plan; full-library screening is POST /screener/ownership in Section 6, which requires 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.

Flagged rows are excluded from POST /ownership/stats unless include_anomalies=true, and from POST /screener/ownership unless trade_filters.include_anomalies=true.

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.

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 splits: an array of {ex_date, ratio, 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.

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.

7.4 GET /ownership/tickers

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

Response: tickers (array of {ticker, jurisdiction, cik}), credits_used, and optional _warnings.

Credits: 175.

Errors: 402 CREDITS_INSUFFICIENT.

7.5 POST /ownership/names

Purpose: All insiders of one company, aggregated per CIK.

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

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.

8. API key, account, and plan errors

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.

9. Request limits (validation)

These caps apply at validation time (422 when exceeded):

10. MCP access

The Data and Metrics API is also exposed as a Model Context Protocol (MCP) server at:

https://api.akkrudata.ai/mcp

Authenticate via one of the two methods below. Both share your AkkruData account, credits, and rate limits.

10.1 Connect via OAuth (recommended for AI assistants)

For AI clients with built-in MCP support (Claude Desktop, Claude Web, etc.):

1. In your AI client, add https://api.akkrudata.ai/mcp as a custom MCP connector.
2. Click Connect. Your browser will open an AkkruData sign-in page.
3. Sign in with the same credentials you use for the dashboard (email/password, Google, or GitHub).
4. Review the connecting AI client's reported identity, then click Authorize.
5. Done. The AI client now holds a token and can call AkkruData on your behalf. Token renewal is automatic.

You can list and disconnect any authorized AI client at any time from the dashboard's Connected AI assistants panel. A single account may have up to 10 simultaneous AI client connections.

10.2 Connect via X-API-Key (programmatic use)

Available only on deployments where MCP OAuth is disabled.

For scripted MCP clients, local development, or any setup where you cannot run the OAuth browser flow:

URL:     https://api.akkrudata.ai/mcp
Header:  X-API-Key: <your-api-key>

The same API key used for REST works for MCP. Create and rotate keys from the dashboard.

10.3 Tool catalog

Each linked section includes an Example MCP tool call with the exact tool name, arguments to pass, and the response shape to expect.

AkkruData — API & MCP user guide.