# Search & Extraction — Finradar API
> Version: 3.61.0 | Generated: 2026-06-20 | Content Hash: 571d2292
> Fetch this file at: https://uat.finradarapi.com/llms/search-and-extraction.txt

## Authentication
All endpoints require an API key. Pass it via query parameter `?apiKey=YOUR_KEY` or header `X-API-Key: YOUR_KEY`. WebSocket endpoints accept the key in the `token` auth payload or query parameter.

---

## Search & Extraction

Advanced text search and content extraction.

### POST /api/v1/scrapping/query/

Advanced Boolean Search.

**Token cost:** 25 tokens per call

**Response fields:**
- `filings` (array): Array of filings matching the query, in sec-api.io's exact response shape. Sorted by `filedAt DESC` (newest first). Empty array on no match — never null. Compatible with existing client code that already parses sec-api.io responses.
- `filings[].accessionNo` (string): SEC accession number in canonical `XXXXXXXXXX-YY-NNNNNN` format. Matches sec-api.io's `accessionNo` field naming. Pass to `GET /api/v1/sec/filings/{accession_number}` to drill into the filing's documents in FinRadar's flatter shape.
- `filings[].cik` (string): Filer CIK as a 10-character zero-padded string. The same CIK always refers to the same legal entity across decades — a stable join key against EDGAR submissions, our `filings` table, and Sharadar SF1.
- `filings[].ticker` (string (nullable)): Ticker resolved from the filer CIK via the `ticker_norm_aliases` lookup. Null when the filer has no public-equity ticker (private funds, individuals, foreign issuers without ADRs, dissolved entities). Multi-class issuers return the primary share class.
- `filings[].formType` (string): Canonical SEC form type (e.g. `10-K`, `10-Q`, `8-K`, `4`, `13F-HR`, `S-1`, `20-F`). Amendment variants append `/A`. NT-prefixed and -NT-suffixed forms (e.g. `NT 10-K`, `13F-NT`) appear verbatim — these have no information table.
- `filings[].filedAt` (string): ISO-8601 UTC timestamp of the filing's SEC acceptance moment. Matches sec-api.io's `filedAt` field shape (full timestamp, NOT just the date).
- `filings[].periodOfReport` (string (nullable)): ISO `YYYY-MM-DD` period the filing covers (the fiscal-period-end-date for 10-K/10-Q, the trade date for Form 4, etc.). Null for filings that don't have a meaningful period (e.g. some 8-Ks, S-1 initial registrations). Differs from `filedAt` — `periodOfReport` is the as-of date, `filedAt` is the disclosure date.
- `filings[].linkToFilingDetails` (string): Canonical SEC EDGAR URL for the filing's index page (lists all documents in the filing package). Use as the human-readable link in dashboards; for programmatic document access use the `/html` companion endpoints which return parsed content.
- `total` (object): sec-api.io-compatible total-hits block: `{ value: integer, relation: 'eq' | 'gte' }`. The deep-pagination cap fires at 10000 hits — beyond that, switch to date-range chunking (`filedAt:[A TO B]`) since pagination cannot reach further.
- `total.value` (integer): Total hit count for the full query. Exact when `relation='eq'`; lower-bound when `relation='gte'` (i.e. 'at least this many; the deep-pagination cap was reached').
- `total.relation` (string): `eq` = exact total; `gte` = the deep-pagination cap was hit (only triggers when matching > 10000 filings). Use to detect when you need to switch to date-range chunking for full enumeration.

**Since:** v1.0.0

**Utility:** sec-api.io-compatible advanced filing search using Lucene-syntax boolean queries — drop-in for customers migrating from sec-api.io's `/full-text-search` query endpoint. Supports field-scoped filters (`ticker:`, `formType:`, `cik:`, `filedAt:[from TO to]`), boolean operators (`AND`/`OR`/`NOT`), wildcards (`tesla*`), and grouping (`(formType:10-K OR formType:10-Q) AND ticker:AAPL`). The single most powerful metadata-query endpoint in the FinRadar surface — analyst pipelines that need 'all 10-Ks from S&P 500 issuers in 2025' in one shot. Returns paginated filing metadata in sec-api.io's exact response shape (`filings[]` + `total: {value, relation}`). For full-text inside filing exhibits use `POST /api/v1/scrapping/search/`; for raw row-shaped reads use `GET /api/v1/sec/filings`.

**Use case:** Precise filtering: 'Give me all 10-Ks from Apple or Microsoft filed in 2023'.

**Parameters:**
- `query` (body, required): Lucene-style query string. Field-scoped: `ticker:AAPL`, `formType:"10-K"` (quote multi-word values), `cik:0000320193`, `filedAt:[2025-01-01 TO 2025-12-31]`. Operators: `AND`, `OR`, `NOT`. Wildcards: `tesla*`, `apple?`. Grouping: `(formType:10-K OR formType:10-Q) AND ticker:AAPL`. Bare-word queries match against issuer.name. Identical syntax to sec-api.io's full-text-search endpoint.
- `limit` (body, optional, default: 50): Maximum filings returned, capped at 50 server-side per page (matches sec-api.io's per-page cap). For deeper pagination use the `from` field if your client supports it; for full backfills, prefer date-range chunking via the `query.filedAt:[A TO B]` syntax.

**Sample response:**
```json
{
  "filings": [
    {
      "accessionNo": "0000320193-25-000123",
      "cik": "0000320193",
      "ticker": "AAPL",
      "formType": "10-K",
      "filedAt": "2025-11-01T20:14:32.000Z",
      "periodOfReport": "2025-09-28",
      "linkToFilingDetails": "https://www.sec.gov/Archives/edgar/data/320193/000032019325000123/0000320193-25-000123-index.htm"
    }
  ],
  "total": {
    "value": 1,
    "relation": "eq"
  }
}
```

### POST /api/v1/scrapping/search/

Full-Text Search.

**Token cost:** 25 tokens per call

**Response fields:**
- `hits` (array): Array of text-match windows, sorted by relevance (BM25-style scoring) then `filed_date DESC` as a tiebreaker. A single filing can contribute multiple hits if the query phrase appears in multiple sections. Empty array on no match — never null.
- `hits[].accession_number` (string): SEC accession number of the filing containing this hit. Pass to `GET /api/v1/sec/filings/{accession_number}` for filing metadata, or to `GET /api/v1/scrapping/extractor` (with the matching `section`) to retrieve the full item text.
- `hits[].ticker` (string (nullable)): Resolved ticker for the issuer (canonical hyphen form). Null when the filer has no public-equity ticker (private funds, individuals, foreign issuers without ADRs). Useful for drilling: filter hits to S&P 500 issuers client-side via the resolved ticker.
- `hits[].form_type` (string): Canonical SEC form type containing the hit (e.g. `10-K`, `10-Q`, `8-K`, `DEF 14A`, `S-1`, `20-F`). Filter client-side to narrow the corpus by form (e.g. only `8-K`s for material-event surveillance).
- `hits[].filed_date` (string): ISO `YYYY-MM-DD` filing acceptance date in ET. Sort hit lists by this descending to surface most-recent occurrences. Newer hits typically score lower than older hits in BM25 unless the recency-boost flag is on (off by default).
- `hits[].section` (string): Item or exhibit identifier where the match was located (e.g. `Item 7` for MD&A, `Item 1A` for Risk Factors, `EX-99.1` for press-release exhibits, `EX-10.1` for material contracts). Pass this directly to `/scrapping/extractor`'s `item` parameter to retrieve the full section.
- `hits[].snippet` (string): 200-300 character text window centered on the match, with the query phrase wrapped in HTML `<em>` tags for direct rendering. Edge characters may be word-broken — for clean rendering use a CSS truncation/ellipsis pattern. Plain text otherwise (no other HTML).
- `meta` (object): Result metadata: `{ total: integer, next_cursor: string|null }`. `total` is the full-corpus match count (cap-aware — values > 10000 surface as `gte`-style estimates). `next_cursor` is the opaque pagination cursor for the next page; null on last page.

**Since:** v1.0.0

**Utility:** Full-text search across the actual extracted text content of every SEC filing — 10-K Risk Factors, 10-Q MD&A, 8-K material event narratives, exhibit text, and proxy statements. The differentiator vs metadata-only `/scrapping/query/`: this scans the words IN the filings, not just the filing headers. Drives keyword surveillance workflows (e.g. 'every 8-K mentioning bankruptcy filed this week', 'every 10-K with going-concern doubt language', 'every proxy mentioning a specific named executive'). Returns hit windows with the matching phrase wrapped in `<em>` tags for direct highlight rendering. Use this to locate the filings, then call `/scrapping/extractor` to retrieve the full item once you've found the right hit.

**Use case:** Searching for specific keywords like 'bankruptcy' or 'merger' across millions of filings.

**Parameters:**
- `query` (body, required): Search term — single word, multi-word phrase (auto-quoted as a phrase search), or quoted exact-match string. Boolean operators NOT supported on this endpoint (use `/scrapping/query/` for boolean syntax). Multi-word queries match the phrase exactly, not the bag-of-words. Stemming and case-folding apply (`bankruptcy` matches `bankrupt` and `BANKRUPTCY`).
- `limit` (body, optional, default: 10): Maximum hit windows returned, capped at 50 server-side. Each hit is a 200-300 character text window centered on the match — for narrower scrolls, drop limit to 5-10; for sweeping audits, set to 50 and paginate via `meta.next_cursor`.

**Sample response:**
```json
{
  "hits": [
    {
      "accession_number": "0000320193-25-000123",
      "ticker": "AAPL",
      "form_type": "10-K",
      "filed_date": "2025-11-01",
      "section": "Item 1A",
      "snippet": "...material adverse effect on our <em>supply chain</em> and..."
    }
  ],
  "meta": {
    "total": 412,
    "next_cursor": "eyJpZCI6..."
  }
}
```

### GET /api/v1/scrapping/extractor

Extract a specific item section from a SEC filing — a sec-api.io Extractor replica. Supports 10-K, 10-Q and 8-K form types (20-F / 40-F are rejected with 400). The COMPLETE item section is returned in a single response — no length cap or truncation (a large 10-K Item 1A can run tens of thousands of characters).

**Token cost:** 25 tokens per call

**Response fields:**
- `(response body)` (string): This endpoint returns the extracted section as a RAW STRING body — NOT a JSON envelope. Content-Type is `text/plain` for `type=text` and `text/html` for `type=html`. The `text/html` body is allowlist-sanitized (nh3) before return (no `<script>`, no event-handler attributes, no non-http(s) URLs) and PRESERVES inline heading style (font-weight / font-size / text-decoration) while dropping color/background/positioning. The `X-Extractor-Mode` response header reports which path produced the body (`text` | `structured` | `legacy_html` | `notfound` | `pending`). An invalid item-for-form, or an unsupported form (20-F / 40-F), returns HTTP 400 (and is NOT billed). A valid item that is simply absent from the filing returns HTTP 404 (also NOT billed). On a cold-cache first fetch of a large filing the server may return HTTP 503 + `Retry-After` with `X-Extractor-Mode: pending` (also NOT billed) while it prepares the section in the background — retry to get the body. Body length ranges from ~1K to 100K+ characters (Item 1A on a large 10-K can exceed 100K).

**Since:** v3.3.1

**Utility:** Surgical item-level extraction from 10-K, 10-Q and 8-K filings — return just the Risk Factors (10-K Item 1A), just the MD&A (10-K Item 7 / 10-Q Part I Item 2), or a single 8-K event item (e.g. 2.02 Results of Operations), without parsing the full filing. Powers sentiment-analysis pipelines, NLP topic models, year-over-year diff tools, and LLM-grounded research workflows that need surgically-clean input text. ONE in-house BeautifulSoup engine locates the section and renders it two ways (`type=text` plain text, `type=html` style-preserving HTML). 10-K items supported: 1, 1A, 1B, 1C, 2, 3, 4, 5, 6, 7, 7A, 8, 9, 9A, 9B, 9C, 10–16 (bare codes). 10-Q items supported: PART-PREFIXED `part1item1`…`part2item6` (e.g. `part1item2` = MD&A, `part2item1a` = Risk Factors) — the Part prefix disambiguates the Part I / Part II Item-number collision. 8-K items supported: dotted event codes 1.01–9.01 (e.g. 2.02, 5.02, 8.01) plus `signature`. Foreign annual reports (20-F / 40-F) are NOT supported here — use the stock-research business-description endpoint for those. Use `POST /api/v1/scrapping/search/` to locate the right filing first.

**Use case:** Extracting 'Risk Factors' (10-K Item 1A) for sentiment analysis, the MD&A from a 10-Q (Part I Item 2), or an 8-K's 'Results of Operations' (Item 2.02) for earnings-event monitoring.

**Parameters:**
- `url` (query, required): Direct URL of the filing's primary HTML document on SEC EDGAR (NOT the index page — must be the actual HTML body of the 10-K/20-F). Get this from `filings[].linkToFilingDetails` then drill into the document URL, or from the `filing_url` field on `/api/v1/sec/filings`. Server-side rejected if the URL is not on the `sec.gov` domain or returns non-HTML content.
- `item` (query, required): Item code to extract — the FORMAT depends on `form_type`. **10-K** bare canonical codes: `1`, `1A`, `1B`, `1C`, `2`, `3`, `4`, `5`, `6`, `7`, `7A`, `8`, `9`, `9A`, `9B`, `9C`, `10`–`16` (case-insensitive, `1a` = `1A`). **10-Q** PART-PREFIXED codes: `part1item1`…`part2item6` (e.g. `part1item2` = MD&A, `part2item1a` = Risk Factors) — the Part prefix is REQUIRED so a Part I vs Part II Item number can never resolve to the wrong section; a bare `item=1` on a 10-Q is rejected with 400. **8-K** dotted event codes: `2.02`, `5.02`, `9.01`, … (the hyphen form `2-2` is also accepted and normalized to `2.02`) plus `signature` — 8-K codes require `form_type=8-K`. An item code that is not valid for the given form returns **400** (refunded, not billed). A valid item that is simply absent from that particular filing returns **404** (also refunded).
- `type` (query, optional, default: text): Output format — ONE located section, two renderings (the in-house engine runs the SAME detection for both). `text` (default) returns clean plain-text: tags stripped, HTML entities kept literal (e.g. `&#160;`), tables wrapped between `##TABLE_START` / `##TABLE_END` markers — best for NLP pipelines and LLM grounding. `html` returns STYLE-PRESERVING HTML: the filing's native heading styling (inline `font-weight` / `font-size` / `text-decoration`) is KEPT, while `color` / background / positioning and ALL XSS vectors (`<script>` tags, event-handler attributes, `javascript:` URLs) are stripped via an allowlist sanitizer (nh3) — safe to render in a browser. The response is a RAW string body (Content-Type `text/plain` for `text`, `text/html` for `html`), NOT a JSON envelope. Read the `X-Extractor-Mode` response header to see which path produced the body. On a cold-cache first fetch of a large filing the server may return HTTP 503 with `X-Extractor-Mode: pending` and a `Retry-After` header while it prepares the section in the background — this response is NOT billed; retry after a few seconds. Cost is identical across formats.
- `form_type` (query, optional, default: 10-K): Form type of the filing — selects the item-code grammar and detection rules. One of `10-K` (default), `10-Q`, or `8-K`. Any other value (e.g. `20-F`, `40-F`) returns **400** ('not supported'), refunded. Because the `item` grammar is form-specific (10-Q needs Part-prefixed codes like `part1item2`, 8-K needs dotted codes like `2.02`), you MUST set `form_type` correctly for 10-Q and 8-K — leaving the `10-K` default with a 10-Q/8-K item yields a 400.

**Sample response:**
```json
"<p style=\"font-weight:bold;font-size:10pt\">ITEM 1A. RISK FACTORS</p>\n<p style=\"font-size:10pt;font-weight:normal\">You should carefully consider the risks described below together with the other information set forth in this report, which could materially affect our business, financial condition and operating results...</p>"
```

### GET /api/v1/scrapping/xbrl

Convert XBRL to JSON. Pass either the XBRL document URL OR the accession number — accession is auto-extracted from the URL if only the URL is provided.

**Token cost:** 25 tokens per call

**Response fields:**
- `accession_number` (string): SEC accession number of the source filing in canonical `XXXXXXXXXX-YY-NNNNNN` format (always normalized to dashed form regardless of input).
- `form_type` (string): Source filing's form type as detected from the XBRL instance metadata (typically `10-K`, `10-Q`, `8-K`, `20-F`, `40-F`). Useful for cost-budgeting downstream processing (10-Ks have 800-2000 facts; 8-Ks typically have 5-50).
- `period_end` (string): ISO `YYYY-MM-DD` reporting period end of the filing's primary context (the fiscal-quarter or fiscal-year end). For 10-K/10-Q this is the canonical period the financials cover; for 8-K it's the event date.
- `facts` (array): Array of XBRL fact rows. One row per `(concept, period, dimensions)` tuple — same concept can appear multiple times if reported across multiple periods or dimensional members (e.g. revenue by geographic segment). Empty array for filings that have no XBRL (rare; typically only NT amendments and some pre-2010 archival filings).
- `facts[].concept` (string): Concept name in `prefix:LocalName` format. Standard concepts use the `us-gaap:` prefix (e.g. `us-gaap:Revenues`, `us-gaap:NetIncomeLoss`, `us-gaap:Assets`); company-specific extensions use the company's own prefix (e.g. `aapl:iPhone`, `tsla:VehicleSales`). Pass to `GET /api/v1/facts/by-concept` for cross-company aggregations of the same concept.
- `facts[].value` (number (nullable)): Numeric fact value in the unit specified by `facts[].unit`. Null for textual or non-numeric facts (e.g. company description, accounting policy strings). NOT scale-adjusted — values are reported as-filed; reconcile against `unit` to interpret (e.g. value=391035 + unit=USD-thousands means $391.035M).
- `facts[].unit` (string (nullable)): XBRL unit reference. Common values: `USD` (US dollars at 1:1 scale), `shares` (raw share count), `pure` (dimensionless ratios — typically `0-1`), `USD-per-share` (per-share dollar values), `iso4217:JPY`/`iso4217:EUR` (foreign currencies). Null only when `value` is null (textual facts). Always check unit before arithmetic — companies routinely mix `USD` and `USD-thousands` within the same filing.
- `facts[].period_start` (string (nullable)): ISO `YYYY-MM-DD` start date for duration concepts (income-statement and cash-flow facts that cover a period). Null for instant concepts (balance-sheet facts that are point-in-time at `period_end`). Use the `period_start` + `period_end` pair to detect Q vs YTD vs TTM scope.
- `facts[].period_end` (string): ISO `YYYY-MM-DD` end date for the fact. For instant concepts this is the as-of date; for duration concepts this is the period end. Always present.
- `facts[].dimensions` (object (nullable)): XBRL dimensional context as a `{axis: member}` map (e.g. `{StatementBusinessSegmentsAxis: 'IPhoneSegmentMember'}`). Null when the fact has no dimensional qualifier (the most common case — un-dimensioned facts represent the consolidated entity). Use to filter segment-level vs total-level facts (`facts.filter(f => f.dimensions === null)` returns the consolidated view).

**Since:** v1.0.0

**Utility:** Parses a single SEC XBRL filing's instance document into a clean array of fact rows: `concept`, `value`, `unit`, `period_start`, `period_end`, `dimensions`. Use this when you need the AS-FILED facts for a specific accession (e.g. to reconcile a 10-K's reported revenue against your downstream model, or to extract a custom company-specific concept like `aapl:iPhone`). For cross-company standardized financial-statement queries — where you want apples-to-apples Revenue/NetIncome across 7,000+ filers — use `GET /api/v1/financials/metrics` instead, which standardizes the messy as-filed facts into a clean canonical schema. Either input is sufficient: pass the direct XBRL document URL, or pass just the accession number and we auto-resolve the document.

**Use case:** Extracting financial statements (Balance Sheet, Income Statement) in a structured format.

**Parameters:**
- `xbrl_url` (query, optional): Direct URL of the XBRL instance document on SEC EDGAR (the `.xml` or inline-XBRL `.htm` file containing tagged facts — NOT the filing index page). Server-side rejected if not on `sec.gov`. At least one of `xbrl_url` or `accession_number` is required; if both are passed, `xbrl_url` takes precedence.
- `accession_number` (query, optional): SEC accession number with or without dashes (e.g. `0000320193-24-000123` or `000032019324000123` both work). When passed alone, the server auto-resolves the primary XBRL instance document by fetching the filing's index page. At least one of `xbrl_url` or `accession_number` is required.

**Sample response:**
```json
{
  "accession_number": "0000320193-25-000123",
  "form_type": "10-K",
  "period_end": "2025-09-28",
  "facts": [
    {
      "concept": "Revenues",
      "value": 391035000000,
      "unit": "USD",
      "period_start": "2024-09-29",
      "period_end": "2025-09-28"
    },
    {
      "concept": "NetIncomeLoss",
      "value": 96995000000,
      "unit": "USD",
      "period_start": "2024-09-29",
      "period_end": "2025-09-28"
    }
  ]
}
```

### GET /api/v1/scrapping

Live SEC EDGAR scrape with form-type + CIK + date filtering. Returns filings synthesized by a Python subprocess that scrapes EDGAR's search pages — heavier and slower than the local-index `/api/v1/sec/filings` endpoint. Use this when you need filings that haven't been ingested locally yet, or when you need EDGAR's search-page-specific fields not stored in the local index.

**Token cost:** 10 tokens per call

**Response fields:**
- `query` (object): Echo of the resolved query parameters used for the EDGAR scrape — useful for debugging when results don't match expectations.
- `query.formType` (string): Echoed form type (uppercased). Confirms the `form_Type` param was parsed correctly.
- `query.result` (integer): Count of filings returned in `filings[]` after date filtering. Equals `filings.length`.
- `filings` (array): Array of filing records as scraped from SEC EDGAR's search pages. Schema differs from `GET /api/v1/sec/filings`'s normalized schema — uses EDGAR-native field names. Empty array on no match. The cost-zero distinction: this is a heavyweight call (10 tokens) that runs a Python subprocess against EDGAR; use the local index endpoint when possible.
- `filings[].accession_Number` (string): SEC accession number in canonical 18-char dashed format `XXXXXXXXXX-YY-NNNNNN`. CamelCase field name (`accession_Number`) reflects EDGAR's stored form.
- `filings[].cik` (string): Filer CIK as zero-padded 10-character string.
- `filings[].formType` (string): Canonical SEC form type (e.g. `10-K`, `10-Q`, `8-K`, `4`, `13F-HR`).
- `filings[].filingDate` (string): ISO date `YYYY-MM-DD` of the filing's SEC acceptance date in ET. CamelCase field name reflects EDGAR's stored form.
- `filings[].linkToFilingDetails` (string): Canonical SEC EDGAR URL for the filing's index page. Pass this to [GET /api/v1/sec/document?url=...](/docs/sec-filings/sec-filings-api/get-sec-document) to fetch the filing body.

**Since:** v1.0.0

**Utility:** Live scrape against SEC EDGAR's search pages — heavier (10 token cost reflects the full-EDGAR roundtrip via a Python subprocess) and slower than `GET /api/v1/sec/filings` (which hits the local index instantly and costs only 5 tokens). Use this when: (a) you need filings that haven't been ingested locally yet (very recent filings before the RSS poller catches them), (b) you specifically want EDGAR's search-result schema rather than FinRadar's normalized schema, (c) you're integrating from a tutorial that referenced this endpoint and don't want to refactor. For 99% of workflows prefer [GET /api/v1/sec/filings](/docs/sec-filings/sec-filings-api/get-sec-filings) — it's faster, cheaper, and self-healing (auto-backfills via this scrape on first-touch). Note: returns a different envelope shape than the rest of the SEC Filings API (`{query, filings}` rather than `ApiResponse.success`).

**Use case:** Tutorial follow-along where the example is parameterized for `/scrapping`. For new integrations, prefer `/sec/filings`.

**Parameters:**
- `form_Type` (query, optional, default: 10-K): Form type to scrape (`10-K`, `10-Q`, `8-K`, `4`, `13F-HR`, `S-1`, etc. — see [SEC EDGAR form types](https://www.sec.gov/forms)). Note the CamelCase param name (`form_Type` not `form_type`) — preserved verbatim from EDGAR's URL convention. Defaults to `10-K` when omitted.
- `cik` (query, optional): 10-char zero-padded CIK to filter by. Use the CIK rather than ticker — EDGAR's search index is CIK-keyed. Resolve a ticker → CIK via [GET /api/v1/scrapping/cik](/docs/sec-filings/search-and-extraction/get-scrapping-cik) first.
- `count` (query, optional, default: 0): Number of filings to return. `0` (default) means "unlimited" — beware on large issuers. Cap at 40 for predictable latency.
- `size` (query, optional, default: 10): Page size for EDGAR's pagination (1-40). Mirrors EDGAR's `count` URL param verbatim. Lower values reduce per-call latency.
- `start_Date` (query, optional): Lower-bound filing date in `YYYY-MM-DD` format. CamelCase param name (`start_Date`) preserved from EDGAR's URL convention. Filtered client-side after EDGAR returns — does NOT reduce upstream load.
- `end_Date` (query, optional): Upper-bound filing date in `YYYY-MM-DD` format. Filtered client-side after EDGAR returns.

**Sample response:**
```json
{
  "query": {
    "formType": "10-K",
    "result": 1
  },
  "filings": [
    {
      "accession_Number": "0000320193-25-000123",
      "cik": "0000320193",
      "formType": "10-K",
      "filingDate": "2025-11-01",
      "linkToFilingDetails": "https://www.sec.gov/Archives/edgar/data/320193/000032019325000123/0000320193-25-000123-index.htm"
    }
  ]
}
```

### GET /api/v1/scrapping/cik

Get filings for a specific CIK via EDGAR scrape. Returns filings filtered by form type and optional date range. Useful when you need EDGAR's search-result schema for a specific CIK rather than FinRadar's normalized schema.

**Token cost:** 10 tokens per call

**Response fields:**
- `query` (object): Echo of the resolved query parameters used for the EDGAR scrape — useful for debugging when results don't match expectations.
- `query.formType` (string): Echoed form type (uppercased).
- `query.result` (integer): Count of filings returned in `filings[]` after EDGAR-level date filtering.
- `query.count` (integer): Echoed `count` parameter — useful for assertion in tests.
- `filings` (array): Array of filing records as scraped from SEC EDGAR's filer-detail pages. Schema uses EDGAR-native field names. Empty array on no match — never null.
- `filings[].accession_Number` (string): SEC accession number in canonical 18-char dashed format `XXXXXXXXXX-YY-NNNNNN`.
- `filings[].cik` (string): Filer CIK as zero-padded 10-character string. Echoes the input.
- `filings[].formType` (string): Canonical SEC form type as filed (echoes the `form_Type` filter).
- `filings[].filingDate` (string): ISO date `YYYY-MM-DD` of the filing's SEC acceptance date in ET. Within the `start_Date`..`end_Date` window when those filters are passed.
- `filings[].linkToFilingDetails` (string): Canonical SEC EDGAR URL for the filing's index page. Pass to [GET /api/v1/sec/document?url=...](/docs/sec-filings/sec-filings-api/get-sec-document) to fetch the filing body.

**Since:** v1.0.0

**Utility:** CIK-keyed live EDGAR scrape — pass a 10-char zero-padded CIK and a form type, receive that filer's filings of that type as scraped from EDGAR's search pages. Heavier than `GET /api/v1/sec/filings?cik=...` (which is the local-index path) — use this when: (a) the local index is missing recent filings for this CIK and you need EDGAR's live data, (b) you specifically need EDGAR's search-result schema, (c) you're following a tutorial that referenced this endpoint. Date filtering happens at SEC level so date-bounded queries are server-efficient. The non-standard CamelCase param names (`form_Type`, `start_Date`, `end_Date`) are preserved verbatim from EDGAR's URL convention.

**Use case:** Given Apple's CIK (0000320193), retrieve their last 10 10-K filings from EDGAR directly with `cik=0000320193&form_Type=10-K&count=10`.

**Parameters:**
- `cik` (query, required): 10-char zero-padded CIK to query (e.g. `0000320193` for Apple). Returns 400 BAD_REQUEST when missing. Resolve a ticker → CIK via [GET /api/v1/scrapping/cik](/docs/sec-filings/search-and-extraction/get-scrapping-cik) — wait, that's THIS endpoint — use [GET /api/v1/sec/entities](/docs/sec-filings/sec-filings-api/get-sec-entities) which returns `(entity_name, cik)` pairs, or query [GET /api/v1/sec/filings?ticker=...](/docs/sec-filings/sec-filings-api/get-sec-filings)'s response which surfaces the CIK in `meta.cik`.
- `form_Type` (query, optional, default: 10-K): Form type to filter by (`10-K`, `10-Q`, `8-K`, `4`, `13F-HR`, `S-1`, etc. — see [SEC EDGAR form types](https://www.sec.gov/forms)). CamelCase param name preserved from EDGAR's URL convention. Defaults to `10-K`.
- `count` (query, optional, default: 10): Maximum number of filings to return (1-40 recommended). Date filtering happens at SEC level so this is the upper bound on EDGAR's return set, not just the post-filter count.
- `start_Date` (query, optional): Lower-bound filing date in `YYYY-MM-DD` format. Filtered at SEC level — reduces upstream load.
- `end_Date` (query, optional): Upper-bound filing date in `YYYY-MM-DD` format. Filtered at SEC level.

**Sample response:**
```json
{
  "query": {
    "formType": "10-K",
    "result": 2,
    "count": 10
  },
  "filings": [
    {
      "accession_Number": "0000320193-25-000123",
      "cik": "0000320193",
      "formType": "10-K",
      "filingDate": "2025-11-01",
      "linkToFilingDetails": "https://www.sec.gov/Archives/edgar/data/320193/000032019325000123/0000320193-25-000123-index.htm"
    },
    {
      "accession_Number": "0000320193-24-000123",
      "cik": "0000320193",
      "formType": "10-K",
      "filingDate": "2024-11-01",
      "linkToFilingDetails": "https://www.sec.gov/Archives/edgar/data/320193/000032019324000123/0000320193-24-000123-index.htm"
    }
  ]
}
```

### GET /api/v1/scrapping/form-10

Scrape 10-K and 10-Q filings. Returns filing metadata + extraction-ready URLs for the primary document. Use /api/v1/scrapping/extractor to extract specific sections (Item 1A Risk Factors, Item 7 MD&A, etc.).

**Token cost:** 10 tokens per call

**Response fields:**
- `query` (object): Echo of input parameters.
- `query.formType` (string): Always `"Form 10"` (covers both 10-K and 10-Q variants).
- `query.link` (string): Echoed input URL — useful for tracing the scrape source.
- `data` (object): Scrape result envelope.
- `data.status` (string): Scrape outcome — `"success"` on parse + DB-persist success, `"error"` on subprocess or parse failure.
- `data.message` (string (nullable)): Human-readable status message (e.g. `"Filing saved successfully"` on success, exception text on error).
- `data.filing_id` (integer (nullable)): Internal `filings.id` row ID assigned when the scrape result was persisted to the local DB. Null on scrape error.
- `data.uuid` (string (nullable)): UUIDv4 generated server-side for cross-environment tracking of the persisted record.
- `data.data` (object): Parsed filing record — see `data.data.*` fields. Uses sec-api.io-style CamelCase field names.
- `data.data.cik` (string (nullable)): Filer CIK as parsed from the index page (zero-padding NOT applied — may be the un-padded form). Null when the index page format is unrecognized.
- `data.data.ticker` (string (nullable)): Resolved ticker via SEC's `company_tickers.json` lookup (matched by zero-padded CIK). Empty string when the CIK has no public ticker.
- `data.data.formType` (string (nullable)): Form type as parsed from the filer info block (e.g. `10-K`, `10-Q`).
- `data.data.description` (string): Filing description from EDGAR's filing-name header (e.g. `"Apple Inc. 10-K"`).
- `data.data.accessionNo` (string): SEC accession number in canonical 18-char dashed format `XXXXXXXXXX-YY-NNNNNN`.
- `data.data.filingdate` (string): Filing date as displayed on EDGAR's index page (text format — typically `YYYY-MM-DD` but exact form depends on EDGAR's display convention).
- `data.data.accepted` (string): Filing accepted timestamp as displayed on EDGAR (typically `YYYY-MM-DD HH:MM:SS`).
- `data.data.periodOfReport` (string): Period of report as displayed on EDGAR (typically `YYYY-MM-DD` for 10-K/10-Q — the fiscal-period-end date).
- `data.data.documentFormatFiles` (array): Array of structured document descriptors `[{Seq, Description, Document, Type, Size}, ...]` from the index page's "Document Format Files" table. The primary HTML/PDF body of the filing is in this list.
- `data.data.dataFiles` (array): Array of XBRL/data file descriptors from the index page's "Data Files" table. Populated when XBRL is embedded; empty array on filings without XBRL.
- `data.data.companyNameLong` (string): Filer's full legal name with embedded EDGAR metadata (e.g. `"APPLE INC. (CIK: 0000320193) (Filer)"`).
- `data.data.companyName` (string): Cleaned filer name without embedded metadata (e.g. `"APPLE INC."`).
- `data.data.linkToXBRL` (string): Direct URL to the XBRL instance document. Pair with [GET /api/v1/scrapping/xbrl?xbrl_url=...](/docs/sec-filings/search-and-extraction/get-scrapping-xbrl) for parsed financial facts.
- `data.data.linkToTxt` (string): Direct URL to the filing's primary HTML or TXT document body. Pair with [GET /api/v1/scrapping/extractor?url=...](/docs/sec-filings/search-and-extraction/get-scrapping-extractor) for surgical item extraction.
- `data.data.original_link` (string): Echoed input `link` parameter.

**Since:** v1.0.0

**Utility:** Single-filing 10-K/10-Q scraper — pass the EDGAR index-page URL of a filing and receive full filer metadata (CIK, ticker, fiscal year end, state of incorporation, SIC, file number), the structured `documentFormatFiles[]` and `dataFiles[]` lists from the index page, and direct URLs to the primary document HTML and the XBRL instance. Use this when you have a 10-K/10-Q URL (from EDGAR search, an RSS alert, a research email) and want the structured filing record without writing your own EDGAR scraper. The 10-token cost reflects the full-EDGAR roundtrip + the BeautifulSoup parse. For surgical item extraction (just Item 1A Risk Factors, just Item 7 MD&A) prefer [GET /api/v1/scrapping/extractor](/docs/sec-filings/search-and-extraction/get-scrapping-extractor) which costs the same but returns the parsed item text directly. For the local-index version (which gives you the same `all_links` array but at 5 tokens), use [GET /api/v1/sec/filings/{accession_number}](/docs/sec-filings/sec-filings-api/get-sec-filings-accession-number).

**Use case:** An RSS alert delivered an Apple 10-K URL — call this endpoint to get the parsed filer metadata + the XBRL instance URL + the primary HTML URL in one call.

**Parameters:**
- `link` (query, required): Full SEC EDGAR URL of the filing's index page (NOT the primary document — must be the index page that lists all documents in the filing package). Get from the `linkToFilingDetails` field in `/scrapping/cik` responses, or from the `primary_link` field in `/api/v1/sec/filings` responses. Returns 400 BAD_REQUEST when missing. Server-side fetches via Python subprocess with a 5-minute timeout.

**Sample response:**
```json
{
  "query": {
    "formType": "Form 10",
    "link": "https://www.sec.gov/cgi-bin/browse-edgar?action=getcompany&CIK=0000320193&type=10-K"
  },
  "data": {
    "status": "success",
    "message": "Filing saved successfully",
    "filing_id": 18234567,
    "uuid": "0f14ed05-3a2e-4b76-9c11-1a7c8b3f6de2",
    "data": {
      "cik": "0000320193",
      "ticker": "AAPL",
      "formType": "10-K",
      "description": "Apple Inc. 10-K",
      "accessionNo": "0000320193-25-000123",
      "filingdate": "2025-11-01",
      "accepted": "2025-11-01 20:14:32",
      "document": "aapl-20250928.htm",
      "periodOfReport": "2025-09-28",
      "documentFormatFiles": [
        {
          "Seq": "1",
          "Description": "10-K",
          "Document": "aapl-20250928.htm",
          "Type": "10-K",
          "Size": "12943821"
        }
      ],
      "dataFiles": [
        {
          "Seq": "2",
          "Description": "XBRL Instance Document",
          "Document": "aapl-20250928.xml",
          "Type": "EX-101.INS",
          "Size": "412390"
        }
      ],
      "companyNameLong": "APPLE INC. (CIK: 0000320193) (Filer)",
      "companyName": "APPLE INC.",
      "entities": [],
      "linkToXBRL": "https://www.sec.gov/Archives/edgar/data/320193/000032019325000123/aapl-20250928.xml",
      "linkToTxt": "https://www.sec.gov/Archives/edgar/data/320193/000032019325000123/aapl-20250928.htm",
      "original_link": "https://www.sec.gov/cgi-bin/browse-edgar?action=getcompany&CIK=0000320193&type=10-K"
    }
  }
}
```

### GET /api/v1/scrapping/form-13f

Scrape 13F-HR institutional-holdings filings for a specific CIK. Returns parsed filing metadata + the holdings information table (one row per portfolio position) with CUSIP-level enrichment (ticker, security name, FIGI). Use this for institutional-manager portfolio analysis when you need EDGAR-native field shapes; for the curated FinRadar 13F surface use /api/v1/13f/filer/{cik}/holdings.

**Token cost:** 10 tokens per call

**Response fields:**
- `query` (object): Echo of input parameters.
- `query.cik` (string): Echoed CIK.
- `query.formType` (string): Always `"13-F"` (note the dash — preserved from EDGAR's stored form, distinct from the canonical `13F-HR` used in the local index).
- `query.start_date` (string (nullable)): Echoed start_date param. Null when omitted.
- `query.end_date` (string (nullable)): Echoed end_date param. Null when omitted.
- `query.result` (integer): Count of filings returned in `data` (when `data` is an array) or `1` (when `data` is a single filing object).
- `data` (array): Array of 13F-HR filings, sorted by `filed_date DESC` (newest first). Each element is a parsed 13F filing with embedded holdings table — see `data[].*` for shape. Single-element when `count=1`; up to `count` elements otherwise. Empty array when no filings match — never null.
- `data[].accessionNo` (string): SEC accession number in canonical 18-char dashed format `XXXXXXXXXX-YY-NNNNNN`.
- `data[].cik` (string): Institutional manager CIK (echoes the input).
- `data[].companyName` (string): Manager's legal entity name as registered with SEC (e.g. `BERKSHIRE HATHAWAY INC`).
- `data[].formType` (string): Form type — `13F-HR` for the standard quarterly filing or `13F-HR/A` for amendments. NT-suffixed forms (`13F-NT`) appear here too — these have no information table to drill into.
- `data[].filingDate` (string): ISO date `YYYY-MM-DD` of the filing's SEC acceptance date in ET.
- `data[].periodOfReport` (string): ISO date `YYYY-MM-DD` of the as-of date for the holdings table (typically last day of the calendar quarter — `2025-03-31`, `2025-06-30`, `2025-09-30`, `2025-12-31`).
- `data[].linkToFilingDetails` (string): SEC EDGAR URL for the filing's index page.
- `data[].linkToInformationTable` (string (nullable)): Direct URL to the information-table XML file (the structured holdings list). Null on `13F-NT` filings which have no information table.
- `data[].holdings` (array): Array of portfolio positions parsed from the information table. One row per `(CUSIP, security_class)` pair. Empty array on `13F-NT` filings or filings with empty information tables (rare but legitimate).
- `data[].holdings[].cusip` (string): 9-character CUSIP identifier of the security held.
- `data[].holdings[].nameOfIssuer` (string): Issuer name as reported in the information table (often differs cosmetically from the issuer's canonical name — dedupe via CUSIP not name).
- `data[].holdings[].titleOfClass` (string): Security class (e.g. `COM`, `COM CL A`, `PUT`, `CALL`).
- `data[].holdings[].value` (integer): Market value of the position in USD (NOT in thousands — server-side normalized from the 2022-09-onward `value_in_dollars` form). Rationale: pre-2022-09 13F filings reported `value` in USD-thousands; we convert client-side to a unified USD scale.
- `data[].holdings[].shares` (integer): Share count held (or principal amount for debt instruments).
- `data[].holdings[].sshPrnamtType` (string): Share/principal type — `SH` (shares) or `PRN` (principal amount). Distinguishes equity holdings from debt holdings.
- `data[].holdings[].putCall` (string (nullable)): Option type for derivative positions — `PUT` or `CALL`. Null on direct equity holdings (the most common case).
- `data[].holdings[].ticker` (string (nullable)): Resolved ticker via the local `cusip_mappings` table. Null when the CUSIP is unmapped (private securities, OTC, very-recently-issued).
- `data[].holdings[].security_name` (string (nullable)): Canonical security name from `cusip_mappings`.
- `data[].holdings[].security_type` (string (nullable)): Security type (e.g. `Common Stock`, `Preferred Stock`, `Warrant`, `Option`, `ADR`).

**Since:** v1.0.0

**Utility:** Live 13F-HR scraper — pass an institutional manager's 10-char CIK and receive their most recent 13F-HR filings with full holdings tables (CUSIP, security_name, value_in_thousands, shares, voting_authority breakdown). CUSIPs are enriched server-side via the local `cusip_mappings` table to add ticker, security_type, FIGI, and exchange code. The right surface for: building a custom institutional-portfolio dashboard, replicating sec-api.io's 13F response shape for a migration, exporting BlackRock / Berkshire / Vanguard quarterly holdings to CSV. Heavy (10 tokens) — runs a Python subprocess that fetches the index page + the information table XML, parses both, then enriches CUSIPs via the local DB. For the curated FinRadar 13F surface (faster, cheaper, with split-adjusted positions) use [GET /api/v1/13f/filer/{cik}/holdings](/docs/institutional-holdings/form-13f-api/get-13f-filer-cik-holdings) instead — recommended for new integrations.

**Use case:** Pull Berkshire Hathaway's last 4 quarterly 13F holdings (CIK 0001067983, count=4) to track Buffett's position changes quarter-over-quarter.

**Parameters:**
- `cik` (query, required): Institutional manager CIK as a digit-only string, max 10 digits (e.g. `0001067983` for Berkshire Hathaway, `1364742` for BlackRock). Returns 400 BAD_REQUEST when missing or non-numeric. Resolve a manager name → CIK via [GET /api/v1/sec/entities?form_type=13F-HR](/docs/sec-filings/sec-filings-api/get-sec-entities).
- `start_date` (query, optional): Lower-bound filing date in `YYYY-MM-DD` format. Returns 400 on invalid format. Filtered at SEC level — reduces upstream load.
- `end_date` (query, optional): Upper-bound filing date in `YYYY-MM-DD` format. Returns 400 on invalid format.
- `count` (query, optional, default: 10): Maximum number of 13F-HR filings to return (must be 1-40). Returns 400 outside that range. For quarterly tracking use `count=4` (last year); for full historical use `count=40` (which spans ~10 years for most managers).

**Sample response:**
```json
{
  "query": {
    "cik": "0001067983",
    "formType": "13-F",
    "start_date": null,
    "end_date": null,
    "result": 1
  },
  "data": [
    {
      "accessionNo": "0001067983-25-000004",
      "cik": "0001067983",
      "companyName": "BERKSHIRE HATHAWAY INC",
      "formType": "13F-HR",
      "filingDate": "2025-11-14",
      "periodOfReport": "2025-09-30",
      "linkToFilingDetails": "https://www.sec.gov/Archives/edgar/data/1067983/000106798325000004/0001067983-25-000004-index.htm",
      "linkToInformationTable": "https://www.sec.gov/Archives/edgar/data/1067983/000106798325000004/infotable.xml",
      "holdings": [
        {
          "cusip": "037833100",
          "nameOfIssuer": "APPLE INC",
          "titleOfClass": "COM",
          "value": 78240194000,
          "shares": 300000000,
          "sshPrnamtType": "SH",
          "putCall": null,
          "ticker": "AAPL",
          "security_name": "Apple Inc",
          "security_type": "Common Stock"
        }
      ]
    }
  ]
}
```

### GET /api/v1/scrapping/insider-trading

Scrape an insider trading filing (Form 3 / 4 / 5) by URL. Returns parsed insider identity, issuer, and per-transaction details (transaction date, code, shares, price, post-transaction holdings). Use this for one-off Form 4 lookups when you have the URL; for the curated FinRadar insider transactions surface use /insider-module/api/insiders/transactions/latest.

**Token cost:** 10 tokens per call

**Response fields:**
- `query` (object): Echo of input parameters.
- `query.formType` (string): Always `"Form 4"` — endpoint name preserved even when the underlying filing is a Form 3 or Form 5.
- `query.link` (string): Echoed input URL.
- `data` (object): Parsed Form 3/4/5 record — see `data.*` fields. Camel-cased field names preserved from EDGAR's stored form.
- `data.formtype` (string): Detected form type — `3`, `4`, `5`, `4/A`, etc. Use to route processing logic (Form 3 = initial holdings; Form 4 = changes; Form 5 = annual reconciliation).
- `data.formtitle` (string): Filing title as displayed in the EDGAR viewer (e.g. `"FORM 4 STATEMENT OF CHANGES IN BENEFICIAL OWNERSHIP"`).
- `data.formstatement` (string): The legal statement block from the form header — typically references Section 16(a) of the Securities Exchange Act.
- `data.omb_approval` (object): OMB approval block — `{ombnumber, hoursperresponse}`. Useful for forensic / audit-trail work; ignore for analytics.
- `data.notSubjectToSection16` (boolean): `true` when the insider has marked the "no longer subject to Section 16" checkbox (e.g. departing executives filing a final Form 4). False otherwise.
- `data.rule10b51Plan` (boolean): `true` when the transaction is executed under a pre-arranged Rule 10b5-1 plan (a SEC-sanctioned defense against insider-trading allegations — "I scheduled this sale 6 months ago, not based on material non-public info"). Critical signal for insider-transaction analytics — Rule 10b5-1 sales are pre-planned, raw discretionary sales aren't.
- `data.issuer` (object): Issuer info — see `data.issuer.*` fields.
- `data.issuer.cik` (string (nullable)): Issuer CIK as parsed from the form's issuer block. Null when the parse fails (rare).
- `data.issuer.name` (string (nullable)): Issuer's legal entity name (e.g. `"APPLE INC"`).
- `data.issuer.tradingSymbol` (string (nullable)): Issuer's ticker as reported on the Form 4 (e.g. `"AAPL"`). Authoritative for the filing — use this rather than CIK→ticker lookup if available.
- `data.issuer.transactiondate` (string (nullable)): Date of earliest transaction in the filing (typically the trade date for Form 4).
- `data.amendmentDate` (string (nullable)): Date of original filing when this is an amendment (`/A` suffix). Null on non-amendments.
- `data.individualOrJoint` (string (nullable)): `Individual` or `Joint/Group` — Form 4 supports group filings by multiple insiders sharing a single submission.
- `data.reportingOwners` (array): Array of reporting owners — typically 1 element on individual filings, multiple on joint/group filings. Each entry: `{name, cik, address, relationship: {director, officer, tenPercentOwner, other, officerTitle}}`.
- `data.nonDerivativeTransactions` (array): Array of non-derivative (i.e. direct equity) transactions. Each entry: `{title, transactionDate, transactionCode, transactionAmount, transactionPrice, sharesOwnedFollowingTransaction, ownership}`. Empty array when no direct-equity activity.
- `data.derivativeTransactions` (array): Array of derivative (option / warrant / convertible) transactions. Includes additional fields for strike price, expiration, underlying security. Empty array when no derivative activity.
- `data.signature` (object (nullable)): Signature block — `{signatureName, signatureDate}`. The signature is the insider's electronic signature confirming the filing.

**Since:** v1.0.0

**Utility:** Single-filing Form 3/4/5 scraper — pass an insider-filing URL and receive full structured data: insider identity (name, CIK, role flags for Director/Officer/10%-Owner), issuer info (CIK, name, ticker), per-transaction rows (transaction date, transaction code A/D/M/F/G/X, shares, price, post-transaction holdings), and the Rule 10b5-1 / Section 16 status flags. Heavy (10 tokens) because the Python subprocess fetches + BeautifulSoup-parses the EDGAR Form 4 XML viewer page. For NEW integrations strongly prefer [GET /insider-module/api/insiders/transactions/latest](/docs/insiders/insider-trading-api/get-insiders-transactions-latest) — that's the curated FinRadar insider surface with `total_beneficial_ownership` aggregation and Sharadar sector enrichment, faster + structured for screening. The scrapping endpoint is preserved for: (a) sec-api.io migration compatibility, (b) tutorial follow-along, (c) one-off URL-driven lookups where you don't need the Form-4-as-a-Service structure.

**Use case:** Got a Form 4 URL from an RSS alert ("Tim Cook just sold AAPL") — call this endpoint to immediately parse the transaction details (price, shares, post-transaction holdings).

**Parameters:**
- `link` (query, required): Full SEC EDGAR URL of the Form 4 (or Form 3 / Form 5) viewer page (the page that displays the formatted form, not the XML directly). Returns 400 BAD_REQUEST when missing. Get from `linkToFilingDetails` in `/scrapping/cik` responses or from RSS alert payloads. Server-side fetches via Python subprocess with a 5-minute timeout.

**Sample response:**
```json
{
  "query": {
    "formType": "Form 4",
    "link": "https://www.sec.gov/cgi-bin/browse-edgar?action=getcompany&CIK=0001214156&type=4"
  },
  "data": {
    "formtype": "4",
    "formtitle": "FORM 4 STATEMENT OF CHANGES IN BENEFICIAL OWNERSHIP",
    "formstatement": "OMB APPROVAL Filed pursuant to Section 16(a)...",
    "omb_approval": {
      "ombnumber": "3235-0287",
      "hoursperresponse": "0.5"
    },
    "notSubjectToSection16": false,
    "rule10b51Plan": true,
    "issuer": {
      "cik": "0000320193",
      "name": "APPLE INC",
      "tradingSymbol": "AAPL",
      "transactiondate": "2026-04-15"
    },
    "amendmentDate": null,
    "individualOrJoint": "Individual",
    "reportingOwners": [
      {
        "name": "COOK TIMOTHY D",
        "cik": "0001214156",
        "relationship": {
          "director": false,
          "officer": true,
          "tenPercentOwner": false,
          "other": false,
          "officerTitle": "Chief Executive Officer"
        }
      }
    ],
    "nonDerivativeTransactions": [
      {
        "title": "Common Stock",
        "transactionDate": "2026-04-15",
        "transactionCode": "S",
        "transactionAmount": 50000,
        "transactionPrice": 178.42,
        "sharesOwnedFollowingTransaction": 3128240,
        "ownership": "D"
      }
    ],
    "derivativeTransactions": [],
    "signature": {
      "signatureName": "/s/ Sam Whittington, Attorney-in-Fact",
      "signatureDate": "2026-04-17"
    }
  }
}
```

### GET /api/v1/scrapping/public/{filepath}

Public scraped-file fetch by file path. Reads pre-cached scrape outputs from the public scrapping cache. Used by clients that have a cached file URL from a prior scrape call.

**Token cost:** 10 tokens per call

**Response fields:**
- `content` (string): Raw artifact contents. For text content types (`text/html`, `text/plain`, `application/xml`) returned as decoded UTF-8 text. For binary content types (`application/pdf`, `image/*`) returned as base64-encoded string — decode client-side before consuming. Always non-empty (404 returned when cache miss; never empty-string).
- `content_type` (string): Original SEC `Content-Type` header preserved verbatim (e.g. `text/html; charset=utf-8`, `application/pdf`, `application/xml`, `image/png`). Use this to dispatch the correct decoder client-side — base64 vs UTF-8 — based on the MIME prefix.
- `cached_at` (string): ISO-8601 UTC timestamp when this artifact was first cached at the gateway. The 24-hour TTL is computed from this timestamp — values older than 24h indicate the cache will be revalidated against SEC on the next miss. Use to detect freshness for time-sensitive workflows.
- `size_bytes` (integer): Decoded artifact size in bytes. For text artifacts this is the UTF-8 byte length; for binary artifacts this is the post-base64-decode byte length (i.e. the actual file size, not the inflated base64-string length). Useful for client-side size budgeting (e.g. reject artifacts > 50 MB before downloading).

**Since:** v1.0.0

**Utility:** Fetch a previously-cached SEC filing artifact (raw HTML body, exhibit attachment, XBRL document, image) from FinRadar's gateway cache instead of hitting SEC EDGAR directly. The gateway caches artifacts with a 24-hour TTL — useful for clients that want to avoid SEC's rate limits (10 req/sec per IP) or want deterministic latency for repeated reads of the same artifact. Returns the original SEC `Content-Type` header so binary artifacts (PDFs, images) round-trip correctly. The cache is populated by prior scrape calls — pass a `filepath` you obtained from a previous `/scrapping/extractor` or `/scrapping/form-10` response. For structured item extraction prefer `/scrapping/extractor`; for PDF rendering use `POST /api/v1/scrapping/pdf`.

**Parameters:**
- `filepath` (path, required): Cache-relative path to the artifact (typically mirrors the SEC EDGAR archive path: `edgar/data/{cik}/{accession-no-dashes}/{filename}`). Returned by prior scrape calls in their `cached_filepath` field. URL-encode forward slashes if your HTTP client doesn't auto-encode path params. Returns 404 if the artifact is not cached or has expired past the 24h TTL.

**Sample response:**
```json
{
  "content": "<html><head><title>Form 10-K</title></head>...",
  "content_type": "text/html",
  "cached_at": "2026-05-01T20:55:12.000Z",
  "size_bytes": 481032
}
```

### GET /api/v1/scrapping/sandbox

Scrapping sandbox endpoint. Used for development + integration testing of the scrapping pipeline. Returns synthetic but schema-correct payloads.

**Token cost:** 10 tokens per call

**Response fields:**
- `message` (string): Always the literal string `"sandbox response"` — useful as a smoke-test assertion in CI pipelines (`assert resp.json()['message'] == 'sandbox response'`).
- `request_id` (string): Per-call UUID generated server-side. Surface this in support tickets when integration debugging — operations can grep this directly out of nginx + main_api logs to trace the exact request lifecycle (gateway routing, auth resolution, token debit, response).
- `auth_method` (string): How the gateway authenticated the request: `api_key` (X-API-Key header), `jwt` (Authorization Bearer), or `session` (cookie-based, internal-only). Most production integrations should see `api_key` — anything else may indicate auth-header mis-wiring.
- `cost_debited` (integer): Tokens debited from your balance for this call. Always 10 on the sandbox endpoint. Echoes the `X-Tokens-Charged` response header — useful for asserting your billing-ledger client correctly mirrors the server-side debit.
- `remaining_balance` (integer): Token balance remaining on the account AFTER this debit (i.e. `balance_before - cost_debited`). Use to assert your local balance cache stays in sync with the server-side ledger. When this approaches zero, expect 402 Payment Required on subsequent calls.
- `as_of` (string): ISO-8601 UTC timestamp the response was generated server-side (NOT cached — always reflects request time, since this endpoint is uncached so callers can verify rate-limit + debit semantics on every call).

**Since:** v1.0.0

**Utility:** Verify your API key, the rate-limit headers, and your token-debit ledger end-to-end without consuming production data — call this once on integration day to confirm everything wires up. Returns a deterministic synthetic payload that's schema-identical to what real scrapping endpoints return (same auth headers, same cost-debit semantics, same `request_id` shape). Cost is intentionally non-zero (10 tokens) so the debit shows up in your `/account/transactions` ledger and validates your billing wiring before you run heavier real calls. Idempotent — every call returns the same payload (modulo `request_id`, `as_of`, and `remaining_balance`).

**Sample response:**
```json
{
  "message": "sandbox response",
  "request_id": "a1b2c3d4-...",
  "auth_method": "api_key",
  "cost_debited": 10,
  "remaining_balance": 198432,
  "as_of": "2026-05-01T20:55:12.000Z"
}
```