# SEC Blast API documentation The v3 API serves SEC EDGAR filings as JSON: filings, the documents in them as they were filed, and the entities that file them, under `https://api.secblast.com/v3/`. The routes that read are `GET`; the [Webhooks (API: callbacks)](https://www.secblast.com/docs/webhooks) routes also take `POST`, `PATCH` and `DELETE`. Routes are relative to `https://api.secblast.com/v3`. Pages are generated from the OpenAPI 3.1.0 description. ## Quickstart ### 1. Check that the API is reachable [`GET /v3/health`](https://www.secblast.com/docs/reference/get-health) needs no key. ```bash curl -sS 'https://api.secblast.com/v3/health' ``` Abbreviated response: ```json { "status": "ok", "checks": { "db": "ok", "docs_root": "ok", "store": "ok" } } ``` ### 2. Get a key [Sign in](https://www.secblast.com/signin). Manage keys under [API keys](https://www.secblast.com/dashboard/keys) in your dashboard. ### 3. Make a request Retrieve the five newest 8-K filings: ```bash curl -sS -H "Authorization: Bearer $SECBLAST_API_KEY" \ 'https://api.secblast.com/v3/filings?form=8-K&limit=5' ``` The response is a list of filings (three shown, abbreviated). `GET /v3/filings` returns 50 rows by default, and up to 1000 with `limit`; use `next_cursor` only to go past that. ```json { "data": [ { "accession": "0002057463-26-000023", "form_type": "8-K", "filing_date": "2026-10-09", "items": ["7.01", "9.01"], "primary_name": "Liberty Capital Corp/NV", "doc_count": 13 }, { "accession": "0001914496-26-000150", "form_type": "8-K", "filing_date": "2026-10-09", "items": ["3.02", "7.01"], "primary_name": "Sculptor Diversified Real Estate Income Trust, Inc.", "doc_count": 11 }, { "accession": "0001903596-26-000372", "form_type": "8-K", "filing_date": "2026-10-09", "items": ["1.01", "5.01", "5.02", "8.01", "9.01"], "primary_name": "METROSPACES, INC.", "doc_count": 29 } ], "has_more": true, "next_cursor": "eyJhIjoiMDAwMTkwMzU5Ni0yNi0wMD..." } ``` The same request in Python: ```python import os import requests API = "https://api.secblast.com/v3" session = requests.Session() session.headers["Authorization"] = f"Bearer {os.environ['SECBLAST_API_KEY']}" # The five newest 8-K filings, amendments included (the default order is filing_date, newest first). r = session.get(f"{API}/filings", params={"form": "8-K", "limit": 5}, timeout=30) r.raise_for_status() page = r.json() for filing in page["data"]: print(filing["accession"], filing["filing_date"], filing["form_type"], filing.get("primary_name")) ``` And in TypeScript: ```typescript const API = "https://api.secblast.com/v3"; const key = process.env.SECBLAST_API_KEY; type Filing = { accession: string; filing_date: string; form_type: string; primary_name?: string | null }; type FilingList = { data: Filing[]; has_more: boolean; next_cursor: string | null }; const res = await fetch(`${API}/filings?form=8-K&limit=5`, { headers: { Authorization: `Bearer ${key}` }, }); if (!res.ok) { // Errors are RFC 9457 problem bodies with a stable `code` and a `request_id`. const problem = await res.json(); throw new Error(`${problem.status} ${problem.code}: ${problem.detail} (request ${problem.request_id})`); } const page: FilingList = await res.json(); for (const filing of page.data) { console.log(filing.accession, filing.filing_date, filing.form_type, filing.primary_name); } ``` ### 4. Read a filing's documents Each filing in a list carries its `accession` number. [`GET /v3/filings/{accession}/documents`](https://www.secblast.com/docs/reference/get-filings-accession-documents) lists the documents of that filing, and [`GET /v3/filings/{accession}/documents/{document}`](https://www.secblast.com/docs/reference/get-filings-accession-documents-document) returns one document's stored bytes, by sequence number or filename. Replace the accession number below with one from your own list. ```bash curl -sS -H "Authorization: Bearer $SECBLAST_API_KEY" \ 'https://api.secblast.com/v3/filings/0001829126-26-010431/documents' curl -sS -H "Authorization: Bearer $SECBLAST_API_KEY" \ 'https://api.secblast.com/v3/filings/0001829126-26-010431/documents/1' \ -o document.bin ``` You can also try any route in the browser with the [console](https://www.secblast.com/console). ## Conventions - **Lists** come in one envelope: `{ data, has_more, next_cursor }`. See [Pagination](https://www.secblast.com/docs/pagination). - **Errors** are RFC 9457 problem bodies (`application/problem+json`) with a stable `code` and a `request_id`. See [Errors](https://www.secblast.com/docs/errors). - **Unknown query parameters are rejected** with a 400 instead of being ignored, so a misspelled filter cannot silently return unfiltered data. - **List parameters** (for example `form`) take comma-separated values: `form=8-K,10-Q`. - **Dates** are `YYYY-MM-DD`; **times** are RFC 3339 in UTC. - **Every response** carries an `X-Request-Id` header. Quote it when you write to support. - **`HEAD` and `OPTIONS`** are answered for every path; any other method than `GET` gets a 405. - **New filings** arrive live with `status` `provisional` and become `final` overnight. - **The `snapshot` block.** Responses that can carry values from the SEC's submissions snapshot (acceptance time, report period, entity records, the SEC's filing lists, tickers) include `snapshot: { available, date }`. When `available` is false the response was built from the v3 database alone. ## Routes The API has 82 routes. Each one is described in the [Reference](https://www.secblast.com/docs/reference). | Route | Returns | Key | |---|---|---| | [`GET /v3/callbacks/deliveries`](https://www.secblast.com/docs/reference/get-callbacks-deliveries) | The organization's webhook deliveries, newest first (created_at, then id), with the attempt count, the last status and error, when the next attempt is due (only while pending) and the bytes billed. | Required | | [`GET /v3/callbacks/deliveries/{id}`](https://www.secblast.com/docs/reference/get-callbacks-deliveries-id) | One delivery of the organization with its payload and every attempt (n, at, duration_ms, http_status, error_class, remote_ip, response_excerpt), oldest first. | Required | | [`POST /v3/callbacks/deliveries/{id}/retry`](https://www.secblast.com/docs/reference/post-callbacks-deliveries-id-retry) | Queues one more attempt of a failed delivery now (202, the delivery): it becomes pending and its attempts are not reset. | Required | | [`GET /v3/callbacks/endpoints`](https://www.secblast.com/docs/reference/get-callbacks-endpoints) | The organization's webhook endpoints, newest first, with limits.endpoints (the plan's limit and the active endpoints), each with its health and last 24 hours of deliveries. | Required | | [`POST /v3/callbacks/endpoints`](https://www.secblast.com/docs/reference/post-callbacks-endpoints) | Create a webhook endpoint. | Required | | [`GET /v3/callbacks/endpoints/{id}`](https://www.secblast.com/docs/reference/get-callbacks-endpoints-id) | One webhook endpoint of the organization. | Required | | [`PATCH /v3/callbacks/endpoints/{id}`](https://www.secblast.com/docs/reference/patch-callbacks-endpoints-id) | Change a webhook endpoint. | Required | | [`DELETE /v3/callbacks/endpoints/{id}`](https://www.secblast.com/docs/reference/delete-callbacks-endpoints-id) | Delete a webhook endpoint. | Required | | [`POST /v3/callbacks/endpoints/{id}/replay`](https://www.secblast.com/docs/reference/post-callbacks-endpoints-id-replay) | Queues again the failed and dropped deliveries of one endpoint created in a window (202 {replayed, truncated, last_created_at}): oldest first, at most 10,000 a call (truncated; continue with from = last_created_at). | Required | | [`POST /v3/callbacks/endpoints/{id}/rotate-secret`](https://www.secblast.com/docs/reference/post-callbacks-endpoints-id-rotate-secret) | Rotate the endpoint's signing secret. | Required | | [`POST /v3/callbacks/endpoints/{id}/test`](https://www.secblast.com/docs/reference/post-callbacks-endpoints-id-test) | Sends the endpoint one sample event of a type it takes, signed like any event, with test: true in its envelope and sample data (accession 0000000000-26-000001), and answers with the attempt's outcome: 200 {id, state, delivered, http_status, error_class, duration_ms} once the one attempt is made (a test send is not retried and not billed), or 202 {id, state} when no attempt was made within 12 seconds (it is still sent; see the delivery log). | Required | | [`POST /v3/callbacks/endpoints/{id}/verify`](https://www.secblast.com/docs/reference/post-callbacks-endpoints-id-verify) | Sends the endpoint a new verification challenge (202, the endpoint): it is unverified, and its deliveries are held, until it answers 2xx with exactly the challenge. | Required | | [`GET /v3/companies`](https://www.secblast.com/docs/reference/get-companies) | Companies that are or were SPACs (blank checks, SIC 6770), from the SIC and names in their filing headers over time. | Required | | [`GET /v3/companies/{cik}/periods`](https://www.secblast.com/docs/reference/get-companies-cik-periods) | One concept by fiscal period. | Required | | [`GET /v3/companies/{cik}/segments`](https://www.secblast.com/docs/reference/get-companies-cik-segments) | The company's breakdowns by period from its own dimensional facts: business segment, product or service, geography and major customer; revenue, operating income, assets, long-lived assets, D&A, capital expenditure and (from 2024) segment expenses. | Required | | [`GET /v3/companies/{cik}/standard`](https://www.secblast.com/docs/reference/get-companies-cik-standard) | The company's standard fields by period (fields x periods), from each filing's own statements through a pinned concept map: each value with its status (ok, not_reported, ambiguous, not_applicable; a blank is never a zero), the facts behind it, the rule (candidate:\ or rollup), the map version and fingerprint, and flags (failed identities, scale outliers). | Required | | [`GET /v3/companies/{cik}/statements`](https://www.secblast.com/docs/reference/get-companies-cik-statements) | A company's statement as presented in its latest periodic report (10-K, 10-Q, 10-KT, 10-QT, 20-F, 40-F and amendments) SEC had accepted by as_of that has one: of one kind (with its parentheticals), of one menu category (notes, details, ...) or one role URI; limit \> 1 gives the previous reports' too, newest first. | Required | | [`GET /v3/coverage`](https://www.secblast.com/docs/reference/get-coverage) | Ingest coverage: per feed day the latest non-superseded ingest run and the newest complete reconcile run, overall totals, and the snapshot store. | Required | | [`GET /v3/coverage/count`](https://www.secblast.com/docs/reference/get-coverage-count) | The live filing count, in one small answer that needs no key, for polling: filings (final and provisional; deleted filings are not counted), provisional, deleted, documents, the newest acceptance time and, when this deployment has live ingest, the live daemon's latency over its day. | Not needed | | [`GET /v3/coverage/summary`](https://www.secblast.com/docs/reference/get-coverage-summary) | What v3 holds, in one answer that needs no key: filings by status, documents, document versions, the feed days ingested (first, last, count), filings per filing-date year, amendment links by status, the known coverage gaps (a list maintained by hand) and, when this deployment has live ingest, the live daemon's state and lag. | Not needed | | [`GET /v3/datasets`](https://www.secblast.com/docs/reference/get-datasets) | The catalogue of parsed datasets: per dataset its extractor, forms, deployed version, derive steps, tables, status (available or in_preparation), coverage (the first and last filing date of successful results: a range, not a statement that every filing in it is parsed), estimated row counts, when it last changed, and its parse queue. | Not needed | | [`GET /v3/entities`](https://www.secblast.com/docs/reference/get-entities) | Entity search. | Required | | [`GET /v3/entities/{cik}`](https://www.secblast.com/docs/reference/get-entities-cik) | Most recent as-filed attributes of a CIK, SEC's current entity record from the snapshot (current), roles seen and filing counts. | Required | | [`GET /v3/entities/{cik}/filings`](https://www.secblast.com/docs/reference/get-entities-cik-filings) | SEC's own filing list for the entity (from the submissions snapshot), newest first; each row says whether v3 has the filing. | Required | | [`GET /v3/events/8k/{item}`](https://www.secblast.com/docs/reference/get-events-8k-item) | One 8-K item's structured events across filings, newest first (by filing date, then accession): one row per filing with its events of that item, each a list of fields {value, value_as_found, span, rule_id, rule confidence} read from the item's text; exhibit numbers joined to the filing's documents by type. | Required | | [`GET /v3/events/items`](https://www.secblast.com/docs/reference/get-events-items) | One 8-K item across filings, newest first (by filing date, then accession): the parsed union of header and body items, with which side named it. | Required | | [`POST /v3/feedback`](https://www.secblast.com/docs/reference/post-feedback) | Send feedback to SEC Blast. | Required | | [`GET /v3/filings`](https://www.secblast.com/docs/reference/get-filings) | Search filings. | Required | | [`GET /v3/filings/{accession}`](https://www.secblast.com/docs/reference/get-filings-accession) | One filing with entities, documents, events and its version chain. | Required | | [`GET /v3/filings/{accession}/13f`](https://www.secblast.com/docs/reference/get-filings-accession-13f) | A 13F filing's cover page (contact fields: city, state or country, ZIP code; no street line, no phone), summary page, both lists of other managers, the unit decision of its values (value_unit) and its step in the manager-period's amendment ledger. | Required | | [`GET /v3/filings/{accession}/13f/holdings`](https://www.secblast.com/docs/reference/get-filings-accession-13f-holdings) | The information-table rows of a 13F filing exactly as filed, in document order, with value_usd = value_reported x the unit decision's multiplier (null when the unit is ambiguous or not decided). | Required | | [`GET /v3/filings/{accession}/144`](https://www.secblast.com/docs/reference/get-filings-accession-144) | A Form 144 notice (or 144/A) as filed: issuer with address and phone, seller (CIK from the SEC header's reporting owner; the form names the seller only), relationships, the securities proposed to be sold with broker and approximate sale date, how they were acquired, the seller's sales of the past three months, plan adoption dates, and the notice's amendment chain on previousAccessionNumber (provisional). | Required | | [`GET /v3/filings/{accession}/documents`](https://www.secblast.com/docs/reference/get-filings-accession-documents) | Documents of a filing, in sequence order. | Required | | [`GET /v3/filings/{accession}/documents/{document}`](https://www.secblast.com/docs/reference/get-filings-accession-documents-document) | Stored bytes of one document. | Required | | [`GET /v3/filings/{accession}/documents/{document}/text`](https://www.secblast.com/docs/reference/get-filings-accession-documents-document-text) | The extracted text of one document as the full-text index holds it (text/plain; charset=utf-8): the text that snippet start/end offsets count characters of. | Required | | [`GET /v3/filings/{accession}/events`](https://www.secblast.com/docs/reference/get-filings-accession-events) | Lifecycle events of a filing, oldest first. | Required | | [`GET /v3/filings/{accession}/facts`](https://www.secblast.com/docs/reference/get-filings-accession-facts) | Every XBRL fact of a filing as filed: every instance read (the SEC-extracted one when there is one, else the filer's), facts numbered across them in reading order, each with its concept, context (entity, period, dimensions), unit, the exact value beside the filed text, decimals as filed (INF kept), nil, its duplicate class, and footnotes. | Required | | [`GET /v3/filings/{accession}/formd`](https://www.secblast.com/docs/reference/get-filings-accession-formd) | One Form D notice of an exempt offering as filed: offering (industry, exemptions, first sale, securities, minimum investment, the total offering amount, amount sold and remaining -- whole dollars, or Indefinite as filed -- investors, commissions, finders' fees, proceeds to related persons), every issuer, the related persons, the sales compensation recipients with their states, the header entities, and the offering chain (a D/A restates the whole notice: the chain's latest member is the offering). | Required | | [`GET /v3/filings/{accession}/header`](https://www.secblast.com/docs/reference/get-filings-accession-header) | The stored SGML header (_header.sgml) as text/plain. | Required | | [`GET /v3/filings/{accession}/items`](https://www.secblast.com/docs/reference/get-filings-accession-items) | An 8-K's item sets (the header's, the body's, their union), how they differ, one row per item (source, heading status, spans in the primary document, rule confidence) and the Item 9.01 exhibit rows. | Required | | [`GET /v3/filings/{accession}/items/{code}/text`](https://www.secblast.com/docs/reference/get-filings-accession-items-code-text) | One 8-K item's canonical text (not the filed HTML), cut from the stored primary document only when the document model and the exact bytes are at hand; otherwise text_status says why. | Required | | [`GET /v3/filings/{accession}/nport`](https://www.secblast.com/docs/reference/get-filings-accession-nport) | One N-PORT report as filed: registrant, series, share classes, report date, total assets, liabilities and net assets, monthly flows (sales, reinvestment, redemption) and other gains, monthly total returns per class, its place in the report ledger (an NPORT-P/A restates the whole report: one filing per series and report date is effective), and a page of its holdings in document order: identifiers (CUSIP classified -- a placeholder is never a CUSIP -- ISIN, ticker, LEI, other), balance, units, currency, value in USD, percent of net assets, asset and issuer categories, country, fair value level, and debt, repo, derivative and lending detail as filed. | Required | | [`GET /v3/filings/{accession}/ownership`](https://www.secblast.com/docs/reference/get-filings-accession-ownership) | A Form 3, 4 or 5 (or its /A) as filed: the document's filing-level fields, the issuer, every reporting owner with the whole address and relationship, the SEC header's entities (addresses and phone numbers), the four tables (non-derivative and derivative transactions and holdings) with each row's footnote references and footnote text, the footnotes, the signatures, and the filing's amendment chain (provisional). | Required | | [`GET /v3/filings/{accession}/parsed`](https://www.secblast.com/docs/reference/get-filings-accession-parsed) | Which parsed datasets apply to the filing (13f, 8k_items, sections) and the state of each: status (ok, ok_with_warnings, partial, unparseable, not_applicable; pending, failed or not_parsed while there is no result), the extractor version that last verified the filing and the deployed one, a re-parse in progress, warnings (at most 100), the documents read, the dataset's derive steps for the filing, and a link to the dataset's route for the filing (null while this server does not answer it). | Required | | [`GET /v3/filings/{accession}/parsed/changes`](https://www.secblast.com/docs/reference/get-filings-accession-parsed-changes) | Every earlier version of the filing's parsed data that is kept, newest first: each row of a dataset table a re-parse changed or removed (kind superseded: table, row key, from and to version, reason changed / removed / withdrawn, the old row), each group of rows rebuilt or replaced as a whole (kind replaced: the 13F ledger and manager-period rows, the filing's warning set and result row; the old rows) and each 13F unit decision (kind unit_decision). | Required | | [`GET /v3/filings/{accession}/sections`](https://www.secblast.com/docs/reference/get-filings-accession-sections) | The sections of a 10-K, 10-Q or 20-F: one row per item in force with its key (10k.1a, 10q.p1i2, 20f.3d), status (ok, incorporated_by_reference, combined_with, omitted, reserved, not_found), why an absent item is absent, spans and rule confidence; the amendment scope. | Required | | [`GET /v3/filings/{accession}/sections/{section}/text`](https://www.secblast.com/docs/reference/get-filings-accession-sections-section-text) | One section's canonical text, under the same serving rule, paging, ETag, cache and time limit as an 8-K item's text. | Required | | [`GET /v3/filings/{accession}/statements`](https://www.secblast.com/docs/reference/get-filings-accession-statements) | The filing's statements as presented: every role of the filing (with its R page), and for the roles asked -- by default the statement and cover roles; kind, category, role_no or role_uri name others, notes, policies, tables and details included -- the presentation tree in the filer's order with preferred labels, negating / total / period start and end flags, its calculation arcs, and the columns and cells assembled from the filing's facts (each cell the filed fact: exact value and filed text; a blank is null, never zero; a text block's cell says where its text is). | Required | | [`GET /v3/filings/{accession}/statements/roles`](https://www.secblast.com/docs/reference/get-filings-accession-statements-roles) | The filing's roles without their statements: every role (statements, cover, notes, policies, tables, details) in position order, with its menu category, statement kind, R page, tree size and matches_sec_render, and a link to its statement. | Required | | [`GET /v3/filings/{accession}/tables`](https://www.secblast.com/docs/reference/get-filings-accession-tables) | The tables of a 10-K, 10-Q or 20-F primary document. | Required | | [`GET /v3/filings/{accession}/versions`](https://www.secblast.com/docs/reference/get-filings-accession-versions) | Version chain of the filing's report: the original and every amendment, with how each amendment was linked. | Required | | [`GET /v3/financials/facts`](https://www.secblast.com/docs/reference/get-financials-facts) | One company's facts of one concept across its filings, newest period first (then accession, fact_seq): every fact as filed, with its filing's form, filing date and acceptance time. | Required | | [`GET /v3/financials/frames`](https://www.secblast.com/docs/reference/get-financials-frames) | One concept and period across companies: each company's latest incarnation known at as_of (one per CIK, unit and dimension set), from one index range per filing year, the period being the filed dates. | Required | | [`GET /v3/financials/series`](https://www.secblast.com/docs/reference/get-financials-series) | One company's values of one concept, point in time. | Required | | [`GET /v3/financials/standard`](https://www.secblast.com/docs/reference/get-financials-standard) | One standard field across companies for a calendar frame (CY2024Q4, CY2024; CY2024Q4I for balance-sheet fields): each company's reported value (view latest as of a time, or first_reported) with its facts, rule, map pin and flags; in a quarter frame, a company without a reported quarter gets its quarter derived from its year, nine months, half or first quarter on one basis (monetary flows); ttm=true gives the trailing twelve months ending in the quarter. | Required | | [`GET /v3/forms`](https://www.secblast.com/docs/reference/get-forms) | Form types present (deleted filings excluded) with filing counts, most frequent first. | Required | | [`GET /v3/funds/holdings`](https://www.secblast.com/docs/reference/get-funds-holdings) | The N-PORT holdings of one security across funds, newest filing first: exactly one of cusip (only rows whose filed CUSIP is nine characters), isin or ticker (the holding's identifiers as filed). | Required | | [`GET /v3/funds/{series_id}/reports`](https://www.secblast.com/docs/reference/get-funds-series-id-reports) | A fund series' N-PORT reports, newest report date first. | Required | | [`GET /v3/health`](https://www.secblast.com/docs/reference/get-health) | Liveness: one database round trip, the document root, and whether the snapshot store is usable. | Not needed | | [`GET /v3/offerings`](https://www.secblast.com/docs/reference/get-offerings) | Form D notices across filings, newest first (filing date, accession). | Required | | [`GET /v3/openapi.json`](https://www.secblast.com/docs/reference/get-openapi-json) | This OpenAPI 3.1 document. | Not needed | | [`GET /v3/ownership/insiders/holdings`](https://www.secblast.com/docs/reference/get-ownership-insiders-holdings) | Forms 3/4/5 holding rows (Table I and Table II) across filings, newest filing first, then table and row, with the same filing, issuer, owner and footnote members and the same views as the transactions route. | Required | | [`GET /v3/ownership/insiders/transactions`](https://www.secblast.com/docs/reference/get-ownership-insiders-transactions) | Forms 3/4/5 transaction rows (Table I and Table II) across filings, newest filing first, then table and row. | Required | | [`GET /v3/ownership/institutional/holders`](https://www.secblast.com/docs/reference/get-ownership-institutional-holders) | The effective 13F rows of one CUSIP across managers for one period (as known at as_of), ordered by manager CIK, ledger step and row; options are their own rows. | Required | | [`GET /v3/ownership/institutional/managers/{cik}/holdings`](https://www.secblast.com/docs/reference/get-ownership-institutional-managers-cik-holdings) | A 13F manager's holdings for one period: view=effective applies the amendment ledger (the last restatement or original, plus later additions) as known at as_of; view=as_filed lists the rows of every applied step. | Required | | [`GET /v3/ownership/institutional/managers/{cik}/periods`](https://www.secblast.com/docs/reference/get-ownership-institutional-managers-cik-periods) | One row per period a 13F manager filed for, newest first: ledger steps, base and latest filing, effective rows and reported 13F long value (not assets under management), flags. | Required | | [`GET /v3/ownership/proposed-sales`](https://www.secblast.com/docs/reference/get-ownership-proposed-sales) | Form 144 notices across filings, newest first, each with its securities, acquisitions and past sales. | Required | | [`GET /v3/reports`](https://www.secblast.com/docs/reference/get-reports) | Reports of one entity: one row per version chain (an original plus its amendments), ordered by the original filing's date, newest first (a chain whose original is not ingested is dated by its first ingested amendment). | Required | | [`GET /v3/resolve`](https://www.secblast.com/docs/reference/get-resolve) | Which CIK(s) hold a ticker, from SEC's ticker file; with as_of, from the copy that was current on that date. | Required | | [`GET /v3/search`](https://www.secblast.com/docs/reference/get-search) | Full-text search over every document v3 holds (spec §6.1). | Required | | [`GET /v3/search/parse`](https://www.secblast.com/docs/reference/get-search-parse) | How a query is read, without running it: the normalised query, its tree, the EDGAR reading beside the default one, prefix expansions, the structured filters after alias mapping and ticker resolution, and the index years it would touch. | Required | | [`GET /v3/search/status`](https://www.secblast.com/docs/reference/get-search-status) | State of the full-text index, without a key: per year the document and filing counts, index version and extractor; the live indexer's lag; indexed_through; the years being rebuilt. | Not needed | | [`GET /v3/search/subscriptions`](https://www.secblast.com/docs/reference/get-search-subscriptions) | The organization's subscriptions, newest first, with limits by kind: filter (stored kind filing), firehose and search, each the plan's limit and the active subscriptions. | Required | | [`POST /v3/search/subscriptions`](https://www.secblast.com/docs/reference/post-search-subscriptions) | Create a search subscription. | Required | | [`GET /v3/search/subscriptions/{id}`](https://www.secblast.com/docs/reference/get-search-subscriptions-id) | One subscription of the organization. | Required | | [`PATCH /v3/search/subscriptions/{id}`](https://www.secblast.com/docs/reference/patch-search-subscriptions-id) | Change a search subscription. | Required | | [`DELETE /v3/search/subscriptions/{id}`](https://www.secblast.com/docs/reference/delete-search-subscriptions-id) | Delete a search subscription. | Required | | [`POST /v3/search/subscriptions/{id}/test`](https://www.secblast.com/docs/reference/post-search-subscriptions-id-test) | Preview a search subscription: the payloads the subscription would have produced for filings accepted in the last 7 days (at most 5, newest first), as webhook envelopes with test: true; nothing is delivered or recorded. | Required | | [`GET /v3/sections`](https://www.secblast.com/docs/reference/get-sections) | One section across filings, newest first (by filing date, then accession). | Required | | [`GET /v3/stream`](https://www.secblast.com/docs/reference/get-stream) | The filing stream: a cursor long-poll over every new, updated, corrected and deleted filing. | Required | | [`GET /v3/stream/status`](https://www.secblast.com/docs/reference/get-stream-status) | Stream state: the head cursor, live ingest state, sequencer lag and latency percentiles of the last hour and day. | Not needed | | [`GET /v3/usage`](https://www.secblast.com/docs/reference/get-usage) | The calling key's limits and this month's usage: requests and billable response bytes (measured before compression; 5xx and 429 not billable) of its organization and of the key itself, what is left of the monthly allowance, when it starts again, and which limits are enforced. | Required | ## For language models and tools - [llms.txt](https://www.secblast.com/llms.txt) lists these pages; [llms-full.txt](https://www.secblast.com/llms-full.txt) is all of them in one file. - Every documentation page has a Markdown copy at the same address with `.md` (this page: [/docs/overview.md](https://www.secblast.com/docs/overview.md)). - The machine-readable description is the OpenAPI document: [https://api.secblast.com/v3/openapi.json](https://api.secblast.com/v3/openapi.json). --- # Authentication Most routes need an API key. A key issued on this site belongs to the whole organization. ## Sending the key The API reads the key from one of 3 places: | How | Example | Note | |---|---|---| | `Authorization: Bearer ` | `curl -H "Authorization: Bearer $SECBLAST_API_KEY" 'https://api.secblast.com/v3/filings?limit=1'` | Preferred. | | `X-API-Key: ` | `curl -H "X-API-Key: $SECBLAST_API_KEY" 'https://api.secblast.com/v3/filings?limit=1'` | Equivalent to the Bearer header. | | `?api_key=` | `curl 'https://api.secblast.com/v3/filings?limit=1&api_key='"$SECBLAST_API_KEY"` | The key is part of the URL. | ```bash curl -sS -H "Authorization: Bearer $SECBLAST_API_KEY" \ 'https://api.secblast.com/v3/filings?limit=1' ``` ## When the key is missing or wrong The API answers `401` with a problem body whose `code` is `unauthorized` and a `WWW-Authenticate: Bearer` header. The same answer is given for a missing key, an unknown key and a key that is not active. See [Errors](https://www.secblast.com/docs/errors). ## Getting and managing keys - Your first key is created when you [sign up](https://www.secblast.com/signin). Create, rename, rotate and revoke keys under [API keys](https://www.secblast.com/dashboard/keys). - Keys issued on this site look like `sbk_` followed by 32 letters and digits. - A key belongs to an organization, not to a person. - Rotating a key creates a replacement, and the old key keeps working for a grace period. - Revoking a key stops it at once. - The API allows cross-origin requests, so a browser can call it directly; the [console](https://www.secblast.com/console) does. --- # Errors Errors are RFC 9457 problem bodies, served as `application/problem+json`, with the appropriate HTTP status. A problem body always has a stable, machine-readable `code` and the `request_id` of the request. The one exception is the `503` of `GET /v3/health` ; it carries the same health body as a `200`. ## Errors (problem bodies): | Field | Type | Required | Description | |---|---|---|---| | `code` | string | yes | | | `detail` | string | yes | | | `length` | integer | no | Search query errors: length in characters of the offending part of q. | | `parameter` | string | no | The offending parameter, for 400 responses. | | `position` | integer | no | Search query errors: character offset in q. | | `request_id` | string | yes | | | `status` | integer | yes | | | `title` | string | yes | | | `type` | string (URI) | yes | | The shape of a 400 for a misspelled parameter. The dots stand for text the API writes; match on `code`; `title` and `detail` are for people and may change. ```json { "type": "…", "title": "…", "status": 400, "detail": "…", "code": "unknown_parameter", "parameter": "fromdate", "request_id": "…" } ``` ## Codes | Code | Status | Meaning | |---|---|---| | `invalid_parameter` | 400 | A parameter has a value the API cannot accept. `parameter` names it. | | `unknown_parameter` | 400 | The request has a query parameter the route does not define. `parameter` names it. | | `unauthorized` | 401 | The API key is missing, unknown or not active. | | `invalid_token` | 401 | The bearer token is not valid: expired, revoked, badly signed, or issued for another resource. | | `forbidden` | 403 | The token's scope does not cover this route. | | `not_found` | 404 | The route or the thing asked for does not exist. | | `gone` | 410 | No route answers it. | | `method_not_allowed` | 405 | The route does not take this method. The routes that read take `GET`, `HEAD` and `OPTIONS`; the webhook routes name theirs in the reference. | | `rate_limited` | 429 | The organization's request rate is exceeded. Wait for `Retry-After`, then send the request again (see [Rate limits and quotas](https://www.secblast.com/docs/rate-limits)). | | `timeout` | 504 | The request exceeded its time limit. Narrow the query (a smaller window, a `cik`) and try again. | | `internal` | 500 | An error inside the API. Retrying may help; if it persists, send the `request_id` to support. | | `db_unavailable` | 503 | The database is temporarily unavailable. Retry after the `Retry-After` delay. | | `range_not_satisfiable` | 416 | The `Range` header asks for bytes the document does not have. | | `request_too_large` | 413 or 431 | The request body or its headers are too large. | | `warming_up` | 503 | The answer is computed in the background, and the first computation since the API started has not finished. Retry after the `Retry-After` delay. | | `invalid_query` | 400 | The search query `q` cannot be read. `position` and `length` point at the part of `q`. | | `query_too_complex` | 400 | The search query has too many terms or operators. `position` and `length` point at the part of `q`. | | `prefix_too_broad` | 400 | A prefix term (`word*`) matches too many words. `position` and `length` point at it. | | `negative_only_query` | 400 | The search query only excludes terms; it needs at least one term to match. | | `unsupported_operator` | 400 | The search query uses an operator the search does not support. `position` and `length` point at it. | | `invalid_cursor` | 400 | The search cursor is not valid for this query. | | `search_timeout` | 503 | The search query ran out of time. A narrower query or date range answers faster. | | `search_busy` | 503 | Full-text search has a full queue. Repeat the request after `Retry-After`. | | `search_unavailable` | 503 | Full-text search cannot be reached now. | | `ticker_resolution_unavailable` | 503 | Tickers cannot be resolved to companies now, so a search by ticker cannot run. | | `no_text` | 404 | The filing has no text for the item or section asked for. | | `not_covered` | 404 | The filing's form is not covered by this route's dataset. `routes` names the routes that cover it. | | `conversion_timeout` | 503 | Converting the document to text took longer than the request allows. It goes on; repeat the request after `Retry-After`. | | `document_too_large` | 422 | The document is larger than the server converts to text. `document` links the filed bytes. | | `unsupported_media_type` | 415 | A request body that is not `application/json`. | | `invalid_body` | 400 | The request body is not one JSON object, or a change names nothing to change. | | `callbacks_unavailable` | 503 | The webhook routes cannot be served by this server just now. Some of these answers carry `Retry-After`. | | `plan_required` | 403 | The organization's plan does not include the [filing stream](https://www.secblast.com/docs/stream), or [webhooks](https://www.secblast.com/docs/webhooks), or this kind of subscription. | | `limit_reached` | 409 | The plan's limit is reached; `kind` says which (endpoints, filter or firehose subscriptions, or manual retries of a delivery), with `limit` and `used`. | | `conflict` | 409 | The endpoint changed while the request was being checked. Send it again. | | `quota_exceeded` | 429 | The month's included data transfer is used up and the organization has no prepaid credit. The body says when the allowance resets (see [Rate limits and quotas](https://www.secblast.com/docs/rate-limits)). | | `blocked` | 403 | The organization of the key or token is suspended. | | `invalid_state` | 409 | The delivery cannot be retried: it is not failed, it was billed, or it is a test send or a verification. | | `replay_running` | 409 | A replay of this endpoint started a short time ago. Wait for `Retry-After`. | | `test_running` | 409 | Another test send of the organization has not answered yet. | | `endpoint_unverified` | 409 | The endpoint has not answered its challenge yet; see [Webhooks](https://www.secblast.com/docs/webhooks). | | `endpoint_disabled` | 409 | The endpoint is inactive or disabled. | A subscription whose query has `q`, `doctypes`, `primary_only=true` or `entityName` gets `400` `invalid_parameter` naming that parameter. The webhook routes are described in [Webhooks](https://www.secblast.com/docs/webhooks). ## Handling errors - **Branch on `code`**, not on the wording of `title` or `detail`. - **4xx: fix the request.** Retrying the same request gives the same answer. A 400 names the `parameter` at fault. - **503 and 504: retry.** A 503 carries `Retry-After`; wait that long, then send the same request again. Back off further if it repeats. - **`request_id`** is also in the `X-Request-Id` response header. Support can find a request by it. - **An error that is not a problem body** (a plain 429, 502 or 503 page) comes from the proxy in front of the API, not from the API itself: during a restart, or when one address sends requests faster than the proxy allows. Treat it as retryable, with a pause. ## Statuses that are not errors - `206` is the answer to a `Range` request for part of a document. - `304` is the answer when `If-None-Match` matches the document's `ETag`: your copy is current. --- # Pagination Lists come in one envelope. Certain routes page with a **keyset cursor** and return no total count. One request returns a full page: `GET /v3/filings` returns 50 rows by default, and up to 1000 with `limit`; each route's reference page gives its own default and maximum. Follow `next_cursor` to go on. ```json { "data": [ { "accession": "…" }, { "accession": "…" }, { "accession": "…" } ], "has_more": true, "next_cursor": "…" } ``` ## Following a cursor 1. Send the request with your filters and no `cursor`. 2. If `has_more` is true, send the same request again with `cursor` set to the `next_cursor` you received. 3. Stop when `has_more` is false. ```bash curl -sS -H "Authorization: Bearer $SECBLAST_API_KEY" \ 'https://api.secblast.com/v3/filings?form=10-K&limit=200' curl -sS -H "Authorization: Bearer $SECBLAST_API_KEY" \ 'https://api.secblast.com/v3/filings?form=10-K&limit=200&cursor=NEXT_CURSOR_FROM_THE_PREVIOUS_PAGE' ``` In Python, continuing the [quickstart](https://www.secblast.com/docs) session: ```python params = {"form": "10-K", "filed_from": "2026-09-01", "filed_to": "2026-09-30", "limit": 200} while True: r = session.get(f"{API}/filings", params=params, timeout=30) r.raise_for_status() page = r.json() for filing in page["data"]: handle(filing) if not page["has_more"]: break # Same filters, same sort and order; only the cursor changes. params["cursor"] = page["next_cursor"] ``` ## Rules - **A cursor is opaque.** Pass back exactly what you received. - **A cursor belongs to its query.** Use it with the same filters, the same `sort` and the same `order`; change none of them between pages. - **Trust `has_more`, not the page length.** With `sort=accepted_at` and no `cik`, a page can hold fewer rows than `limit`, even none, and still have more: keep following `next_cursor` until `has_more` is false. Narrow such a query with `accepted_from` and `accepted_to`. - **Very large filers.** For a company with tens of thousands of filings, `sort=accepted_at` with `order=asc` can return empty pages while `has_more` is true, and `sort=accession` with a `cik` and another filter can take several seconds or end in a `504` with code `timeout`. The default sort, `filing_date`, does not have these limits. - **A 503 with code `snapshot_unavailable`** on a continuation means the page cannot be produced right now; send the same request again after the `Retry-After` delay. See [Errors](https://www.secblast.com/docs/errors). ## Page size | Route | limit | Default | |---|---|---| | [`GET /v3/callbacks/deliveries`](https://www.secblast.com/docs/reference/get-callbacks-deliveries) | Page size, 1..100. | `20` | | [`GET /v3/callbacks/endpoints`](https://www.secblast.com/docs/reference/get-callbacks-endpoints) | Page size, 1..100 (GET). | `50` | | [`GET /v3/companies`](https://www.secblast.com/docs/reference/get-companies) | Page size, 1..1000. | `100` | | [`GET /v3/companies/{cik}/segments`](https://www.secblast.com/docs/reference/get-companies-cik-segments) | Period ends per page, newest first, 1..200 (default 1: the latest fiscal year). | `1` | | [`GET /v3/companies/{cik}/standard`](https://www.secblast.com/docs/reference/get-companies-cik-standard) | Period ends per page, newest first, 1..1000. | `8` | | [`GET /v3/companies/{cik}/statements`](https://www.secblast.com/docs/reference/get-companies-cik-statements) | Reports, 1..8 (1 with a category alone). | `1` | | [`GET /v3/entities`](https://www.secblast.com/docs/reference/get-entities) | Maximum results, 1..50. | `20` | | [`GET /v3/entities/{cik}/filings`](https://www.secblast.com/docs/reference/get-entities-cik-filings) | Page size, 1..1000. | `50` | | [`GET /v3/events/8k/{item}`](https://www.secblast.com/docs/reference/get-events-8k-item) | Page size, 1..500. | `50` | | [`GET /v3/events/items`](https://www.secblast.com/docs/reference/get-events-items) | Page size, 1..1000. | `50` | | [`GET /v3/filings`](https://www.secblast.com/docs/reference/get-filings) | Page size, 1..1000. | `50` | | [`GET /v3/filings/{accession}/13f/holdings`](https://www.secblast.com/docs/reference/get-filings-accession-13f-holdings) | Page size, 1..1000. | `200` | | [`GET /v3/filings/{accession}/facts`](https://www.secblast.com/docs/reference/get-filings-accession-facts) | Page size, 1..5000. | `1000` | | [`GET /v3/filings/{accession}/nport`](https://www.secblast.com/docs/reference/get-filings-accession-nport) | Holdings per page, 1..5000. | `500` | | [`GET /v3/filings/{accession}/parsed/changes`](https://www.secblast.com/docs/reference/get-filings-accession-parsed-changes) | Page size, 1..500. | `100` | | [`GET /v3/filings/{accession}/statements`](https://www.secblast.com/docs/reference/get-filings-accession-statements) | Roles per page, 1..25. | `25` | | [`GET /v3/filings/{accession}/statements/roles`](https://www.secblast.com/docs/reference/get-filings-accession-statements-roles) | Roles per page, 1..500. | `500` | | [`GET /v3/filings/{accession}/tables`](https://www.secblast.com/docs/reference/get-filings-accession-tables) | Page size, 1..1000. | `100` | | [`GET /v3/financials/facts`](https://www.secblast.com/docs/reference/get-financials-facts) | Page size, 1..2000. | `200` | | [`GET /v3/financials/frames`](https://www.secblast.com/docs/reference/get-financials-frames) | Page size, 1..50000: rows in CIK, unit and dimension order. | `500` | | [`GET /v3/financials/standard`](https://www.secblast.com/docs/reference/get-financials-standard) | Companies with a value per page, CIK order, 1..10000. | `100` | | [`GET /v3/funds/holdings`](https://www.secblast.com/docs/reference/get-funds-holdings) | Page size, 1..1000. | `500` | | [`GET /v3/funds/{series_id}/reports`](https://www.secblast.com/docs/reference/get-funds-series-id-reports) | Page size, 1..1000. | `500` | | [`GET /v3/offerings`](https://www.secblast.com/docs/reference/get-offerings) | Page size, 1..1000. | `500` | | [`GET /v3/ownership/insiders/holdings`](https://www.secblast.com/docs/reference/get-ownership-insiders-holdings) | Page size, 1..500. | `100` | | [`GET /v3/ownership/insiders/transactions`](https://www.secblast.com/docs/reference/get-ownership-insiders-transactions) | Page size, 1..500. | `100` | | [`GET /v3/ownership/institutional/holders`](https://www.secblast.com/docs/reference/get-ownership-institutional-holders) | Page size, 1..1000. | `200` | | [`GET /v3/ownership/institutional/managers/{cik}/holdings`](https://www.secblast.com/docs/reference/get-ownership-institutional-managers-cik-holdings) | Page size, 1..1000. | `200` | | [`GET /v3/ownership/institutional/managers/{cik}/periods`](https://www.secblast.com/docs/reference/get-ownership-institutional-managers-cik-periods) | Page size, 1..200. | `50` | | [`GET /v3/ownership/proposed-sales`](https://www.secblast.com/docs/reference/get-ownership-proposed-sales) | Page size, 1..200. | `50` | | [`GET /v3/reports`](https://www.secblast.com/docs/reference/get-reports) | Page size, 1..200. | `50` | | [`GET /v3/search`](https://www.secblast.com/docs/reference/get-search) | Page size, 1 to 100. | `20` | | [`GET /v3/search/subscriptions`](https://www.secblast.com/docs/reference/get-search-subscriptions) | Page size, 1..100 (GET). | `50` | | [`GET /v3/sections`](https://www.secblast.com/docs/reference/get-sections) | Page size, 1..1000. | `50` | | [`GET /v3/stream`](https://www.secblast.com/docs/reference/get-stream) | Events per answer, 1 to 1000. | `100` | ## The one offset-paged list [`GET /v3/entities/{cik}/filings`](https://www.secblast.com/docs/reference/get-entities-cik-filings) and [`GET /v3/filings/{accession}/items/{code}/text`](https://www.secblast.com/docs/reference/get-filings-accession-items-code-text) and [`GET /v3/filings/{accession}/sections/{section}/text`](https://www.secblast.com/docs/reference/get-filings-accession-sections-section-text) are the SEC's own filing lists for an entity and are paged with `offset`, not a cursor: pass the response's `next_offset` back as `offset` until it is null. Its `next_cursor` is always null. The list can shift when a new snapshot is loaded. ## Other lists The remaining lists use the same envelope and take no cursor. --- # Rate limits and quotas Plans are metered by two things: **request rate** (requests per second, with a burst allowance) and **monthly data transfer** (the bytes of the responses you receive). There are no request counts. Limits apply per organization: every key of an organization shares them. ## Plans: The request rate and monthly data transfer of each plan are listed on the schedule of fees: [/pricing](https://www.secblast.com/pricing). ## Over the request rate A request over the plan's request rate gets `429` with the problem code `rate_limited` and a `Retry-After` header in whole seconds. The body has `retry_after_ms`, the same wait to the thousandth of a second, and the plan's `limit_per_second` and `burst`. Wait that long, then send the request again. ## When the month's data transfer is used up When the month's included data transfer is used up, requests stop with `429` and the problem code `quota_exceeded`, unless the organization holds prepaid credit. `Retry-After` is the time until the allowance resets. The body has `reason` (`allowance_used_no_credit`, or `credit_exhausted` when the credit ran out), `reset_at`, `included_bytes_remaining` and `credit_bytes_remaining`. Prepaid credit is part of the Business plan: it is bought up front and is drawn only for data transfer beyond the included amount, at the plan's per-GiB rate. Credit does not expire; it is forfeited, without refund, if you close your account. Nothing is billed after the fact. Allowances reset at the start of each calendar month, New York time (ET). Responses with a `5xx` or `429` status do not count toward data transfer and do not draw credit. ## Headers | Header | Value | |---|---| | `RateLimit` | How many requests the burst allowance has left now (`r`) and the seconds until it is full again (`t`), for example `"default";r=17;t=1`. | | `RateLimit-Policy` | The plan's burst (`q`) and the seconds the plan's rate takes to refill it (`w`), for example `"default";q=20;w=1`. | | `X-Quota-Limit-Bytes` | The month's included data transfer. | | `X-Quota-Used-Bytes` | Data transfer used this month. | | `X-Quota-Remaining-Bytes` | Included data transfer left this month. | | `X-Quota-Reset` | When the allowance resets (RFC 3339). | | `X-Credit-Remaining-Bytes` | What the organization's prepaid credit still buys, in bytes. | | `Retry-After` | On a `429`: seconds to wait. | An organization with unlimited data transfer gets `X-Quota-Used-Bytes` only. Browsers can read these headers on cross-origin requests. ## The proxy in front of the API SEC Blast limits how fast one network address may send requests. A request over that limit is refused with a plain error page (status `429` or `503`), which is **not** a problem body and has no `code`. Pause, then retry. ## Using less data - **Cache documents.** [`GET /v3/filings/{accession}/documents/{document}`](https://www.secblast.com/docs/reference/get-filings-accession-documents-document) sends an `ETag` (the SHA-256 of the stored bytes); send it back as `If-None-Match` and an unchanged document costs a `304` with no body. - **Ask for part of a document** with a single-range `Range` header when you only need the start of a large file. - **Filters run on the server**, so a narrowed list transfers only its matches. - **A larger `limit`** means fewer requests for the same rows. --- # How changes are kept Filings change after they are filed: companies amend them, and SEC corrects and redelivers them. SEC Blast keeps each change and links it to what it changed. ## Amendments and their originals [`GET /v3/filings/{accession}/versions`](https://www.secblast.com/docs/reference/get-filings-accession-versions) gives a filing's whole chain: the original and every amendment, in filing order (`amendment_seq` 0 for the original, 1 to n for the amendments). Each member carries how it was linked: | Link method | What it uses | |---|---| | `explicit_header` | The amendment's SEC header names the original. | | `explicit_xml` | The filing's XML names the original (for example Schedule 13D/G). | | `original_date` | A Form 4/A's date of the original submission. | | `period_match` | The same filer, base form and period of report. | | `date_items_match` | For 8-K filings: the same event date and items. | | `file_number` | The same SEC file number. | A link's `status` is `resolved`, `ambiguous` (the candidates are listed), `unresolved`, `target_not_public` or `target_not_yet_ingested`. [`GET /v3/reports`](https://www.secblast.com/docs/reference/get-reports) lists a company's reports, one row per chain. [`GET /v3/filings`](https://www.secblast.com/docs/reference/get-filings) takes `amendments=include\|exclude\|only`. ```bash curl -sS -H "Authorization: Bearer $SECBLAST_API_KEY" \ 'https://api.secblast.com/v3/filings/0001829126-26-010431/versions' ``` ## Every event of a filing [`GET /v3/filings/{accession}/events`](https://www.secblast.com/docs/reference/get-filings-accession-events) lists what happened to a filing, oldest first. Each event has its kind, its time, its `source` (the process that recorded it, for example `realtime`, `feed`, `reconcile` or `snapshot_sync`) and its `details`. [`GET /v3/filings/{accession}`](https://www.secblast.com/docs/reference/get-filings-accession) carries the same list as `events`. | Event | When | Details | |---|---|---| | `seen` | SEC Blast first observed the filing: SEC's list of new filings, a feed file, an index or the submissions data. | | | `fetched` | Live ingest downloaded and stored the complete submission. | | | `released` | A private filing was made public. The filing's `is_private_release` is true and `released_at` gives the time. | | | `finalized` | An authoritative source confirmed the filing; its status became final at `finalized_at`. | | | `delivered` | A later delivery of the filing was merged into its documents. | | | `corrected` | Its header or documents changed, on reconciliation or by an SEC correction. The filing's `is_correction` is true and `date_of_change` gives the latest date of change in SEC's header. | | | `accepted_changed` | The stored acceptance time changed, for example when SEC's submissions data supplies it. | `old`, `new`, `old_source`, `new_source` | | `linked` | An amendment was linked to its original, or its link changed. | | | `reconciled` | A reconciliation check of the filing against SEC's sources completed. | | | `parsed` | A dataset extractor produced rows for the filing for the first time. | `dataset`, `extractor`, `version`, `status` | | `parse_changed` | A re-parse or a changed input changed, added or removed the filing's parsed rows. | `dataset`, `extractor`, versions, counts | `previous_accession` is the earlier filing a filing names as the one it amends or replaces, where its header or XML names one; [`GET /v3/filings/{accession}/versions`](https://www.secblast.com/docs/reference/get-filings-accession-versions) shows the link made from it. ## Redeliveries When SEC delivers a filing more than once, the deliveries are merged: [`GET /v3/filings/{accession}/documents`](https://www.secblast.com/docs/reference/get-filings-accession-documents) serves, for each document, the newest delivery's copy. A changed document gets a new `ETag`, and the filing gets a `delivered` event. ## Provisional and final A filing's `status` is `provisional` from live ingest until SEC's nightly feed file confirms it, then `final`. `accepted_at_source` says where `accepted_at` came from, and `accepted_at_snapshot` gives SEC's own value when it differs. --- # Filing stream [`GET /v3/stream`](https://www.secblast.com/docs/reference/get-stream) returns the filings SEC Blast receives, in the order it emits them: new filings, changes and corrections, and the close of each nightly feed day. It is a long-poll: you ask with the cursor of your last answer, and when nothing new has arrived the request waits up to `wait` seconds for it. The reference of the route lists every parameter, with its default. ```bash curl -sS -H "Authorization: Bearer $SECBLAST_API_KEY" \ 'https://api.secblast.com/v3/stream' ``` The stream takes v3 API keys (they start with `sbk_`), sent in the same ways as to the API; see [Authentication](https://www.secblast.com/docs/authentication). It does not take OAuth access tokens. A key whose plan does not include the stream gets `403` `plan_required`. ## Reading the stream - The first request has no `after`: it starts at the head, so you receive what arrives from then on. - Every answer has `next_cursor`, an empty answer too. Send it as `after` in the next request. With filters, it moves past the events they left out. - `has_more` `true` means more events are waiting: ask again at once instead of waiting. - `stream_seq` numbers the events with no gaps. A jump between two events you received means you missed one: ask again from your last cursor. A cursor reaches back 30 days. An older one gets `410` `cursor_expired` with `oldest_cursor`, the oldest position still kept. ## Events `types` chooses the events; the reference of the route gives the default. | Event | When | |---|---| | `filing.new` | A filing is received for the first time. | | `filing.updated` | A filing sent before changes: its documents arrive, the nightly feed makes it final, a redelivery is merged or an amendment is linked. `change` says which. | | `filing.corrected` | SEC corrects a filing already sent. `changes` lists the header fields and documents that changed. | | `feed.day_closed` | A nightly feed day is complete, with its counts. | A filing first seen in the nightly feed, not live, has `late` `true`. `include_late=false` leaves those out. ## Filters The stream takes the filters of [`GET /v3/search`](https://www.secblast.com/docs/reference/get-search), with the same meaning: `forms`, `form_types`, `form_families`, `ciks`, `tickers`, `sics` and `states`, and `items` for 8-K item codes. `detail=summary` leaves out each filing's document list. ## Errors and limits Each organization may hold a limited number of stream requests at once, a waiting one included, shared by all its keys; one more gets `429` `rate_limited` with the reason `stream_connections`. A `503` carries `Retry-After`: wait that long, then ask again with the same cursor. ## Stream status [`GET /v3/stream/status`](https://www.secblast.com/docs/reference/get-stream-status) needs no key. It gives the head cursor, the state of live ingest, how far the stream is behind it, and latency percentiles over the last hour and day. ```bash curl -sS 'https://api.secblast.com/v3/stream/status' ``` --- # Webhooks With webhooks (API: callbacks), SEC Blast sends each new filing that matches a subscription to your HTTPS endpoint as a signed `POST`. An endpoint is a URL that receives events; a subscription is a set of filing filters that sends what matches to one endpoint. The routes on this page manage both and take a v3 API key, sent as on every other route ([Authentication](https://www.secblast.com/docs/authentication)). A filing in an event has the shape of a filing in the [filing stream](https://www.secblast.com/docs/stream). Deliveries come from `67.227.64.202`: IPv4 only, TCP port 443, `https` only. ## Endpoints [`POST /v3/callbacks/endpoints`](https://www.secblast.com/docs/reference/post-callbacks-endpoints) with `url`, `event_types` and an optional `description` creates an endpoint. The `url` is `https` on port 443, with a public DNS name that resolves to a public address; IP addresses, user names and passwords, `localhost`, and names under `.local` or `.internal` are refused. The answer, `201`, carries the endpoint's signing `secret`, `whsec_` followed by base64; it is shown only in that answer. ```bash curl -sS -X POST -H "Authorization: Bearer $SECBLAST_API_KEY" \ -H "Content-Type: application/json" -d @body.json \ 'https://api.secblast.com/v3/callbacks/endpoints' ``` ```json { "url": "https://hooks.example.com/secblast", "event_types": [ "filing.new" ], "description": "8-K alerts" } ``` [`GET /v3/callbacks/endpoints`](https://www.secblast.com/docs/reference/get-callbacks-endpoints) lists the endpoints, each with its health and its deliveries of the last 24 hours. [`PATCH /v3/callbacks/endpoints/{id}`](https://www.secblast.com/docs/reference/patch-callbacks-endpoints-id) changes `url`, `description`, `event_types` or `active`; `GET` reads the endpoint and `DELETE` deletes it, which also deactivates the subscriptions that deliver to it. [`POST /v3/callbacks/endpoints/{id}/rotate-secret`](https://www.secblast.com/docs/reference/post-callbacks-endpoints-id-rotate-secret) issues a new secret, shown once; the previous secret keeps signing beside it for `expire_previous_in_s` seconds. `event_types` lists the events the endpoint receives: | Event | When | |---|---| | `filing.new` | A new filing matches a subscription. `data.filing` is the filing. | | `filing.updated` | A filing already sent changes: documents added or fetched again, made final by the nightly feed, merged with a redelivery, or linked to the filing it amends. `data.change` says which. Sent to subscriptions with `include_corrections`. | | `filing.corrected` | SEC corrects a filing already sent. `data.changes` lists the header fields and documents that changed. Sent to subscriptions with `include_corrections`. | | `filing.digest` | The `filing.new` events of a subscription with `min_interval_s`, gathered over its interval: `data.events`, `data.count` and `data.truncated`. | | `endpoint.verification` | The endpoint's challenge (see below). Sent to every endpoint, whatever its `event_types`. | ## Subscriptions [`POST /v3/search/subscriptions`](https://www.secblast.com/docs/reference/post-search-subscriptions) with `name`, `query` and `endpoint_id` creates a subscription. `query` takes the filters of [`GET /v3/search`](https://www.secblast.com/docs/reference/get-search) as JSON members: `forms`, `form_types`, `form_families`, `ciks`, `tickers`, `sics`, `states` and `inc_states`, plus `items` for 8-K item codes. Tickers are resolved to CIKs when the subscription is saved. A query with filters makes a filter subscription; a query with none makes a firehose subscription, which receives every new filing. Both deliver `filing.new`, and the endpoint must list it in `event_types`. ```json { "name": "8-K item 5.02", "query": { "forms": "8-K", "items": "5.02" }, "endpoint_id": "cbe_…", "include_corrections": false } ``` - `include_corrections` `true` also sends `filing.updated` and `filing.corrected` for the filings the subscription has sent. - `min_interval_s` sends at most one request per interval: the events of the interval arrive together as one `filing.digest`. - A query with a filing-date window (`filed_from`, `filed_to`) or with `status` gets `400` naming it: a subscription receives new filings. - A query with `q`, `doctypes`, `primary_only=true` or `entityName` gets `400` `invalid_parameter` naming that parameter: a subscription matches filings by their filing-level fields. - [`POST /v3/search/subscriptions/{id}/test`](https://www.secblast.com/docs/reference/post-search-subscriptions-id-test) answers with the events the subscription would have sent for recent filings, each with `test` `true`. Nothing is delivered. - [`PATCH /v3/search/subscriptions/{id}`](https://www.secblast.com/docs/reference/patch-search-subscriptions-id) changes a subscription; `GET` reads it and `DELETE` deletes it. The answers of [`GET /v3/callbacks/endpoints`](https://www.secblast.com/docs/reference/get-callbacks-endpoints) and [`GET /v3/search/subscriptions`](https://www.secblast.com/docs/reference/get-search-subscriptions) carry `limits`: for endpoints, and for filter and firehose subscriptions, the plan's `limit` and the active ones (`used`). A plan without webhooks gets `403` `plan_required`; an endpoint or subscription beyond the plan's limit gets `409` `limit_reached` with `kind`. The limits of each plan are on the [fees page](https://www.secblast.com/pricing). ## Endpoint verification A new endpoint is `unverified`, and so is an endpoint whose `url` changes or that is activated again. SEC Blast sends it an `endpoint.verification` event, signed like every event, whose `data.challenge` is 32 hexadecimal characters: ```json { "type": "endpoint.verification", "data": { "challenge": "6f1c0d2e9a8b47c3b5e2f1a0d9c8b7a6" } } ``` The endpoint is verified when it answers `2xx` within 10 seconds and the response body, trimmed of surrounding white space, equals the challenge, or the body is JSON whose `challenge` field equals it. A leading UTF-8 byte order mark is ignored. A body that contains the challenge among other text does not verify. Either of these bodies verifies: ```text 6f1c0d2e9a8b47c3b5e2f1a0d9c8b7a6 {"challenge": "6f1c0d2e9a8b47c3b5e2f1a0d9c8b7a6"} ``` Until the endpoint is verified, its deliveries are held. They are sent once it is verified, and dropped after 72 hours. ## Verify and test [`POST /v3/callbacks/endpoints/{id}/verify`](https://www.secblast.com/docs/reference/post-callbacks-endpoints-id-verify) sends a new challenge and answers `202` with the endpoint. A challenge sent earlier and not yet delivered is dropped, and an answer to it no longer verifies. An inactive endpoint gets `409` `endpoint_disabled`; `PATCH` with `active` `true` verifies it again. [`POST /v3/callbacks/endpoints/{id}/test`](https://www.secblast.com/docs/reference/post-callbacks-endpoints-id-test) with `type` sends one sample event of a type the endpoint takes, signed like any event, with `test` `true` and sample data. It answers `200` with the outcome of its one attempt (`delivered`, `http_status`, `error_class`, `duration_ms`), or `202` when no attempt was made within 12 seconds; the event is then still sent, and the delivery log has the outcome. A test send is not retried and not billed. While another test of the organization runs, a test gets `409` `test_running`; an unverified or disabled endpoint gets `409` `endpoint_unverified` or `endpoint_disabled`. The two routes share a limit of 6 requests a minute per organization, with a burst of 3. Beyond it they answer `429` `rate_limited` with the reason `verify_test` and `Retry-After`. ## Endpoint health Each endpoint has `health.state`, and `last_24h`: its deliveries of the last 24 hours by state. | State | Meaning | |---|---| | `unverified` | Waiting for the answer to its challenge. Deliveries are held. | | `active` | Verified. Deliveries are sent. | | `failing` | A delivery failed every attempt within one hour, or 10 attempts in a row failed. Deliveries are still sent; one success makes the endpoint `active` again. | | `disabled` | Every attempt failed for 72 hours, with at least 20 attempts, or the endpoint answered `410`. New deliveries are held for 72 hours, then dropped. `PATCH` with `active` `true` makes the endpoint `unverified` and sends a challenge; once it is verified, the held deliveries are sent in order. | An endpoint set to `active` `false` holds nothing: its deliveries are dropped. ## Delivery log, retry and replay [`GET /v3/callbacks/deliveries`](https://www.secblast.com/docs/reference/get-callbacks-deliveries) lists the organization's deliveries, newest first, with `attempt_count`, `last_status`, `last_error` and, while an attempt is due, `next_attempt_at`. It filters by `endpoint_id`, `subscription_id`, `state`, `type`, `accession`, and `from` and `to` on `created_at`. [`GET /v3/callbacks/deliveries/{id}`](https://www.secblast.com/docs/reference/get-callbacks-deliveries-id) adds the payload and every attempt. Deliveries are kept 30 days after their final state. The list pages with `cursor` and `next_cursor` ([Pagination](https://www.secblast.com/docs/pagination)); a cursor is opaque and is sent back as it was received. | State | Meaning | |---|---| | `pending` | Waiting for its next attempt. | | `held` | Waiting for a condition, named in `held_reason`: an unverified or disabled endpoint, the plan, the monthly transfer, or a digest interval. | | `delivering` | An attempt is in flight. | | `delivered` | The endpoint answered `2xx`. | | `failed` | Every attempt failed, the endpoint answered `410`, or a hold ran out; `last_error` says which. | | `dropped` | The endpoint was inactive, or a hold on an unverified or disabled endpoint ran out. | [`POST /v3/callbacks/deliveries/{id}/retry`](https://www.secblast.com/docs/reference/post-callbacks-deliveries-id-retry) queues one more attempt of a failed delivery now and answers `202`. The attempt count goes on from where it was. A delivery can be retried this way twice; after that it gets `409` `limit_reached`. Only a failed delivery that was never billed can be retried; any other gets `409` `invalid_state`. [`POST /v3/callbacks/endpoints/{id}/replay`](https://www.secblast.com/docs/reference/post-callbacks-endpoints-id-replay) with `from`, and optionally `to`, `states` and `types`, queues again the failed and dropped deliveries of one endpoint created in that window, oldest first. The window is at most 30 days. It answers `202` with `{replayed, truncated, last_created_at}`. One call queues at most 10,000 deliveries; when `truncated` is `true`, the next call keeps `to`, `states` and `types` and sets `from` to `last_created_at`. Billed deliveries, test sends and verifications are never queued again. A replay of the same endpoint within 60 seconds of the last gets `409` `replay_running` with `Retry-After`. ```json { "replayed": 214, "truncated": false, "last_created_at": null } ``` ## Retries An attempt fails when the endpoint does not answer `2xx` within 10 seconds; redirects are not followed. A delivery is attempted up to 12 times in total, over about 71 hours, and is then `failed`. A `410` fails the delivery and disables the endpoint at once. Delivery is at least once: every attempt of a delivery carries the same `webhook-id`, which is also the body's `id`. ## Signatures Every request is a `POST` with `Content-Type: application/json` and the headers of Standard Webhooks: | Header | Value | |---|---| | `webhook-id` | The delivery's id, the same on every attempt. | | `webhook-timestamp` | Unix seconds of this attempt. | | `webhook-signature` | One or more space-separated `v1,` entries. | | `X-SecBlast-Event` | The event type, as the body's `type`. | The signature is `base64(HMAC-SHA256(key, ".."))`, where the key is the bytes that the base64 after `whsec_` decodes to. It is computed over the raw request body bytes: a body parsed and serialized again is a different byte sequence and does not verify. While a rotated secret's previous value still signs, the header has two entries; the request is valid when one of them matches. `webhook-timestamp` is the time of each attempt, so a receiver can refuse one more than 5 minutes from its own clock, as the examples below do. The body of every event except `endpoint.verification` has these fields: | Field | Meaning | |---|---| | `id` | The `webhook-id` of the delivery. | | `type` | The event type. | | `schema_version` | `1`. Within a version, changes only add fields. | | `emitted_at` | When the event was made. | | `test` | `true` for a test send. | | `subscription` | The subscription that produced the event, `{id, name}`; `null` for a test send. | | `stream_seq` | For `filing.*` events, the event's position in the filing stream. | | `data` | The event's data, by type (see the table of events). | Python, with Flask: ```python import base64, hashlib, hmac, json, os, time from flask import Flask, request app = Flask(__name__) SECRET = os.environ["SECBLAST_WEBHOOK_SECRET"] # the whsec_ value from the endpoint's creation KEY = base64.b64decode(SECRET.removeprefix("whsec_")) def verified(body: bytes, headers) -> bool: msg_id, ts = headers.get("webhook-id", ""), headers.get("webhook-timestamp", "") if not ts.isdigit() or abs(time.time() - int(ts)) > 300: return False mac = hmac.new(KEY, f"{msg_id}.{ts}.".encode() + body, hashlib.sha256).digest() expected = base64.b64encode(mac).decode() entries = headers.get("webhook-signature", "").split() return any(e.startswith("v1,") and hmac.compare_digest(e[3:], expected) for e in entries) @app.post("/secblast") def secblast_webhook(): body = request.get_data() # the raw body bytes, as signed if not verified(body, request.headers): return "", 400 event = json.loads(body) if event["type"] == "endpoint.verification": return event["data"]["challenge"] if event["type"] == "filing.new": filing = event["data"]["filing"] print(event["id"], filing["accession"], filing["form_type"]) return "", 204 ``` TypeScript, with Express and `node:crypto`: ```typescript import express from "express"; import { createHmac, timingSafeEqual } from "node:crypto"; type Event = { id: string; type: string; data: { challenge?: string; filing?: { accession: string; form_type: string } } }; const secret = process.env.SECBLAST_WEBHOOK_SECRET!; // the whsec_ value from the endpoint's creation const key = Buffer.from(secret.replace(/^whsec_/, ""), "base64"); function verified(body: Buffer, h: express.Request["headers"]): boolean { const id = String(h["webhook-id"] ?? ""), ts = String(h["webhook-timestamp"] ?? ""); if (!/^\d+$/.test(ts) || Math.abs(Date.now() / 1000 - Number(ts)) > 300) return false; const expected = createHmac("sha256", key).update(`${id}.${ts}.`).update(body).digest(); return String(h["webhook-signature"] ?? "").split(" ").some((e) => { const sig = e.startsWith("v1,") ? Buffer.from(e.slice(3), "base64") : Buffer.alloc(0); return sig.length === expected.length && timingSafeEqual(sig, expected); }); } const app = express(); // express.raw keeps the body as the bytes that were signed. app.post("/secblast", express.raw({ type: "application/json" }), (req, res) => { if (!verified(req.body, req.headers)) return res.sendStatus(400); const event = JSON.parse(req.body.toString("utf8")) as Event; if (event.type === "endpoint.verification") return res.type("text/plain").send(event.data.challenge); if (event.type === "filing.new") console.log(event.id, event.data.filing?.accession, event.data.filing?.form_type); return res.sendStatus(204); }); ``` --- # MCP server for SEC filings SEC Blast runs a remote MCP server at `https://api.secblast.com/mcp`. Claude, ChatGPT, Cursor and any other MCP client connect to it over HTTP and use the API through its tools. ## Adding the server The MCP server is hosted at `https://api.secblast.com/mcp`. To add to Claude Code: ```bash claude mcp add --transport http secblast https://api.secblast.com/mcp ``` For other clients, use the same address as a remote MCP server (streamable HTTP). ## ## Connecting The client connects with OAuth 2.1. The first time, the client opens SEC Blast in the browser: 1. You sign in to SEC Blast, or create an account. 2. The consent page shows the app's name, the address it returns to, and the organization it connects to. With several organizations, you choose one. 3. **Allow** returns you to the app. From then on the app calls the API for that organization; **Deny** returns you with nothing granted. Owners, admins and developers of an organization can connect an app to it, the same roles that manage SEC Blast API keys. ## What a connected AI can do A connected AI has read access to the API. Every call it makes counts against the organization's plan, like a request made with a key. The app holds an access token valid for 10 minutes and a refresh token valid for 60 days. Each refresh replaces the refresh token and double usage of a refresh token invalidates the session. ## Connected apps [Connected apps](https://www.secblast.com/dashboard/apps) lists the apps connected to the organization: name, the address each returns to, who allowed it, when, and when it was last used. **Revoke** ends a connection: its refresh token stops at once, its access token within a minute. A revoked app can be allowed again after ten minutes. ## Tools The server offers these tools. Each one calls the API with the app's token. | Tool | What it does | |---|---| | `sec_find_company` | Find a company or fund by ticker, name or CIK; returns its CIK, current and former names, tickers, SIC industry, addresses and SPAC status. | | `sec_latest_filing` | The latest filing of one form for a ticker or CIK in one call (for example the latest S-4 of NTWO), with the start of the document. | | `sec_list_filings` | List filings by company, form, 8-K item, status and date, newest first. | | `sec_get_filing` | One filing by accession number: dates, filers, status, amendments, documents and exhibits, sections or 8-K items. | | `sec_search_filings` | Full-text search of every filing since 1993, with ticker, form, document type, SIC, state and date filters. | | `sec_read_filing` | Read any document or exhibit, a named section (10-K, 10-Q and 20-F items; the summary, background of the merger, pro forma and target MD&A of S-4, F-4 and merger proxies; executive compensation in DEF 14A), or an 8-K item, page by page. | | `sec_list_sections` | One section across many filings: 10-K, 10-Q and 20-F sections, and merger and proxy sections such as Background of the Merger or Pay Versus Performance, by company or date. | | `sec_list_8k_events` | 8-K events across companies by item, with extracted fields: 1.01 merger and other material agreements and 2.01 completed acquisitions (deal price per share, cash per share, exchange ratio, closing date), 2.02 earnings and 4.01 auditor changes, with the accuracy of each field. | | `sec_list_spacs` | Former SPACs by the date their business combination closed, or current blank-check SPACs, with the merger filing and the SPAC's original name. | | `sec_get_financials` | XBRL financial statements, any concept over time, one concept across companies, standard fields and segments. | | `sec_get_holdings` | Insider trades (Forms 3, 4 and 5), 13F holdings by security or manager, Form 144, N-PORT fund holdings and Form D. | | `sec_get_tables` | The tables of a 10-K, 10-Q or 20-F primary document, with parsed numbers and scale. | | `sec_get_filing_data` | The parsed content of one filing: Form D, N-PORT, 13F, Forms 3, 4 and 5, or Form 144. | | `sec_watch_filings` | Create, list or delete a subscription to new filings (by company, form type or 8-K item) that sends them as signed webhooks to one of your endpoints. | | `sec_send_feedback` | Send feedback to SEC Blast about the MCP server or the data: a bug, wrong or missing data, a missing tool or unclear docs. | ## For client developers - Authorization code with PKCE, `S256` only. No implicit or password grant. - Clients register dynamically (RFC 7591) or are named by a client ID metadata document: a `client_id` that is an `https` URL. Redirect URIs are `https`, or `http` on `127.0.0.1`, `[::1]` or `localhost` with any port. - The `resource` parameter (RFC 8707) is `https://api.secblast.com/mcp` for the MCP server or `https://api.secblast.com/v3` for the API, and the access token is valid for that one only. Without it, the token is for the API. - Access tokens are ES256 JWTs. The one scope is `api`. - `POST /oauth/revoke` (RFC 7009) with either token ends the connection. --- # API reference Generated from the API's OpenAPI 3.1.0 description, version 0.1.0. The base address is `https://api.secblast.com`; the routes are `GET` except those marked otherwise. API over the v3 core filing layer. Filings, entities, search, parsed data and XBRL are read with GET. Webhook endpoints (/v3/callbacks/endpoints) and search subscriptions (/v3/search/subscriptions) are also created with POST, changed with PATCH and deleted with DELETE; the delivery routes under /v3/callbacks take POST for retry, replay, verify and test. Feedback to SEC Blast is sent with POST /v3/feedback. Lists use the envelope {data, has_more, next_cursor}. Errors are RFC 9457 application/problem+json with a stable `code`. Unknown query parameters are rejected with 400. Every response carries X-Request-Id. HEAD and OPTIONS are answered for every path. Responses that can carry values from SEC's submissions snapshot (acceptance time, report period, entity records, SEC's filing lists, tickers) have a `snapshot` block {available, date}; when available is false the response was built from the v3 database alone. Filings that arrived live carry `status` `provisional` until SEC's nightly feed file makes them `final`. The routes under `/v3/callbacks/` and `/v3/search/subscriptions` manage [Webhooks (API: callbacks)](https://www.secblast.com/docs/webhooks). Each of the 82 routes has its own page. The objects they take and return are on [Schemas](https://www.secblast.com/docs/reference/schemas). ## Filings | Route | Returns | |---|---| | [`GET /v3/filings`](https://www.secblast.com/docs/reference/get-filings) | Search filings. | | [`GET /v3/filings/{accession}`](https://www.secblast.com/docs/reference/get-filings-accession) | One filing with entities, documents, events and its version chain. | | [`GET /v3/filings/{accession}/documents`](https://www.secblast.com/docs/reference/get-filings-accession-documents) | Documents of a filing, in sequence order. | | [`GET /v3/filings/{accession}/documents/{document}`](https://www.secblast.com/docs/reference/get-filings-accession-documents-document) | Stored bytes of one document. | | [`GET /v3/filings/{accession}/events`](https://www.secblast.com/docs/reference/get-filings-accession-events) | Lifecycle events of a filing, oldest first. | | [`GET /v3/filings/{accession}/header`](https://www.secblast.com/docs/reference/get-filings-accession-header) | The stored SGML header (_header.sgml) as text/plain. | | [`GET /v3/filings/{accession}/versions`](https://www.secblast.com/docs/reference/get-filings-accession-versions) | Version chain of the filing's report: the original and every amendment, with how each amendment was linked. | | [`GET /v3/reports`](https://www.secblast.com/docs/reference/get-reports) | Reports of one entity: one row per version chain (an original plus its amendments), ordered by the original filing's date, newest first (a chain whose original is not ingested is dated by its first ingested amendment). | ## Entities | Route | Returns | |---|---| | [`GET /v3/companies`](https://www.secblast.com/docs/reference/get-companies) | Companies that are or were SPACs (blank checks, SIC 6770), from the SIC and names in their filing headers over time. | | [`GET /v3/entities`](https://www.secblast.com/docs/reference/get-entities) | Entity search. | | [`GET /v3/entities/{cik}`](https://www.secblast.com/docs/reference/get-entities-cik) | Most recent as-filed attributes of a CIK, SEC's current entity record from the snapshot (current), roles seen and filing counts. | | [`GET /v3/entities/{cik}/filings`](https://www.secblast.com/docs/reference/get-entities-cik-filings) | SEC's own filing list for the entity (from the submissions snapshot), newest first; each row says whether v3 has the filing. | | [`GET /v3/resolve`](https://www.secblast.com/docs/reference/get-resolve) | Which CIK(s) hold a ticker, from SEC's ticker file; with as_of, from the copy that was current on that date. | ## Full-text search | Route | Returns | |---|---| | [`GET /v3/filings/{accession}/documents/{document}/text`](https://www.secblast.com/docs/reference/get-filings-accession-documents-document-text) | The extracted text of one document as the full-text index holds it (text/plain; charset=utf-8): the text that snippet start/end offsets count characters of. | | [`GET /v3/search`](https://www.secblast.com/docs/reference/get-search) | Full-text search over every document v3 holds (spec §6.1). | | [`GET /v3/search/parse`](https://www.secblast.com/docs/reference/get-search-parse) | How a query is read, without running it: the normalised query, its tree, the EDGAR reading beside the default one, prefix expansions, the structured filters after alias mapping and ticker resolution, and the index years it would touch. | | [`GET /v3/search/status`](https://www.secblast.com/docs/reference/get-search-status) | State of the full-text index, without a key: per year the document and filing counts, index version and extractor; the live indexer's lag; indexed_through; the years being rebuilt. | ## Sections of 10-K, 10-Q and 20-F | Route | Returns | |---|---| | [`GET /v3/filings/{accession}/sections`](https://www.secblast.com/docs/reference/get-filings-accession-sections) | The sections of a 10-K, 10-Q or 20-F: one row per item in force with its key (10k.1a, 10q.p1i2, 20f.3d), status (ok, incorporated_by_reference, combined_with, omitted, reserved, not_found), why an absent item is absent, spans and rule confidence; the amendment scope. | | [`GET /v3/filings/{accession}/sections/{section}/text`](https://www.secblast.com/docs/reference/get-filings-accession-sections-section-text) | One section's canonical text, under the same serving rule, paging, ETag, cache and time limit as an 8-K item's text. | | [`GET /v3/sections`](https://www.secblast.com/docs/reference/get-sections) | One section across filings, newest first (by filing date, then accession). | ## Parsed data and tables | Route | Returns | |---|---| | [`GET /v3/filings/{accession}/parsed`](https://www.secblast.com/docs/reference/get-filings-accession-parsed) | Which parsed datasets apply to the filing (13f, 8k_items, sections) and the state of each: status (ok, ok_with_warnings, partial, unparseable, not_applicable; pending, failed or not_parsed while there is no result), the extractor version that last verified the filing and the deployed one, a re-parse in progress, warnings (at most 100), the documents read, the dataset's derive steps for the filing, and a link to the dataset's route for the filing (null while this server does not answer it). | | [`GET /v3/filings/{accession}/parsed/changes`](https://www.secblast.com/docs/reference/get-filings-accession-parsed-changes) | Every earlier version of the filing's parsed data that is kept, newest first: each row of a dataset table a re-parse changed or removed (kind superseded: table, row key, from and to version, reason changed / removed / withdrawn, the old row), each group of rows rebuilt or replaced as a whole (kind replaced: the 13F ledger and manager-period rows, the filing's warning set and result row; the old rows) and each 13F unit decision (kind unit_decision). | | [`GET /v3/filings/{accession}/tables`](https://www.secblast.com/docs/reference/get-filings-accession-tables) | The tables of a 10-K, 10-Q or 20-F primary document. | ## 8-K items | Route | Returns | |---|---| | [`GET /v3/events/8k/{item}`](https://www.secblast.com/docs/reference/get-events-8k-item) | One 8-K item's structured events across filings, newest first (by filing date, then accession): one row per filing with its events of that item, each a list of fields {value, value_as_found, span, rule_id, rule confidence} read from the item's text; exhibit numbers joined to the filing's documents by type. | | [`GET /v3/events/items`](https://www.secblast.com/docs/reference/get-events-items) | One 8-K item across filings, newest first (by filing date, then accession): the parsed union of header and body items, with which side named it. | | [`GET /v3/filings/{accession}/items`](https://www.secblast.com/docs/reference/get-filings-accession-items) | An 8-K's item sets (the header's, the body's, their union), how they differ, one row per item (source, heading status, spans in the primary document, rule confidence) and the Item 9.01 exhibit rows. | | [`GET /v3/filings/{accession}/items/{code}/text`](https://www.secblast.com/docs/reference/get-filings-accession-items-code-text) | One 8-K item's canonical text (not the filed HTML), cut from the stored primary document only when the document model and the exact bytes are at hand; otherwise text_status says why. | ## Financial data (XBRL) | Route | Returns | |---|---| | [`GET /v3/companies/{cik}/periods`](https://www.secblast.com/docs/reference/get-companies-cik-periods) | One concept by fiscal period. | | [`GET /v3/companies/{cik}/segments`](https://www.secblast.com/docs/reference/get-companies-cik-segments) | The company's breakdowns by period from its own dimensional facts: business segment, product or service, geography and major customer; revenue, operating income, assets, long-lived assets, D&A, capital expenditure and (from 2024) segment expenses. | | [`GET /v3/companies/{cik}/standard`](https://www.secblast.com/docs/reference/get-companies-cik-standard) | The company's standard fields by period (fields x periods), from each filing's own statements through a pinned concept map: each value with its status (ok, not_reported, ambiguous, not_applicable; a blank is never a zero), the facts behind it, the rule (candidate:\ or rollup), the map version and fingerprint, and flags (failed identities, scale outliers). | | [`GET /v3/companies/{cik}/statements`](https://www.secblast.com/docs/reference/get-companies-cik-statements) | A company's statement as presented in its latest periodic report (10-K, 10-Q, 10-KT, 10-QT, 20-F, 40-F and amendments) SEC had accepted by as_of that has one: of one kind (with its parentheticals), of one menu category (notes, details, ...) or one role URI; limit \> 1 gives the previous reports' too, newest first. | | [`GET /v3/filings/{accession}/facts`](https://www.secblast.com/docs/reference/get-filings-accession-facts) | Every XBRL fact of a filing as filed: every instance read (the SEC-extracted one when there is one, else the filer's), facts numbered across them in reading order, each with its concept, context (entity, period, dimensions), unit, the exact value beside the filed text, decimals as filed (INF kept), nil, its duplicate class, and footnotes. | | [`GET /v3/filings/{accession}/statements`](https://www.secblast.com/docs/reference/get-filings-accession-statements) | The filing's statements as presented: every role of the filing (with its R page), and for the roles asked -- by default the statement and cover roles; kind, category, role_no or role_uri name others, notes, policies, tables and details included -- the presentation tree in the filer's order with preferred labels, negating / total / period start and end flags, its calculation arcs, and the columns and cells assembled from the filing's facts (each cell the filed fact: exact value and filed text; a blank is null, never zero; a text block's cell says where its text is). | | [`GET /v3/filings/{accession}/statements/roles`](https://www.secblast.com/docs/reference/get-filings-accession-statements-roles) | The filing's roles without their statements: every role (statements, cover, notes, policies, tables, details) in position order, with its menu category, statement kind, R page, tree size and matches_sec_render, and a link to its statement. | | [`GET /v3/financials/facts`](https://www.secblast.com/docs/reference/get-financials-facts) | One company's facts of one concept across its filings, newest period first (then accession, fact_seq): every fact as filed, with its filing's form, filing date and acceptance time. | | [`GET /v3/financials/frames`](https://www.secblast.com/docs/reference/get-financials-frames) | One concept and period across companies: each company's latest incarnation known at as_of (one per CIK, unit and dimension set), from one index range per filing year, the period being the filed dates. | | [`GET /v3/financials/series`](https://www.secblast.com/docs/reference/get-financials-series) | One company's values of one concept, point in time. | | [`GET /v3/financials/standard`](https://www.secblast.com/docs/reference/get-financials-standard) | One standard field across companies for a calendar frame (CY2024Q4, CY2024; CY2024Q4I for balance-sheet fields): each company's reported value (view latest as of a time, or first_reported) with its facts, rule, map pin and flags; in a quarter frame, a company without a reported quarter gets its quarter derived from its year, nine months, half or first quarter on one basis (monetary flows); ttm=true gives the trailing twelve months ending in the quarter. | ## Insider ownership (Forms 3, 4, 5) | Route | Returns | |---|---| | [`GET /v3/filings/{accession}/ownership`](https://www.secblast.com/docs/reference/get-filings-accession-ownership) | A Form 3, 4 or 5 (or its /A) as filed: the document's filing-level fields, the issuer, every reporting owner with the whole address and relationship, the SEC header's entities (addresses and phone numbers), the four tables (non-derivative and derivative transactions and holdings) with each row's footnote references and footnote text, the footnotes, the signatures, and the filing's amendment chain (provisional). | | [`GET /v3/ownership/insiders/holdings`](https://www.secblast.com/docs/reference/get-ownership-insiders-holdings) | Forms 3/4/5 holding rows (Table I and Table II) across filings, newest filing first, then table and row, with the same filing, issuer, owner and footnote members and the same views as the transactions route. | | [`GET /v3/ownership/insiders/transactions`](https://www.secblast.com/docs/reference/get-ownership-insiders-transactions) | Forms 3/4/5 transaction rows (Table I and Table II) across filings, newest filing first, then table and row. | ## Institutional holdings (Form 13F) | Route | Returns | |---|---| | [`GET /v3/filings/{accession}/13f`](https://www.secblast.com/docs/reference/get-filings-accession-13f) | A 13F filing's cover page (contact fields: city, state or country, ZIP code; no street line, no phone), summary page, both lists of other managers, the unit decision of its values (value_unit) and its step in the manager-period's amendment ledger. | | [`GET /v3/filings/{accession}/13f/holdings`](https://www.secblast.com/docs/reference/get-filings-accession-13f-holdings) | The information-table rows of a 13F filing exactly as filed, in document order, with value_usd = value_reported x the unit decision's multiplier (null when the unit is ambiguous or not decided). | | [`GET /v3/ownership/institutional/holders`](https://www.secblast.com/docs/reference/get-ownership-institutional-holders) | The effective 13F rows of one CUSIP across managers for one period (as known at as_of), ordered by manager CIK, ledger step and row; options are their own rows. | | [`GET /v3/ownership/institutional/managers/{cik}/holdings`](https://www.secblast.com/docs/reference/get-ownership-institutional-managers-cik-holdings) | A 13F manager's holdings for one period: view=effective applies the amendment ledger (the last restatement or original, plus later additions) as known at as_of; view=as_filed lists the rows of every applied step. | | [`GET /v3/ownership/institutional/managers/{cik}/periods`](https://www.secblast.com/docs/reference/get-ownership-institutional-managers-cik-periods) | One row per period a 13F manager filed for, newest first: ledger steps, base and latest filing, effective rows and reported 13F long value (not assets under management), flags. | ## Proposed sales (Form 144) | Route | Returns | |---|---| | [`GET /v3/filings/{accession}/144`](https://www.secblast.com/docs/reference/get-filings-accession-144) | A Form 144 notice (or 144/A) as filed: issuer with address and phone, seller (CIK from the SEC header's reporting owner; the form names the seller only), relationships, the securities proposed to be sold with broker and approximate sale date, how they were acquired, the seller's sales of the past three months, plan adoption dates, and the notice's amendment chain on previousAccessionNumber (provisional). | | [`GET /v3/ownership/proposed-sales`](https://www.secblast.com/docs/reference/get-ownership-proposed-sales) | Form 144 notices across filings, newest first, each with its securities, acquisitions and past sales. | ## Exempt offerings (Form D) | Route | Returns | |---|---| | [`GET /v3/filings/{accession}/formd`](https://www.secblast.com/docs/reference/get-filings-accession-formd) | One Form D notice of an exempt offering as filed: offering (industry, exemptions, first sale, securities, minimum investment, the total offering amount, amount sold and remaining -- whole dollars, or Indefinite as filed -- investors, commissions, finders' fees, proceeds to related persons), every issuer, the related persons, the sales compensation recipients with their states, the header entities, and the offering chain (a D/A restates the whole notice: the chain's latest member is the offering). | | [`GET /v3/offerings`](https://www.secblast.com/docs/reference/get-offerings) | Form D notices across filings, newest first (filing date, accession). | ## Fund holdings (Form N-PORT) | Route | Returns | |---|---| | [`GET /v3/filings/{accession}/nport`](https://www.secblast.com/docs/reference/get-filings-accession-nport) | One N-PORT report as filed: registrant, series, share classes, report date, total assets, liabilities and net assets, monthly flows (sales, reinvestment, redemption) and other gains, monthly total returns per class, its place in the report ledger (an NPORT-P/A restates the whole report: one filing per series and report date is effective), and a page of its holdings in document order: identifiers (CUSIP classified -- a placeholder is never a CUSIP -- ISIN, ticker, LEI, other), balance, units, currency, value in USD, percent of net assets, asset and issuer categories, country, fair value level, and debt, repo, derivative and lending detail as filed. | | [`GET /v3/funds/holdings`](https://www.secblast.com/docs/reference/get-funds-holdings) | The N-PORT holdings of one security across funds, newest filing first: exactly one of cusip (only rows whose filed CUSIP is nine characters), isin or ticker (the holding's identifiers as filed). | | [`GET /v3/funds/{series_id}/reports`](https://www.secblast.com/docs/reference/get-funds-series-id-reports) | A fund series' N-PORT reports, newest report date first. | ## Datasets | Route | Returns | |---|---| | [`GET /v3/datasets`](https://www.secblast.com/docs/reference/get-datasets) | The catalogue of parsed datasets: per dataset its extractor, forms, deployed version, derive steps, tables, status (available or in_preparation), coverage (the first and last filing date of successful results: a range, not a statement that every filing in it is parsed), estimated row counts, when it last changed, and its parse queue. | ## Filing stream | Route | Returns | |---|---| | [`GET /v3/stream`](https://www.secblast.com/docs/reference/get-stream) | The filing stream: a cursor long-poll over every new, updated, corrected and deleted filing. | | [`GET /v3/stream/status`](https://www.secblast.com/docs/reference/get-stream-status) | Stream state: the head cursor, live ingest state, sequencer lag and latency percentiles of the last hour and day. | ## Webhooks (API: callbacks) | Route | Returns | |---|---| | [`GET /v3/callbacks/deliveries`](https://www.secblast.com/docs/reference/get-callbacks-deliveries) | The organization's webhook deliveries, newest first (created_at, then id), with the attempt count, the last status and error, when the next attempt is due (only while pending) and the bytes billed. | | [`GET /v3/callbacks/deliveries/{id}`](https://www.secblast.com/docs/reference/get-callbacks-deliveries-id) | One delivery of the organization with its payload and every attempt (n, at, duration_ms, http_status, error_class, remote_ip, response_excerpt), oldest first. | | [`POST /v3/callbacks/deliveries/{id}/retry`](https://www.secblast.com/docs/reference/post-callbacks-deliveries-id-retry) | Queues one more attempt of a failed delivery now (202, the delivery): it becomes pending and its attempts are not reset. | | [`GET /v3/callbacks/endpoints`](https://www.secblast.com/docs/reference/get-callbacks-endpoints) | The organization's webhook endpoints, newest first, with limits.endpoints (the plan's limit and the active endpoints), each with its health and last 24 hours of deliveries. | | [`POST /v3/callbacks/endpoints`](https://www.secblast.com/docs/reference/post-callbacks-endpoints) | Create a webhook endpoint. | | [`GET /v3/callbacks/endpoints/{id}`](https://www.secblast.com/docs/reference/get-callbacks-endpoints-id) | One webhook endpoint of the organization. | | [`PATCH /v3/callbacks/endpoints/{id}`](https://www.secblast.com/docs/reference/patch-callbacks-endpoints-id) | Change a webhook endpoint. | | [`DELETE /v3/callbacks/endpoints/{id}`](https://www.secblast.com/docs/reference/delete-callbacks-endpoints-id) | Delete a webhook endpoint. | | [`POST /v3/callbacks/endpoints/{id}/replay`](https://www.secblast.com/docs/reference/post-callbacks-endpoints-id-replay) | Queues again the failed and dropped deliveries of one endpoint created in a window (202 {replayed, truncated, last_created_at}): oldest first, at most 10,000 a call (truncated; continue with from = last_created_at). | | [`POST /v3/callbacks/endpoints/{id}/rotate-secret`](https://www.secblast.com/docs/reference/post-callbacks-endpoints-id-rotate-secret) | Rotate the endpoint's signing secret. | | [`POST /v3/callbacks/endpoints/{id}/test`](https://www.secblast.com/docs/reference/post-callbacks-endpoints-id-test) | Sends the endpoint one sample event of a type it takes, signed like any event, with test: true in its envelope and sample data (accession 0000000000-26-000001), and answers with the attempt's outcome: 200 {id, state, delivered, http_status, error_class, duration_ms} once the one attempt is made (a test send is not retried and not billed), or 202 {id, state} when no attempt was made within 12 seconds (it is still sent; see the delivery log). | | [`POST /v3/callbacks/endpoints/{id}/verify`](https://www.secblast.com/docs/reference/post-callbacks-endpoints-id-verify) | Sends the endpoint a new verification challenge (202, the endpoint): it is unverified, and its deliveries are held, until it answers 2xx with exactly the challenge. | | [`GET /v3/search/subscriptions`](https://www.secblast.com/docs/reference/get-search-subscriptions) | The organization's subscriptions, newest first, with limits by kind: filter (stored kind filing), firehose and search, each the plan's limit and the active subscriptions. | | [`POST /v3/search/subscriptions`](https://www.secblast.com/docs/reference/post-search-subscriptions) | Create a search subscription. | | [`GET /v3/search/subscriptions/{id}`](https://www.secblast.com/docs/reference/get-search-subscriptions-id) | One subscription of the organization. | | [`PATCH /v3/search/subscriptions/{id}`](https://www.secblast.com/docs/reference/patch-search-subscriptions-id) | Change a search subscription. | | [`DELETE /v3/search/subscriptions/{id}`](https://www.secblast.com/docs/reference/delete-search-subscriptions-id) | Delete a search subscription. | | [`POST /v3/search/subscriptions/{id}/test`](https://www.secblast.com/docs/reference/post-search-subscriptions-id-test) | Preview a search subscription: the payloads the subscription would have produced for filings accepted in the last 7 days (at most 5, newest first), as webhook envelopes with test: true; nothing is delivered or recorded. | ## Feedback | Route | Returns | |---|---| | [`POST /v3/feedback`](https://www.secblast.com/docs/reference/post-feedback) | Send feedback to SEC Blast. | ## Coverage, usage and service | Route | Returns | |---|---| | [`GET /v3/coverage`](https://www.secblast.com/docs/reference/get-coverage) | Ingest coverage: per feed day the latest non-superseded ingest run and the newest complete reconcile run, overall totals, and the snapshot store. | | [`GET /v3/coverage/count`](https://www.secblast.com/docs/reference/get-coverage-count) | The live filing count, in one small answer that needs no key, for polling: filings (final and provisional; deleted filings are not counted), provisional, deleted, documents, the newest acceptance time and, when this deployment has live ingest, the live daemon's latency over its day. | | [`GET /v3/coverage/summary`](https://www.secblast.com/docs/reference/get-coverage-summary) | What v3 holds, in one answer that needs no key: filings by status, documents, document versions, the feed days ingested (first, last, count), filings per filing-date year, amendment links by status, the known coverage gaps (a list maintained by hand) and, when this deployment has live ingest, the live daemon's state and lag. | | [`GET /v3/forms`](https://www.secblast.com/docs/reference/get-forms) | Form types present (deleted filings excluded) with filing counts, most frequent first. | | [`GET /v3/health`](https://www.secblast.com/docs/reference/get-health) | Liveness: one database round trip, the document root, and whether the snapshot store is usable. | | [`GET /v3/openapi.json`](https://www.secblast.com/docs/reference/get-openapi-json) | This OpenAPI 3.1 document. | | [`GET /v3/usage`](https://www.secblast.com/docs/reference/get-usage) | The calling key's limits and this month's usage: requests and billable response bytes (measured before compression; 5xx and 429 not billable) of its organization and of the key itself, what is left of the monthly allowance, when it starts again, and which limits are enforced. | --- # GET /v3/filings Search filings. Keyset pagination: pass next_cursor back as cursor with the same filters and sort. Deleted (withdrawn) filings are listed like any other, with status deleted; status=final,provisional leaves them out. q and role need cik or a filing-date window (filed_from and filed_to, at most 92 days apart): 400 otherwise. sort=accepted_at lists filings by the acceptance time stored in v3 (accepted_at, exact to the stored fraction of a second; ties by accession), from the database alone: pages are complete and has_more is exact. Filings without an acceptance time are not listed. With cik the entity's filings are read in time order from its own index. A cursor issued before acceptance times were stored in v3 is refused (400): start the listing again. **API key:** required. See [Authentication](https://www.secblast.com/docs/authentication). **Group:** [Filings](https://www.secblast.com/docs/reference#filings) ## Parameters | Name | In | Type | Required | Default | Description | |---|---|---|---|---|---| | `cik` | query | string | no | | CIK in any entity role, padded or unpadded. Combined with role and q on the same entity. | | `role` | query | string | no | | Entity role to match (with cik and/or q, or alone). Without cik it requires filed_from and filed_to at most 92 days apart (400 otherwise). One of: `filer`, `subject`, `filed_by`, `filed_for`, `reporting_owner`, `issuer`, `depositor`, `securitizer`, `issuing_entity`, `underwriter`, `serial_company`. | | `form` | query | comma-separated list of string | no | | Base form(s), exact, e.g. 10-K or 8-K,10-Q. Matches amendments too unless amendments=exclude. | | `amendments` | query | string | no | `include` | Whether to include amendments. One of: `include`, `exclude`, `only`. | | `form_type` | query | comma-separated list of string | no | | Exact form type(s) as filed, e.g. 10-K/A. | | `filed_from` | query | date (YYYY-MM-DD) | no | | filing_date \>= this date (inclusive). | | `filed_to` | query | date (YYYY-MM-DD) | no | | filing_date \<= this date (inclusive). | | `feed_from` | query | date (YYYY-MM-DD) | no | | feed_date \>= this date (inclusive). | | `feed_to` | query | date (YYYY-MM-DD) | no | | feed_date \<= this date (inclusive). | | `items` | query | comma-separated list of string | no | | Item codes (e.g. 2.02,9.01); a filing matches when it has any of them. | | `status` | query | comma-separated list of string | no | | Filing status(es), e.g. final or final,provisional. Default: every status, deleted filings included. | | `accepted_from` | query | string | no | | Acceptance time \>= this: YYYY-MM-DDTHH:MM:SSZ (UTC) or YYYY-MM-DD. Requires sort=accepted_at. | | `accepted_to` | query | string | no | | Acceptance time \<= this (inclusive; a date means the whole UTC day): YYYY-MM-DDTHH:MM:SSZ or YYYY-MM-DD. Requires sort=accepted_at. | | `q` | query | string | no | | Case-insensitive substring of an entity name as filed. Without cik it requires filed_from and filed_to at most 92 days apart (400 otherwise): the name is tested filing by filing. | | `sort` | query | string | no | `filing_date` | Sort key (ties broken by accession). One of: `filing_date`, `accession`, `accepted_at`. | | `order` | query | string | no | `desc` | Sort direction. One of: `desc`, `asc`. | | `limit` | query | integer | no | `50` | Page size, 1..1000. | | `cursor` | query | string | no | | Opaque cursor from a previous page's next_cursor. Must be used with the same filters, sort and order. | ## Responses | Status | Body | Description | |---|---|---| | `200` | [FilingList](https://www.secblast.com/docs/reference/schemas#schema-filinglist) (`application/json`) | OK | | `400` | [Problem](https://www.secblast.com/docs/reference/schemas#schema-problem) (`application/problem+json`) | Invalid or unknown parameter. | | `401` | [Problem](https://www.secblast.com/docs/reference/schemas#schema-problem) (`application/problem+json`) | Missing, invalid or inactive API key (code unauthorized), or a refused access token (code invalid_token: malformed, unknown key, bad signature, expired, wrong issuer or audience, revoked grant). WWW-Authenticate names the protected-resource metadata (RFC 9728). | | `503` | [Problem](https://www.secblast.com/docs/reference/schemas#schema-problem) (`application/problem+json`) | Database unavailable. | | `default` | [Problem](https://www.secblast.com/docs/reference/schemas#schema-problem) (`application/problem+json`) | Any other error (405, 500, 504). | ## Response body A `200` carries a [FilingList](https://www.secblast.com/docs/reference/schemas#schema-filinglist) object. | Field | Type | Required | Description | |---|---|---|---| | `data` | array of [Filing](https://www.secblast.com/docs/reference/schemas#schema-filing) | yes | | | `has_more` | boolean | yes | True when another page follows (pages are complete for every sort). | | `next_cursor` | string \| null | yes | | | `snapshot` | [Snapshot](https://www.secblast.com/docs/reference/schemas#schema-snapshot) | yes | | ## Example request ```bash curl -sS -H "Authorization: Bearer $SECBLAST_API_KEY" \ 'https://api.secblast.com/v3/filings' ``` [Open this route in the console](https://www.secblast.com/console#get-v3-filings) ## More in Filings Next: [`GET /v3/filings/{accession}`](https://www.secblast.com/docs/reference/get-filings-accession) --- # GET /v3/filings/{accession} One filing with entities, documents, events and its version chain. A filing SEC deleted (withdrew) is served like any other: status deleted, deleted true, deleted_at and the deletion block; its documents when they were delivered (a filing known only from its deletion notice has none). accepted_at and period_of_report are the stored values (see the Filing schema: a header time wins over SEC's, SEC's reportDate over the header's period); accepted_at_snapshot gives SEC's time when it differs. **API key:** required. See [Authentication](https://www.secblast.com/docs/authentication). **Group:** [Filings](https://www.secblast.com/docs/reference#filings) ## Parameters | Name | In | Type | Required | Default | Description | |---|---|---|---|---|---| | `accession` | path | string | yes | | Accession number, with dashes (0001829126-26-010431) or without (18 digits). | ## Responses | Status | Body | Description | |---|---|---| | `200` | [FilingDetail](https://www.secblast.com/docs/reference/schemas#schema-filingdetail) (`application/json`) | OK | | `400` | [Problem](https://www.secblast.com/docs/reference/schemas#schema-problem) (`application/problem+json`) | Invalid or unknown parameter. | | `401` | [Problem](https://www.secblast.com/docs/reference/schemas#schema-problem) (`application/problem+json`) | Missing, invalid or inactive API key (code unauthorized), or a refused access token (code invalid_token: malformed, unknown key, bad signature, expired, wrong issuer or audience, revoked grant). WWW-Authenticate names the protected-resource metadata (RFC 9728). | | `404` | [Problem](https://www.secblast.com/docs/reference/schemas#schema-problem) (`application/problem+json`) | Not found. | | `503` | [Problem](https://www.secblast.com/docs/reference/schemas#schema-problem) (`application/problem+json`) | Database unavailable; retry after the Retry-After delay. | | `default` | [Problem](https://www.secblast.com/docs/reference/schemas#schema-problem) (`application/problem+json`) | Any other error (405, 500, 504). | ## Response body A `200` carries a [FilingDetail](https://www.secblast.com/docs/reference/schemas#schema-filingdetail) object. | Field | Type | Required | Description | |---|---|---|---| | `accepted_at` | date-time (RFC 3339, UTC) \| null | no | The acceptance time stored in v3. A time from the filing's own header (source realtime or archives_txt) always wins over SEC's; once stored a time does not move (a later SEC value goes to accepted_at_snapshot). Otherwise SEC's submissions value: for a filing new since the previous snapshot sync, SEC's value minus the New York UTC offset (SEC's values carry that offset), source submissions_corrected; for history, SEC's value as given, source submissions_unverified (it may carry 0, 1 or 2 such offsets). Null when no source has a time. | | `accepted_at_snapshot` | date-time (RFC 3339, UTC) | no | Present only when SEC's submissions value differs from accepted_at (at whole seconds): SEC's value as given. | | `accepted_at_source` | string \| null | no | realtime / archives_txt: from the filing's header (live ingest / SEC Archives). submissions_corrected, submissions_unverified: from SEC's submissions snapshot (see accepted_at). oldload and submissions are not written any more. One of: `realtime`, `archives_txt`, `submissions_corrected`, `submissions_unverified`, `oldload`, `submissions`, `null`. | | `accession` | string | yes | | | `base_form` | string | yes | | | `deleted_at` | date-time (RFC 3339, UTC) \| null | no | | | `doc_count` | integer | no | | | `feed_date` | date (YYYY-MM-DD) \| null | no | | | `filing_date` | date (YYYY-MM-DD) | yes | | | `first_seen_at` | date-time (RFC 3339, UTC) \| null | no | | | `form_type` | string | yes | Form type as filed. | | `header_in_file` | boolean | no | Single filing only. false: SEC's submission file of the filing has no SGML header (part of the 1994-1995 Archives files hold only their documents); its form type, filing date and filers are SEC's submissions index values, links.header is null and /header answers 404 with reason no_header_in_file. | | `is_amendment` | boolean | yes | | | `is_inline_xbrl` | boolean \| null | no | SEC's isInlineXBRL; null as is_xbrl. | | `is_xbrl` | boolean \| null | no | SEC's isXBRL; null when SEC does not say or the snapshot sync has not seen the filing. | | `items` | array of string | no | | | `items_unmapped` | array of string | no | | | `links` | object | yes | | | `links.documents` | string | no | | | `links.events` | string | no | | | `links.header` | string \| null | no | null when header_in_file is false (single filing). | | `links.self` | string | no | | | `period_of_report` | date (YYYY-MM-DD) \| null | no | SEC's reportDate (submissions snapshot) when it gives one, otherwise the value in the filing's header. | | `period_of_report_header` | date (YYYY-MM-DD) \| null | no | Single filing only, and only when SEC's reportDate replaced a different header period: the header's (null: the header has none). | | `period_of_report_source` | string \| null | no | One of: `submissions`, `header`, `null`. | | `primary_cik` | string | yes | | | `primary_name` | string \| null | no | Name of the primary entity as filed (header_in_file false: the name SEC's submissions index gives for the filing date, or null). | | `provisional` | boolean | no | status == provisional. | | `sec_items` | array of string \| null | no | SEC's 8-K items list (items is the header's); null when the snapshot sync has not seen the filing. | | `sec_primary_doc_description` | string \| null | no | Single filing only: SEC's primaryDocDescription. | | `sec_primary_document` | string \| null | no | SEC's primaryDocument (file name). | | `sec_url` | string (URI) | yes | | | `snapshot_date` | date (YYYY-MM-DD) \| null | no | Single filing only: the snapshot whose values were last written to the filing; null when none was. | | `source` | string | no | realtime: registered by live ingest; it becomes feed when the nightly feed delivers the filing. One of: `feed`, `oldload`, `archives`, `realtime`. | | `status` | string | yes | provisional: registered by live ingest and not yet confirmed by the nightly feed, which makes it final (and may replace its documents). deleted: SEC deleted (withdrew) the filing; it is still served, with its documents when they were delivered (deleted_at, and the deletion block on the single filing). One of: `provisional`, `final`, `deleted`. | | `total_bytes` | integer | no | | | `date_of_change` | date (YYYY-MM-DD) \| null | no | | | `deleted` | boolean | no | status == deleted. | | `deletion` | object \| null | no | Only for a deleted filing (null otherwise): where the deletion came from. SEC's DELETION notice gives no reason. | | `deletion.feed_date` | date (YYYY-MM-DD) \| null | no | The feed day whose archive held the notice. | | `deletion.notice` | string \| null | no | The notice member, \#\. | | `deletion.recorded_at` | date-time (RFC 3339, UTC) \| null | no | When v3 registered the deletion. | | `deletion.source` | string \| null | no | Where the deletion notice came from, as the filing's events say it: feed (SEC's nightly feed, which carries the notices) for every deletion today. | | `documents` | array of [Document](https://www.secblast.com/docs/reference/schemas#schema-document) | no | | | `effectiveness_date` | date (YYYY-MM-DD) \| null | no | | | `entities` | array of [FilingEntity](https://www.secblast.com/docs/reference/schemas#schema-filingentity) | no | | | `events` | array of [Event](https://www.secblast.com/docs/reference/schemas#schema-event) | no | | | `finalized_at` | date-time (RFC 3339, UTC) \| null | no | | | `is_correction` | boolean | no | | | `is_paper` | boolean | no | | | `is_private_release` | boolean | no | | | `live` | object | no | Only while the filing is provisional and its source is realtime: where live ingest is with it. Gone once the filing is final. | | `live.documents_at` | date-time (RFC 3339, UTC) \| null | no | When its documents were registered; null until then. | | `live.listed_at` | date-time (RFC 3339, UTC) \| null | no | When the filing was listed. | | `live.state` | string | no | listed: the header is registered (entities, items, acceptance time, /header); doc_count is 0 and the documents are still being fetched. complete: the documents are registered. documents_failed: they could not be fetched; the nightly feed will supply them. One of: `listed`, `complete`, `documents_failed`. | | `previous_accession` | string \| null | no | | | `released_at` | date-time (RFC 3339, UTC) \| null | no | | | `snapshot` | [Snapshot](https://www.secblast.com/docs/reference/schemas#schema-snapshot) | no | | | `versions` | [Versions](https://www.secblast.com/docs/reference/schemas#schema-versions) | no | | ## Example request ```bash curl -sS -H "Authorization: Bearer $SECBLAST_API_KEY" \ 'https://api.secblast.com/v3/filings/0001829126-26-010431' ``` [Open this route in the console](https://www.secblast.com/console#get-v3-filings-accession) ## More in Filings Previous: [`GET /v3/filings`](https://www.secblast.com/docs/reference/get-filings) · Next: [`GET /v3/filings/{accession}/documents`](https://www.secblast.com/docs/reference/get-filings-accession-documents) --- # GET /v3/filings/{accession}/documents Documents of a filing, in sequence order. **API key:** required. See [Authentication](https://www.secblast.com/docs/authentication). **Group:** [Filings](https://www.secblast.com/docs/reference#filings) ## Parameters | Name | In | Type | Required | Default | Description | |---|---|---|---|---|---| | `accession` | path | string | yes | | Accession number, with dashes (0001829126-26-010431) or without (18 digits). | ## Responses | Status | Body | Description | |---|---|---| | `200` | [DocumentList](https://www.secblast.com/docs/reference/schemas#schema-documentlist) (`application/json`) | OK | | `400` | [Problem](https://www.secblast.com/docs/reference/schemas#schema-problem) (`application/problem+json`) | Invalid or unknown parameter. | | `401` | [Problem](https://www.secblast.com/docs/reference/schemas#schema-problem) (`application/problem+json`) | Missing, invalid or inactive API key (code unauthorized), or a refused access token (code invalid_token: malformed, unknown key, bad signature, expired, wrong issuer or audience, revoked grant). WWW-Authenticate names the protected-resource metadata (RFC 9728). | | `404` | [Problem](https://www.secblast.com/docs/reference/schemas#schema-problem) (`application/problem+json`) | Not found. | | `503` | [Problem](https://www.secblast.com/docs/reference/schemas#schema-problem) (`application/problem+json`) | Database unavailable; retry after the Retry-After delay. | | `default` | [Problem](https://www.secblast.com/docs/reference/schemas#schema-problem) (`application/problem+json`) | Any other error (405, 500, 504). | ## Response body A `200` carries a [DocumentList](https://www.secblast.com/docs/reference/schemas#schema-documentlist) object. | Field | Type | Required | Description | |---|---|---|---| | `data` | array of [Document](https://www.secblast.com/docs/reference/schemas#schema-document) | yes | | | `has_more` | boolean | no | | | `next_cursor` | string \| null | no | | ## Example request ```bash curl -sS -H "Authorization: Bearer $SECBLAST_API_KEY" \ 'https://api.secblast.com/v3/filings/0001829126-26-010431/documents' ``` [Open this route in the console](https://www.secblast.com/console#get-v3-filings-accession-documents) ## More in Filings Previous: [`GET /v3/filings/{accession}`](https://www.secblast.com/docs/reference/get-filings-accession) · Next: [`GET /v3/filings/{accession}/documents/{document}`](https://www.secblast.com/docs/reference/get-filings-accession-documents-document) --- # GET /v3/filings/{accession}/documents/{document} Stored bytes of one document. Supports ETag / If-None-Match (304) and single-range Range requests (206). Served with Content-Security-Policy: sandbox. **API key:** required. See [Authentication](https://www.secblast.com/docs/authentication). **Group:** [Filings](https://www.secblast.com/docs/reference#filings) ## Parameters | Name | In | Type | Required | Default | Description | |---|---|---|---|---|---| | `accession` | path | string | yes | | Accession number, with dashes (0001829126-26-010431) or without (18 digits). | | `document` | path | string | yes | | Sequence number (1, 2, ...) or the document's filename. | ## Responses | Status | Body | Description | |---|---|---| | `200` | binary (`*/*`) | The stored bytes. Headers: `Accept-Ranges`, `ETag`. | | `206` | binary (`*/*`) | The requested byte range. | | `304` | none | Not modified (If-None-Match matched the ETag). | | `400` | [Problem](https://www.secblast.com/docs/reference/schemas#schema-problem) (`application/problem+json`) | Invalid or unknown parameter. | | `401` | [Problem](https://www.secblast.com/docs/reference/schemas#schema-problem) (`application/problem+json`) | Missing, invalid or inactive API key (code unauthorized), or a refused access token (code invalid_token: malformed, unknown key, bad signature, expired, wrong issuer or audience, revoked grant). WWW-Authenticate names the protected-resource metadata (RFC 9728). | | `404` | [Problem](https://www.secblast.com/docs/reference/schemas#schema-problem) (`application/problem+json`) | Not found. | | `416` | [Problem](https://www.secblast.com/docs/reference/schemas#schema-problem) (`application/problem+json`) | Range not satisfiable. | | `503` | [Problem](https://www.secblast.com/docs/reference/schemas#schema-problem) (`application/problem+json`) | Database unavailable; retry after the Retry-After delay. | | `default` | [Problem](https://www.secblast.com/docs/reference/schemas#schema-problem) (`application/problem+json`) | Any other error (405, 500, 504). | ## Response body A `200` carries the stored bytes, with the content type of the document. ## Example request ```bash curl -sS -H "Authorization: Bearer $SECBLAST_API_KEY" \ 'https://api.secblast.com/v3/filings/0001829126-26-010431/documents/1' ``` [Open this route in the console](https://www.secblast.com/console#get-v3-filings-accession-documents-document) ## More in Filings Previous: [`GET /v3/filings/{accession}/documents`](https://www.secblast.com/docs/reference/get-filings-accession-documents) · Next: [`GET /v3/filings/{accession}/events`](https://www.secblast.com/docs/reference/get-filings-accession-events) --- # GET /v3/filings/{accession}/events Lifecycle events of a filing, oldest first. **API key:** required. See [Authentication](https://www.secblast.com/docs/authentication). **Group:** [Filings](https://www.secblast.com/docs/reference#filings) ## Parameters | Name | In | Type | Required | Default | Description | |---|---|---|---|---|---| | `accession` | path | string | yes | | Accession number, with dashes (0001829126-26-010431) or without (18 digits). | ## Responses | Status | Body | Description | |---|---|---| | `200` | [EventList](https://www.secblast.com/docs/reference/schemas#schema-eventlist) (`application/json`) | OK | | `400` | [Problem](https://www.secblast.com/docs/reference/schemas#schema-problem) (`application/problem+json`) | Invalid or unknown parameter. | | `401` | [Problem](https://www.secblast.com/docs/reference/schemas#schema-problem) (`application/problem+json`) | Missing, invalid or inactive API key (code unauthorized), or a refused access token (code invalid_token: malformed, unknown key, bad signature, expired, wrong issuer or audience, revoked grant). WWW-Authenticate names the protected-resource metadata (RFC 9728). | | `404` | [Problem](https://www.secblast.com/docs/reference/schemas#schema-problem) (`application/problem+json`) | Not found. | | `503` | [Problem](https://www.secblast.com/docs/reference/schemas#schema-problem) (`application/problem+json`) | Database unavailable; retry after the Retry-After delay. | | `default` | [Problem](https://www.secblast.com/docs/reference/schemas#schema-problem) (`application/problem+json`) | Any other error (405, 500, 504). | ## Response body A `200` carries a [EventList](https://www.secblast.com/docs/reference/schemas#schema-eventlist) object. | Field | Type | Required | Description | |---|---|---|---| | `data` | array of [Event](https://www.secblast.com/docs/reference/schemas#schema-event) | yes | | | `has_more` | boolean | no | | | `next_cursor` | string \| null | no | | ## Example request ```bash curl -sS -H "Authorization: Bearer $SECBLAST_API_KEY" \ 'https://api.secblast.com/v3/filings/0001829126-26-010431/events' ``` [Open this route in the console](https://www.secblast.com/console#get-v3-filings-accession-events) ## More in Filings Previous: [`GET /v3/filings/{accession}/documents/{document}`](https://www.secblast.com/docs/reference/get-filings-accession-documents-document) · Next: [`GET /v3/filings/{accession}/header`](https://www.secblast.com/docs/reference/get-filings-accession-header) --- # GET /v3/filings/{accession}/header The stored SGML header (_header.sgml) as text/plain. 404 with reason no_header_in_file when the filing's submission file has none (header_in_file false). For a filing known only from its deletion notice, the notice's header. **API key:** required. See [Authentication](https://www.secblast.com/docs/authentication). **Group:** [Filings](https://www.secblast.com/docs/reference#filings) ## Parameters | Name | In | Type | Required | Default | Description | |---|---|---|---|---|---| | `accession` | path | string | yes | | Accession number, with dashes (0001829126-26-010431) or without (18 digits). | ## Responses | Status | Body | Description | |---|---|---| | `200` | binary (`*/*`) | The stored bytes. Headers: `Accept-Ranges`, `ETag`. | | `206` | binary (`*/*`) | The requested byte range. | | `304` | none | Not modified (If-None-Match matched the ETag). | | `400` | [Problem](https://www.secblast.com/docs/reference/schemas#schema-problem) (`application/problem+json`) | Invalid or unknown parameter. | | `401` | [Problem](https://www.secblast.com/docs/reference/schemas#schema-problem) (`application/problem+json`) | Missing, invalid or inactive API key (code unauthorized), or a refused access token (code invalid_token: malformed, unknown key, bad signature, expired, wrong issuer or audience, revoked grant). WWW-Authenticate names the protected-resource metadata (RFC 9728). | | `404` | [Problem](https://www.secblast.com/docs/reference/schemas#schema-problem) (`application/problem+json`) | Not found. | | `416` | [Problem](https://www.secblast.com/docs/reference/schemas#schema-problem) (`application/problem+json`) | Range not satisfiable. | | `503` | [Problem](https://www.secblast.com/docs/reference/schemas#schema-problem) (`application/problem+json`) | Database unavailable; retry after the Retry-After delay. | | `default` | [Problem](https://www.secblast.com/docs/reference/schemas#schema-problem) (`application/problem+json`) | Any other error (405, 500, 504). | ## Response body A `200` carries the stored bytes, with the content type of the document. ## Example request ```bash curl -sS -H "Authorization: Bearer $SECBLAST_API_KEY" \ 'https://api.secblast.com/v3/filings/0001829126-26-010431/header' ``` [Open this route in the console](https://www.secblast.com/console#get-v3-filings-accession-header) ## More in Filings Previous: [`GET /v3/filings/{accession}/events`](https://www.secblast.com/docs/reference/get-filings-accession-events) · Next: [`GET /v3/filings/{accession}/versions`](https://www.secblast.com/docs/reference/get-filings-accession-versions) --- # GET /v3/filings/{accession}/versions Version chain of the filing's report: the original and every amendment, with how each amendment was linked. Members are ordered by amendment_seq (0 for the root, set when it is ingested; 1..n assigned to the amendments by the linker, null for an amendment it has not linked yet); the order of the amendments can still change until the snapshot lists every member. **API key:** required. See [Authentication](https://www.secblast.com/docs/authentication). **Group:** [Filings](https://www.secblast.com/docs/reference#filings) ## Parameters | Name | In | Type | Required | Default | Description | |---|---|---|---|---|---| | `accession` | path | string | yes | | Accession number, with dashes (0001829126-26-010431) or without (18 digits). | ## Responses | Status | Body | Description | |---|---|---| | `200` | [Versions](https://www.secblast.com/docs/reference/schemas#schema-versions) (`application/json`) | OK | | `400` | [Problem](https://www.secblast.com/docs/reference/schemas#schema-problem) (`application/problem+json`) | Invalid or unknown parameter. | | `401` | [Problem](https://www.secblast.com/docs/reference/schemas#schema-problem) (`application/problem+json`) | Missing, invalid or inactive API key (code unauthorized), or a refused access token (code invalid_token: malformed, unknown key, bad signature, expired, wrong issuer or audience, revoked grant). WWW-Authenticate names the protected-resource metadata (RFC 9728). | | `404` | [Problem](https://www.secblast.com/docs/reference/schemas#schema-problem) (`application/problem+json`) | Not found. | | `503` | [Problem](https://www.secblast.com/docs/reference/schemas#schema-problem) (`application/problem+json`) | Database unavailable; retry after the Retry-After delay. | | `default` | [Problem](https://www.secblast.com/docs/reference/schemas#schema-problem) (`application/problem+json`) | Any other error (405, 500, 504). | ## Response body A `200` carries a [Versions](https://www.secblast.com/docs/reference/schemas#schema-versions) object. | Field | Type | Required | Description | |---|---|---|---| | `count` | integer | no | Members of the whole chain, deleted and not-ingested included. | | `items` | array of object | no | | | `items[].accepted_at` | date-time (RFC 3339, UTC) \| null | no | As a filing's accepted_at; null for a member that is not ingested. | | `items[].accepted_at_snapshot` | date-time (RFC 3339, UTC) | no | As on a filing: only when SEC's value differs from accepted_at. | | `items[].accepted_at_source` | string \| null | no | | | `items[].accession` | string | no | | | `items[].amendment_no` | integer \| null | no | | | `items[].amendment_seq` | integer \| null | no | 0 for the root, 1..n for amendments in filing order. A filing that is not an amendment has 0 from the moment it is ingested; an amendment is null until the linker has linked it. | | `items[].amendment_type` | string \| null | no | | | `items[].current` | boolean | no | | | `items[].filing_date` | date (YYYY-MM-DD) \| null | no | | | `items[].form_type` | string \| null | no | | | `items[].header_in_file` | boolean \| null | no | As on GET /v3/filings/{accession}. | | `items[].ingested` | boolean | no | False for a root known only from an amendment's link. | | `items[].link` | object | no | | | `items[].link.candidates` | array of object | no | Possible originals, shown for an ambiguous link. | | `items[].link.confidence` | number \| null | no | | | `items[].link.method` | string \| null | no | One of: `explicit_header`, `explicit_xml`, `original_date`, `period_match`, `date_items_match`, `file_number`, `parties`, `filer_file_number`, `description_text`, `manual`, `null`. | | `items[].link.status` | string | no | One of: `resolved`, `ambiguous`, `unresolved`, `target_not_public`, `target_not_yet_ingested`. | | `items[].primary_cik` | string \| null | no | | | `items[].scope` | string \| null | no | | | `items[].sec_url` | string \| null | no | | | `items[].status` | string \| null | no | | | `latest` | string \| null | no | Newest ingested, non-deleted member; null when every ingested member is deleted. | | `position` | integer | no | 1-based place of this filing in the whole chain (not in items when truncated). | | `report_key` | string | no | Accession of the chain's root (the original filing, even when it is not ingested). | | `root` | string | no | Alias of report_key. | | `snapshot` | [Snapshot](https://www.secblast.com/docs/reference/schemas#schema-snapshot) | no | On /v3/filings/{accession}/versions only; the block embedded in a filing has none (the filing carries it). | | `truncated` | boolean | no | True when the chain has more than 200 members and items holds 200 of them (always the root, this filing and the latest, then the nearest to this filing). | ## Example request ```bash curl -sS -H "Authorization: Bearer $SECBLAST_API_KEY" \ 'https://api.secblast.com/v3/filings/0001829126-26-010431/versions' ``` [Open this route in the console](https://www.secblast.com/console#get-v3-filings-accession-versions) ## More in Filings Previous: [`GET /v3/filings/{accession}/header`](https://www.secblast.com/docs/reference/get-filings-accession-header) · Next: [`GET /v3/reports`](https://www.secblast.com/docs/reference/get-reports) --- # GET /v3/reports Reports of one entity: one row per version chain (an original plus its amendments), ordered by the original filing's date, newest first (a chain whose original is not ingested is dated by its first ingested amendment). form and period filter on that first filing (period on its stored period_of_report: SEC's reportDate when it gives one). A filing that is not an amendment is listed as soon as it is ingested, as a chain of one; an amendment joins its chain (or is listed as its own, when it cannot be linked) once the linker has processed it, and is absent until then. period_of_report and latest.accepted_at are the stored values (snapshot block: the snapshot they come from). **API key:** required. See [Authentication](https://www.secblast.com/docs/authentication). **Group:** [Filings](https://www.secblast.com/docs/reference#filings) ## Parameters | Name | In | Type | Required | Default | Description | |---|---|---|---|---|---| | `cik` | query | string | yes | | Primary CIK of the report, padded or unpadded. Required. | | `form` | query | comma-separated list of string | no | | Base form(s) of the chain's first filing, exact, e.g. 10-K or 10-K,10-Q. | | `period` | query | date (YYYY-MM-DD) | no | | Only chains whose first filing has this period_of_report. | | `limit` | query | integer | no | `50` | Page size, 1..200. | | `cursor` | query | string | no | | Opaque cursor from a previous page's next_cursor. Must be used with the same filters. | ## Responses | Status | Body | Description | |---|---|---| | `200` | [ReportList](https://www.secblast.com/docs/reference/schemas#schema-reportlist) (`application/json`) | OK | | `400` | [Problem](https://www.secblast.com/docs/reference/schemas#schema-problem) (`application/problem+json`) | Invalid or unknown parameter. | | `401` | [Problem](https://www.secblast.com/docs/reference/schemas#schema-problem) (`application/problem+json`) | Missing, invalid or inactive API key (code unauthorized), or a refused access token (code invalid_token: malformed, unknown key, bad signature, expired, wrong issuer or audience, revoked grant). WWW-Authenticate names the protected-resource metadata (RFC 9728). | | `503` | [Problem](https://www.secblast.com/docs/reference/schemas#schema-problem) (`application/problem+json`) | Database unavailable; retry after the Retry-After delay. | | `default` | [Problem](https://www.secblast.com/docs/reference/schemas#schema-problem) (`application/problem+json`) | Any other error (405, 500, 504). | ## Response body A `200` carries a [ReportList](https://www.secblast.com/docs/reference/schemas#schema-reportlist) object. | Field | Type | Required | Description | |---|---|---|---| | `data` | array of [Report](https://www.secblast.com/docs/reference/schemas#schema-report) | yes | | | `has_more` | boolean | yes | | | `next_cursor` | string \| null | yes | | | `snapshot` | [Snapshot](https://www.secblast.com/docs/reference/schemas#schema-snapshot) | yes | | ## Example request ```bash curl -sS -H "Authorization: Bearer $SECBLAST_API_KEY" \ 'https://api.secblast.com/v3/reports?cik=320193' ``` The entity in this example is only an illustration. [Open this route in the console](https://www.secblast.com/console#get-v3-reports) ## More in Filings Previous: [`GET /v3/filings/{accession}/versions`](https://www.secblast.com/docs/reference/get-filings-accession-versions) --- # GET /v3/companies Companies that are or were SPACs (blank checks, SIC 6770), from the SIC and names in their filing headers over time. spac=former: the de-SPACed companies, newest merger close first (then CIK), each with the close date, the filing it comes from and its basis (item_2_01: the period of report of the completion-of-acquisition 8-K; sic_change: the first filing under the new SIC; name_change: the date the SPAC name was dropped). spac=current: entities whose filings still read SIC 6770, by CIK. The same object is the spac member of /v3/entities/{cik}. **API key:** required. See [Authentication](https://www.secblast.com/docs/authentication). **Group:** [Entities](https://www.secblast.com/docs/reference#entities) ## Parameters | Name | In | Type | Required | Default | Description | |---|---|---|---|---|---| | `spac` | query | string | no | | former or current (required). One of: `former`, `current`. | | `closed_from` | query | date (YYYY-MM-DD) | no | | spac=former: first merger close date (inclusive), YYYY-MM-DD. | | `closed_to` | query | date (YYYY-MM-DD) | no | | spac=former: last merger close date (inclusive), YYYY-MM-DD. | | `limit` | query | integer | no | `100` | Page size, 1..1000. | | `cursor` | query | string | no | | Opaque cursor from a previous page's next_cursor; bound to the filters. | ## Responses | Status | Body | Description | |---|---|---| | `200` | [SpacCompanies](https://www.secblast.com/docs/reference/schemas#schema-spaccompanies) (`application/json`) | OK | | `400` | [Problem](https://www.secblast.com/docs/reference/schemas#schema-problem) (`application/problem+json`) | Invalid or unknown parameter. | | `401` | [Problem](https://www.secblast.com/docs/reference/schemas#schema-problem) (`application/problem+json`) | Missing, invalid or inactive API key (code unauthorized), or a refused access token (code invalid_token: malformed, unknown key, bad signature, expired, wrong issuer or audience, revoked grant). WWW-Authenticate names the protected-resource metadata (RFC 9728). | | `503` | [Problem](https://www.secblast.com/docs/reference/schemas#schema-problem) (`application/problem+json`) | Database unavailable; retry after the Retry-After delay. | | `default` | [Problem](https://www.secblast.com/docs/reference/schemas#schema-problem) (`application/problem+json`) | Any other error (405, 500, 504). | ## Response body A `200` carries a [SpacCompanies](https://www.secblast.com/docs/reference/schemas#schema-spaccompanies) object. | Field | Type | Required | Description | |---|---|---|---| | `data` | array of object | yes | | | `data[].cik` | string | no | | | `data[].links` | object | no | | | `data[].name` | string \| null | no | | | `data[].spac` | [Spac](https://www.secblast.com/docs/reference/schemas#schema-spac) | no | | | `has_more` | boolean | yes | | | `next_cursor` | string \| null | yes | | | `spac` | string | yes | One of: `former`, `current`. | ## Example request ```bash curl -sS -H "Authorization: Bearer $SECBLAST_API_KEY" \ 'https://api.secblast.com/v3/companies' ``` [Open this route in the console](https://www.secblast.com/console#get-v3-companies) ## More in Entities Next: [`GET /v3/entities`](https://www.secblast.com/docs/reference/get-entities) --- # GET /v3/entities Entity search. With q: SEC's snapshot is searched by current and former name, ticker and CIK (snapshot.available=true). When the snapshot store is unavailable: names as filed containing q, or CIKs starting with q. Without q: the most active entities as filed. Those two answers come from v3's own filings and look only at filings filed in the 30 days up to the newest filing date in v3 (most active = named by most filings of those days); an entity seen only in older filings is not listed. filings is always the entity's whole count in v3. **API key:** required. See [Authentication](https://www.secblast.com/docs/authentication). **Group:** [Entities](https://www.secblast.com/docs/reference#entities) ## Parameters | Name | In | Type | Required | Default | Description | |---|---|---|---|---|---| | `q` | query | string | no | | Name, ticker or CIK. Omit to list the most active entities as filed (of the last 30 days of filings). | | `limit` | query | integer | no | `20` | Maximum results, 1..50. | ## Responses | Status | Body | Description | |---|---|---| | `200` | [EntityList](https://www.secblast.com/docs/reference/schemas#schema-entitylist) (`application/json`) | OK | | `400` | [Problem](https://www.secblast.com/docs/reference/schemas#schema-problem) (`application/problem+json`) | Invalid or unknown parameter. | | `401` | [Problem](https://www.secblast.com/docs/reference/schemas#schema-problem) (`application/problem+json`) | Missing, invalid or inactive API key (code unauthorized), or a refused access token (code invalid_token: malformed, unknown key, bad signature, expired, wrong issuer or audience, revoked grant). WWW-Authenticate names the protected-resource metadata (RFC 9728). | | `503` | [Problem](https://www.secblast.com/docs/reference/schemas#schema-problem) (`application/problem+json`) | Database unavailable; retry after the Retry-After delay. | | `default` | [Problem](https://www.secblast.com/docs/reference/schemas#schema-problem) (`application/problem+json`) | Any other error (405, 500, 504). | ## Response body A `200` carries a [EntityList](https://www.secblast.com/docs/reference/schemas#schema-entitylist) object. | Field | Type | Required | Description | |---|---|---|---| | `data` | array of [EntityMatch](https://www.secblast.com/docs/reference/schemas#schema-entitymatch) | yes | | | `has_more` | boolean | no | | | `next_cursor` | string \| null | no | | | `snapshot` | [Snapshot](https://www.secblast.com/docs/reference/schemas#schema-snapshot) | yes | available is true when the snapshot was searched; false when the list is names as filed. | ## Example request ```bash curl -sS -H "Authorization: Bearer $SECBLAST_API_KEY" \ 'https://api.secblast.com/v3/entities' ``` [Open this route in the console](https://www.secblast.com/console#get-v3-entities) ## More in Entities Previous: [`GET /v3/companies`](https://www.secblast.com/docs/reference/get-companies) · Next: [`GET /v3/entities/{cik}`](https://www.secblast.com/docs/reference/get-entities-cik) --- # GET /v3/entities/{cik} Most recent as-filed attributes of a CIK, SEC's current entity record from the snapshot (current), roles seen and filing counts. 404 when neither v3 nor the snapshot knows the CIK; when this deployment has no snapshot store configured, 404 whenever v3 has no filing for the CIK (v3 is then the only source). When a configured snapshot store is unavailable and v3 has no filing for the CIK the answer is 200 {cik, data: null, snapshot}: it cannot be told. **API key:** required. See [Authentication](https://www.secblast.com/docs/authentication). **Group:** [Entities](https://www.secblast.com/docs/reference#entities) ## Parameters | Name | In | Type | Required | Default | Description | |---|---|---|---|---|---| | `cik` | path | string | yes | | CIK, padded or unpadded. | ## Responses | Status | Body | Description | |---|---|---| | `200` | [Entity](https://www.secblast.com/docs/reference/schemas#schema-entity) (`application/json`) | OK | | `400` | [Problem](https://www.secblast.com/docs/reference/schemas#schema-problem) (`application/problem+json`) | Invalid or unknown parameter. | | `401` | [Problem](https://www.secblast.com/docs/reference/schemas#schema-problem) (`application/problem+json`) | Missing, invalid or inactive API key (code unauthorized), or a refused access token (code invalid_token: malformed, unknown key, bad signature, expired, wrong issuer or audience, revoked grant). WWW-Authenticate names the protected-resource metadata (RFC 9728). | | `404` | [Problem](https://www.secblast.com/docs/reference/schemas#schema-problem) (`application/problem+json`) | Not found. | | `503` | [Problem](https://www.secblast.com/docs/reference/schemas#schema-problem) (`application/problem+json`) | Database unavailable; retry after the Retry-After delay. | | `default` | [Problem](https://www.secblast.com/docs/reference/schemas#schema-problem) (`application/problem+json`) | Any other error (405, 500, 504). | ## Response body A `200` carries a [Entity](https://www.secblast.com/docs/reference/schemas#schema-entity) object. | Field | Type | Required | Description | |---|---|---|---| | `addresses` | [Addresses](https://www.secblast.com/docs/reference/schemas#schema-addresses) | no | | | `as_of` | object \| null | no | The filing the as-filed attributes come from; null when v3 has no filing for the CIK. | | `as_of.accession` | string | no | | | `as_of.filing_date` | date (YYYY-MM-DD) | no | | | `as_of.role` | string | no | | | `cik` | string | no | | | `current` | [EntityCurrent](https://www.secblast.com/docs/reference/schemas#schema-entitycurrent) | no | | | `data` | null | no | Present (null) only in the {cik, data, snapshot} body described above. | | `filings` | integer | no | Filings in v3 that name the entity. | | `first_filing_date` | date (YYYY-MM-DD) \| null | no | | | `fiscal_year_end` | string \| null | no | | | `former_names` | array of object | no | | | `irs_number` | string \| null | no | | | `last_filing_date` | date (YYYY-MM-DD) \| null | no | | | `links` | object | no | | | `links.filings` | string | no | | | `links.sec_filings` | string | no | | | `links.self` | string | no | | | `name` | string \| null | no | | | `role_counts` | object | no | | | `roles` | array of string | no | | | `sic` | string \| null | no | | | `snapshot` | [Snapshot](https://www.secblast.com/docs/reference/schemas#schema-snapshot) | no | | | `spac` | [Spac](https://www.secblast.com/docs/reference/schemas#schema-spac) | no | | | `state_of_inc` | string \| null | no | | ## Example request ```bash curl -sS -H "Authorization: Bearer $SECBLAST_API_KEY" \ 'https://api.secblast.com/v3/entities/320193' ``` The entity in this example is only an illustration. [Open this route in the console](https://www.secblast.com/console#get-v3-entities-cik) ## More in Entities Previous: [`GET /v3/entities`](https://www.secblast.com/docs/reference/get-entities) · Next: [`GET /v3/entities/{cik}/filings`](https://www.secblast.com/docs/reference/get-entities-cik-filings) --- # GET /v3/entities/{cik}/filings SEC's own filing list for the entity (from the submissions snapshot), newest first; each row says whether v3 has the filing. 404 when the snapshot has no such CIK. Empty data with snapshot.available=false when the snapshot store is unavailable. Paged with offset (pass next_offset back as offset; next_cursor is always null): the list can shift when a new snapshot is loaded. **API key:** required. See [Authentication](https://www.secblast.com/docs/authentication). **Group:** [Entities](https://www.secblast.com/docs/reference#entities) ## Parameters | Name | In | Type | Required | Default | Description | |---|---|---|---|---|---| | `cik` | path | string | yes | | CIK, padded or unpadded. | | `form` | query | comma-separated list of string | no | | Exact form type(s), e.g. 10-K or 8-K,8-K/A. | | `filed_from` | query | date (YYYY-MM-DD) | no | | filing_date \>= this date (inclusive). | | `filed_to` | query | date (YYYY-MM-DD) | no | | filing_date \<= this date (inclusive). | | `limit` | query | integer | no | `50` | Page size, 1..1000. | | `offset` | query | integer | no | `0` | Rows to skip, 0..100000000. | ## Responses | Status | Body | Description | |---|---|---| | `200` | [SecFilingList](https://www.secblast.com/docs/reference/schemas#schema-secfilinglist) (`application/json`) | OK | | `400` | [Problem](https://www.secblast.com/docs/reference/schemas#schema-problem) (`application/problem+json`) | Invalid or unknown parameter. | | `401` | [Problem](https://www.secblast.com/docs/reference/schemas#schema-problem) (`application/problem+json`) | Missing, invalid or inactive API key (code unauthorized), or a refused access token (code invalid_token: malformed, unknown key, bad signature, expired, wrong issuer or audience, revoked grant). WWW-Authenticate names the protected-resource metadata (RFC 9728). | | `404` | [Problem](https://www.secblast.com/docs/reference/schemas#schema-problem) (`application/problem+json`) | Not found. | | `503` | [Problem](https://www.secblast.com/docs/reference/schemas#schema-problem) (`application/problem+json`) | Database unavailable; retry after the Retry-After delay. | | `default` | [Problem](https://www.secblast.com/docs/reference/schemas#schema-problem) (`application/problem+json`) | Any other error (405, 500, 504). | ## Response body A `200` carries a [SecFilingList](https://www.secblast.com/docs/reference/schemas#schema-secfilinglist) object. | Field | Type | Required | Description | |---|---|---|---| | `data` | array of [SecFiling](https://www.secblast.com/docs/reference/schemas#schema-secfiling) | yes | | | `has_more` | boolean | no | | | `next_cursor` | string \| null | no | Always null: this list is paged with offset; use next_offset. | | `next_offset` | integer \| null | no | The offset of the next page; null on the last page (and when the snapshot store is unavailable). | | `offset` | integer | no | | | `snapshot` | [Snapshot](https://www.secblast.com/docs/reference/schemas#schema-snapshot) | yes | | | `total` | integer \| null | no | Rows matching the filters; null when the snapshot store is unavailable. | ## Example request ```bash curl -sS -H "Authorization: Bearer $SECBLAST_API_KEY" \ 'https://api.secblast.com/v3/entities/320193/filings' ``` The entity in this example is only an illustration. [Open this route in the console](https://www.secblast.com/console#get-v3-entities-cik-filings) ## More in Entities Previous: [`GET /v3/entities/{cik}`](https://www.secblast.com/docs/reference/get-entities-cik) · Next: [`GET /v3/resolve`](https://www.secblast.com/docs/reference/get-resolve) --- # GET /v3/resolve Which CIK(s) hold a ticker, from SEC's ticker file; with as_of, from the copy that was current on that date. Empty data when the ticker is unknown, the date precedes coverage_from, or the snapshot store is unavailable. **API key:** required. See [Authentication](https://www.secblast.com/docs/authentication). **Group:** [Entities](https://www.secblast.com/docs/reference#entities) ## Parameters | Name | In | Type | Required | Default | Description | |---|---|---|---|---|---| | `ticker` | query | string | yes | | Ticker symbol (case-insensitive): 1 to 16 letters, digits, '.' or '-'. Required. | | `as_of` | query | date (YYYY-MM-DD) | no | | Date to resolve on, YYYY-MM-DD. Default: the newest copy. | ## Responses | Status | Body | Description | |---|---|---| | `200` | [ResolveResult](https://www.secblast.com/docs/reference/schemas#schema-resolveresult) (`application/json`) | OK | | `400` | [Problem](https://www.secblast.com/docs/reference/schemas#schema-problem) (`application/problem+json`) | Invalid or unknown parameter. | | `401` | [Problem](https://www.secblast.com/docs/reference/schemas#schema-problem) (`application/problem+json`) | Missing, invalid or inactive API key (code unauthorized), or a refused access token (code invalid_token: malformed, unknown key, bad signature, expired, wrong issuer or audience, revoked grant). WWW-Authenticate names the protected-resource metadata (RFC 9728). | | `503` | [Problem](https://www.secblast.com/docs/reference/schemas#schema-problem) (`application/problem+json`) | Database unavailable; retry after the Retry-After delay. | | `default` | [Problem](https://www.secblast.com/docs/reference/schemas#schema-problem) (`application/problem+json`) | Any other error (405, 500, 504). | ## Response body A `200` carries a [ResolveResult](https://www.secblast.com/docs/reference/schemas#schema-resolveresult) object. | Field | Type | Required | Description | |---|---|---|---| | `as_of` | date (YYYY-MM-DD) \| null | no | | | `coverage_from` | date (YYYY-MM-DD) \| null | no | The oldest copy kept; earlier dates cannot be resolved. | | `data` | array of [ResolveMatch](https://www.secblast.com/docs/reference/schemas#schema-resolvematch) | yes | | | `file_date` | date (YYYY-MM-DD) \| null | no | The daily copy of SEC's ticker file that answered. | | `has_more` | boolean | no | | | `next_cursor` | string \| null | no | | | `snapshot` | [Snapshot](https://www.secblast.com/docs/reference/schemas#schema-snapshot) | yes | available is false when the store could not be asked, or had neither a ticker file nor a snapshot to consult: empty data then means unknown, not that no entity holds the ticker. | | `source` | string \| null | no | One of: `sec_company_tickers`, `submissions`, `null`. | | `ticker` | string | yes | | ## Example request ```bash curl -sS -H "Authorization: Bearer $SECBLAST_API_KEY" \ 'https://api.secblast.com/v3/resolve?ticker=AAPL' ``` The entity in this example is only an illustration. [Open this route in the console](https://www.secblast.com/console#get-v3-resolve) ## More in Entities Previous: [`GET /v3/entities/{cik}/filings`](https://www.secblast.com/docs/reference/get-entities-cik-filings) --- # GET /v3/filings/{accession}/documents/{document}/text The extracted text of one document as the full-text index holds it (text/plain; charset=utf-8): the text that snippet start/end offsets count characters of. Headers: X-Extractor and X-Extractor-Version (offsets apply to that extractor), X-Text-Chars (the length in characters). ETag / If-None-Match (304) and single-range Range requests on the UTF-8 bytes (206, 416). 404 with code no_text for a document indexed without text. A filing SEC deleted is indexed like any other (status deleted) and its text is served; a deleted filing without documents has none (404). **API key:** required. See [Authentication](https://www.secblast.com/docs/authentication). **Group:** [Full-text search](https://www.secblast.com/docs/reference#full-text-search) ## Parameters | Name | In | Type | Required | Default | Description | |---|---|---|---|---|---| | `accession` | path | string | yes | | Accession number, with dashes (0001829126-26-010431) or without (18 digits). | | `document` | path | string | yes | | Sequence number (1, 2, ...) or the document's filename. | ## Responses | Status | Body | Description | |---|---|---| | `200` | string (`text/plain`) | The extracted text. Headers: `Accept-Ranges`, `ETag`, `X-Extractor`, `X-Extractor-Version`, `X-Text-Chars`. | | `206` | string (`text/plain`) | The requested byte range of the UTF-8 text. Headers: `Accept-Ranges`, `ETag`, `X-Extractor`, `X-Extractor-Version`, `X-Text-Chars`. | | `304` | none | Not modified (If-None-Match matched the ETag). | | `400` | [Problem](https://www.secblast.com/docs/reference/schemas#schema-problem) (`application/problem+json`) | Invalid or unknown parameter, or a query error (invalid_query, query_too_complex, prefix_too_broad, negative_only_query, unsupported_operator, invalid_cursor); query errors carry position and length (characters of q). | | `401` | [Problem](https://www.secblast.com/docs/reference/schemas#schema-problem) (`application/problem+json`) | Missing, invalid or inactive API key (code unauthorized), or a refused access token (code invalid_token: malformed, unknown key, bad signature, expired, wrong issuer or audience, revoked grant). WWW-Authenticate names the protected-resource metadata (RFC 9728). | | `404` | [Problem](https://www.secblast.com/docs/reference/schemas#schema-problem) (`application/problem+json`) | Not found. | | `416` | [Problem](https://www.secblast.com/docs/reference/schemas#schema-problem) (`application/problem+json`) | Range not satisfiable. | | `503` | [Problem](https://www.secblast.com/docs/reference/schemas#schema-problem) (`application/problem+json`) | Full-text search cannot answer now: search_unavailable (sb_search unreachable or not configured), search_busy (its queue is full), search_timeout (the query hit its time budget), ticker_resolution_unavailable; or the database is unavailable. Retry after the Retry-After delay when one is given. | | `default` | [Problem](https://www.secblast.com/docs/reference/schemas#schema-problem) (`application/problem+json`) | Any other error (405, 500, 504). | ## Response body A `200` carries string (`text/plain`). ## Example request ```bash curl -sS -H "Authorization: Bearer $SECBLAST_API_KEY" \ 'https://api.secblast.com/v3/filings/0001829126-26-010431/documents/1/text' ``` [Open this route in the console](https://www.secblast.com/console#get-v3-filings-accession-documents-document-text) ## More in Full-text search Next: [`GET /v3/search`](https://www.secblast.com/docs/reference/get-search) --- # GET /v3/search Full-text search over every document v3 holds (spec §6.1). q uses the SEC Blast query syntax (syntax=edgar reads it as EDGAR full-text search does); the structured parameters are AND-ed with it, and EDGAR's own URL parameters (forms, ciks, startdt, enddt, dateRange, entityName, locationCode, locationType, category, page) are accepted, so an EDGAR search URL replays. Rows are documents (group=document) or filings with their best documents (group=filing); each document carries url, the route of its stored bytes. Snippet offsets are characters of the text that /v3/filings/{accession}/documents/{document}/text returns. Page with cursor (next_cursor). fields= trims the rows, never the envelope. Query errors are 400 with position and length; 503 search_busy, search_timeout and ticker_resolution_unavailable carry Retry-After. **API key:** required. See [Authentication](https://www.secblast.com/docs/authentication). **Group:** [Full-text search](https://www.secblast.com/docs/reference#full-text-search) ## Parameters | Name | In | Type | Required | Default | Description | |---|---|---|---|---|---| | `q` | query | string | no | | Query (at most 1,000 characters); empty lists by filters only. | | `syntax` | query | string | no | `sb` | Query syntax. One of: `sb`, `edgar`. | | `match` | query | string | no | `exact` | Term matching. One of: `exact`, `stem`. | | `forms` | query | comma-separated list of string | no | | Root form types (EDGAR alias): 10-K matches 10-K, 10-K/A, 10-K405. A leading - excludes (forms=-3,-4,-5). | | `form_types` | query | comma-separated list of string | no | | Exact form types, for example 10-K/A. A leading - excludes. | | `form_families` | query | comma-separated list of string | no | | Root form types. A leading - excludes. | | `doctypes` | query | comma-separated list of string | no | | Document types; a \* suffix matches a prefix (EX-10\*). | | `ciks` | query | comma-separated list of string | no | | CIKs (1 to 10 digits each, at most 1,024). | | `tickers` | query | comma-separated list of string | no | | Tickers (at most 64); sb_search resolves them to CIKs. | | `sics` | query | comma-separated list of string | no | | SIC codes; a \* suffix matches a prefix (73\*). | | `states` | query | comma-separated list of string | no | | Business-address state codes. | | `inc_states` | query | comma-separated list of string | no | | State-of-incorporation codes. | | `filed_from` | query | date (YYYY-MM-DD) | no | | Earliest filing date, YYYY-MM-DD. | | `filed_to` | query | date (YYYY-MM-DD) | no | | Latest filing date, YYYY-MM-DD. | | `startdt` | query | date (YYYY-MM-DD) | no | | EDGAR alias of filed_from. | | `enddt` | query | date (YYYY-MM-DD) | no | | EDGAR alias of filed_to. | | `dateRange` | query | string | no | | `all` applies no lower bound and is a 400 with startdt/filed_from; `10y`, `5y`, `1y`, `30d` set filed_from relative to today and are also a 400 with startdt/filed_from; `custom` (default) uses startdt/filed_from. One of: `all`, `10y`, `5y`, `1y`, `30d`, `custom`. | | `accepted_to` | query | string | no | | Latest acceptance time: YYYY-MM-DDTHH:MM:SSZ, or a date meaning the end of that UTC day. | | `as_of` | query | string | no | | Alias of accepted_to. | | `status` | query | comma-separated list of string | no | | Filing statuses: provisional, final, deleted (SEC deleted the filing; its documents stay searchable). Default: every status, deleted filings included. | | `primary_only` | query | string | no | `auto` | Primary documents only. auto: true when q is empty, else false. One of: `true`, `false`, `auto`. | | `entityName` | query | string | no | | EDGAR entity name; becomes a name phrase filter (approximate). | | `locationCode` | query | string | no | | EDGAR state code; becomes states, or inc_states when locationType=incorporated. | | `locationType` | query | string | no | | EDGAR: located or incorporated; consumed by locationCode. | | `category` | query | string | no | | Accepted for EDGAR URL replay; ignored. | | `page` | query | string | no | | Accepted for EDGAR URL replay; ignored (use cursor). | | `group` | query | string | no | `document` | Result unit. One of: `document`, `filing`. | | `collapse` | query | string | no | `false` | Collapse near-duplicate results. One of: `true`, `false`. | | `sort` | query | string | no | | Sort key; default relevance when q has a positive term, else date. One of: `relevance`, `date`, `accepted`. | | `order` | query | string | no | `desc` | Sort order. One of: `desc`, `asc`. | | `limit` | query | integer | no | `20` | Page size, 1 to 100. | | `cursor` | query | string | no | | Opaque cursor from next_cursor. | | `from` | query | integer | no | `0` | Offset, 0 to 10,000 (compatibility; use cursor beyond). | | `facets` | query | comma-separated list of string | no | | Facets to compute: form, year, sic, state. | | `facet_size` | query | integer | no | `30` | Buckets per facet, 1 to 100. | | `snippets` | query | integer | no | `1` | Snippets per document, 0 to 5. | | `snippet_chars` | query | integer | no | `240` | Snippet length, 80 to 600. | | `docs_per_filing` | query | integer | no | `3` | Documents shown per filing, 1 to 10. | | `fields` | query | comma-separated list of string | no | | Hit members to keep in each row. | | `totals` | query | string | no | `true` | Compute totals. One of: `true`, `false`. | ## Responses | Status | Body | Description | |---|---|---| | `200` | [SearchResults](https://www.secblast.com/docs/reference/schemas#schema-searchresults) (`application/json`) | OK | | `400` | [Problem](https://www.secblast.com/docs/reference/schemas#schema-problem) (`application/problem+json`) | Invalid or unknown parameter, or a query error (invalid_query, query_too_complex, prefix_too_broad, negative_only_query, unsupported_operator, invalid_cursor); query errors carry position and length (characters of q). | | `401` | [Problem](https://www.secblast.com/docs/reference/schemas#schema-problem) (`application/problem+json`) | Missing, invalid or inactive API key (code unauthorized), or a refused access token (code invalid_token: malformed, unknown key, bad signature, expired, wrong issuer or audience, revoked grant). WWW-Authenticate names the protected-resource metadata (RFC 9728). | | `503` | [Problem](https://www.secblast.com/docs/reference/schemas#schema-problem) (`application/problem+json`) | Full-text search cannot answer now: search_unavailable (sb_search unreachable or not configured), search_busy (its queue is full), search_timeout (the query hit its time budget), ticker_resolution_unavailable; or the database is unavailable. Retry after the Retry-After delay when one is given. | | `default` | [Problem](https://www.secblast.com/docs/reference/schemas#schema-problem) (`application/problem+json`) | Any other error (405, 500, 504). | ## Response body A `200` carries a [SearchResults](https://www.secblast.com/docs/reference/schemas#schema-searchresults) object. | Field | Type | Required | Description | |---|---|---|---| | `data` | array of [SearchHit](https://www.secblast.com/docs/reference/schemas#schema-searchhit) | yes | | | `facets` | [SearchFacets](https://www.secblast.com/docs/reference/schemas#schema-searchfacets) | no | | | `has_more` | boolean | yes | | | `index` | [SearchIndexInfo](https://www.secblast.com/docs/reference/schemas#schema-searchindexinfo) | yes | | | `next_cursor` | string \| null | yes | Pass back as cursor with the same query, filters, sort and group. Null when nothing follows, and always null with from \> 0. | | `resolved` | object | yes | {tickers: {TICKER: \[cik, ...\]}}: how tickers were resolved. | | `resolved.tickers` | object | no | | | `took_ms` | integer | yes | | | `total` | [SearchTotals](https://www.secblast.com/docs/reference/schemas#schema-searchtotals) | yes | | | `warnings` | array of [SearchWarning](https://www.secblast.com/docs/reference/schemas#schema-searchwarning) | yes | | ## Example request ```bash curl -sS -H "Authorization: Bearer $SECBLAST_API_KEY" \ 'https://api.secblast.com/v3/search' ``` [Open this route in the console](https://www.secblast.com/console#get-v3-search) ## More in Full-text search Previous: [`GET /v3/filings/{accession}/documents/{document}/text`](https://www.secblast.com/docs/reference/get-filings-accession-documents-document-text) · Next: [`GET /v3/search/parse`](https://www.secblast.com/docs/reference/get-search-parse) --- # GET /v3/search/parse How a query is read, without running it: the normalised query, its tree, the EDGAR reading beside the default one, prefix expansions, the structured filters after alias mapping and ticker resolution, and the index years it would touch. Errors as /v3/search. **API key:** required. See [Authentication](https://www.secblast.com/docs/authentication). **Group:** [Full-text search](https://www.secblast.com/docs/reference#full-text-search) ## Parameters | Name | In | Type | Required | Default | Description | |---|---|---|---|---|---| | `q` | query | string | no | | Query (at most 1,000 characters). | | `syntax` | query | string | no | `sb` | Query syntax. One of: `sb`, `edgar`. | | `match` | query | string | no | `exact` | Term matching. One of: `exact`, `stem`. | | `forms` | query | comma-separated list of string | no | | Root form types (EDGAR alias): 10-K matches 10-K, 10-K/A, 10-K405. A leading - excludes (forms=-3,-4,-5). | | `form_types` | query | comma-separated list of string | no | | Exact form types, for example 10-K/A. A leading - excludes. | | `form_families` | query | comma-separated list of string | no | | Root form types. A leading - excludes. | | `doctypes` | query | comma-separated list of string | no | | Document types; a \* suffix matches a prefix (EX-10\*). | | `ciks` | query | comma-separated list of string | no | | CIKs (1 to 10 digits each, at most 1,024). | | `tickers` | query | comma-separated list of string | no | | Tickers (at most 64); sb_search resolves them to CIKs. | | `sics` | query | comma-separated list of string | no | | SIC codes; a \* suffix matches a prefix (73\*). | | `states` | query | comma-separated list of string | no | | Business-address state codes. | | `inc_states` | query | comma-separated list of string | no | | State-of-incorporation codes. | | `filed_from` | query | date (YYYY-MM-DD) | no | | Earliest filing date, YYYY-MM-DD. | | `filed_to` | query | date (YYYY-MM-DD) | no | | Latest filing date, YYYY-MM-DD. | | `startdt` | query | date (YYYY-MM-DD) | no | | EDGAR alias of filed_from. | | `enddt` | query | date (YYYY-MM-DD) | no | | EDGAR alias of filed_to. | | `dateRange` | query | string | no | | `all` applies no lower bound and is a 400 with startdt/filed_from; `10y`, `5y`, `1y`, `30d` set filed_from relative to today and are also a 400 with startdt/filed_from; `custom` (default) uses startdt/filed_from. One of: `all`, `10y`, `5y`, `1y`, `30d`, `custom`. | | `accepted_to` | query | string | no | | Latest acceptance time: YYYY-MM-DDTHH:MM:SSZ, or a date meaning the end of that UTC day. | | `as_of` | query | string | no | | Alias of accepted_to. | | `status` | query | comma-separated list of string | no | | Filing statuses: provisional, final, deleted (SEC deleted the filing; its documents stay searchable). Default: every status, deleted filings included. | | `primary_only` | query | string | no | `auto` | Primary documents only. auto: true when q is empty, else false. One of: `true`, `false`, `auto`. | | `entityName` | query | string | no | | EDGAR entity name; becomes a name phrase filter (approximate). | | `locationCode` | query | string | no | | EDGAR state code; becomes states, or inc_states when locationType=incorporated. | | `locationType` | query | string | no | | EDGAR: located or incorporated; consumed by locationCode. | | `category` | query | string | no | | Accepted for EDGAR URL replay; ignored. | | `page` | query | string | no | | Accepted for EDGAR URL replay; ignored (use cursor). | ## Responses | Status | Body | Description | |---|---|---| | `200` | [SearchParse](https://www.secblast.com/docs/reference/schemas#schema-searchparse) (`application/json`) | OK | | `400` | [Problem](https://www.secblast.com/docs/reference/schemas#schema-problem) (`application/problem+json`) | Invalid or unknown parameter, or a query error (invalid_query, query_too_complex, prefix_too_broad, negative_only_query, unsupported_operator, invalid_cursor); query errors carry position and length (characters of q). | | `401` | [Problem](https://www.secblast.com/docs/reference/schemas#schema-problem) (`application/problem+json`) | Missing, invalid or inactive API key (code unauthorized), or a refused access token (code invalid_token: malformed, unknown key, bad signature, expired, wrong issuer or audience, revoked grant). WWW-Authenticate names the protected-resource metadata (RFC 9728). | | `503` | [Problem](https://www.secblast.com/docs/reference/schemas#schema-problem) (`application/problem+json`) | Full-text search cannot answer now: search_unavailable (sb_search unreachable or not configured), search_busy (its queue is full), search_timeout (the query hit its time budget), ticker_resolution_unavailable; or the database is unavailable. Retry after the Retry-After delay when one is given. | | `default` | [Problem](https://www.secblast.com/docs/reference/schemas#schema-problem) (`application/problem+json`) | Any other error (405, 500, 504). | ## Response body A `200` carries a [SearchParse](https://www.secblast.com/docs/reference/schemas#schema-searchparse) object. | Field | Type | Required | Description | |---|---|---|---| | `ast` | object \| null | no | The query tree under the requested syntax: sexpr and tree. | | `differs` | boolean | no | The two readings differ. | | `edgar` | object | no | The EDGAR reading: ast, echo (the query EDGAR would build) and error when it does not parse. | | `filters` | object | no | The structured filters after alias mapping and ticker resolution. | | `match` | string | no | One of: `exact`, `stem`. | | `normalized` | string | no | The normalised query. | | `prefixes` | array of object | no | | | `prefixes[].capped` | boolean | no | | | `prefixes[].expansions` | integer | no | | | `prefixes[].in_span` | boolean | no | Inside NEAR or a phrase (capped at 1,024 expansions). | | `prefixes[].prefix` | string | no | | | `prefixes[].top` | array of array of any | no | Up to 20 \[term, document frequency\] pairs. | | `resolved` | object | no | {tickers: {TICKER: \[cik, ...\]}}. | | `shards` | array of integer | no | The index years the query would search. | | `syntax` | string | no | One of: `sb`, `edgar`. | | `warnings` | array of [SearchWarning](https://www.secblast.com/docs/reference/schemas#schema-searchwarning) | no | | ## Example request ```bash curl -sS -H "Authorization: Bearer $SECBLAST_API_KEY" \ 'https://api.secblast.com/v3/search/parse' ``` [Open this route in the console](https://www.secblast.com/console#get-v3-search-parse) ## More in Full-text search Previous: [`GET /v3/search`](https://www.secblast.com/docs/reference/get-search) · Next: [`GET /v3/search/status`](https://www.secblast.com/docs/reference/get-search-status) --- # GET /v3/search/status State of the full-text index, without a key: per year the document and filing counts, index version and extractor; the live indexer's lag; indexed_through; the years being rebuilt. 503 search_unavailable when sb_search cannot be reached (or this deployment has no search). **API key:** not needed. **Group:** [Full-text search](https://www.secblast.com/docs/reference#full-text-search) ## Parameters This route takes no parameters. ## Responses | Status | Body | Description | |---|---|---| | `200` | [SearchStatus](https://www.secblast.com/docs/reference/schemas#schema-searchstatus) (`application/json`) | OK | | `503` | [Problem](https://www.secblast.com/docs/reference/schemas#schema-problem) (`application/problem+json`) | Full-text search cannot answer now: search_unavailable (sb_search unreachable or not configured), search_busy (its queue is full), search_timeout (the query hit its time budget), ticker_resolution_unavailable; or the database is unavailable. Retry after the Retry-After delay when one is given. | | `default` | [Problem](https://www.secblast.com/docs/reference/schemas#schema-problem) (`application/problem+json`) | Any other error (405, 500, 504). | ## Response body A `200` carries a [SearchStatus](https://www.secblast.com/docs/reference/schemas#schema-searchstatus) object. | Field | Type | Required | Description | |---|---|---|---| | `damaged_years` | array of integer \| null | yes | Years found damaged and dropped from the index until they are rebuilt; searches answer from the other years. | | `freshness` | object \| null | yes | Seconds from a filing's acceptance to its first searchable commit, over the last 15 minutes; null without a live indexer. | | `freshness.p50_s` | number \| null | no | | | `freshness.p95_s` | number \| null | no | | | `freshness.window` | string \| null | no | "15m". | | `indexed_through` | date-time (RFC 3339, UTC) \| null | yes | The newest event time the live index has applied. | | `indexer` | object \| null | yes | | | `indexer.indexed_through` | date-time (RFC 3339, UTC) \| null | no | | | `indexer.lag_events` | integer \| null | no | | | `indexer.lag_seconds` | number \| null | no | | | `indexer_stale` | boolean \| null | yes | True when the live indexer has not updated its status for over 120 seconds, or reports none; null when the index service does not say. | | `lag_seconds` | number \| null | yes | How far the live indexer is behind (0 when caught up). | | `partial_years` | array of integer \| null | yes | Years the live indexer started (the current or next year) that no full build has replaced yet: searchable, but they hold only the filings indexed live since; state is degraded while any exist. | | `rebuilding` | array of integer \| null | yes | Years being rebuilt. | | `state` | string \| null | yes | | | `tickers` | object \| null | yes | | | `tickers.file_date` | date (YYYY-MM-DD) \| null | no | | | `years` | array of object | yes | | | `years[].built_at` | string \| null | no | | | `years[].documents` | integer \| null | no | | | `years[].extractor` | string \| null | no | | | `years[].filings` | integer \| null | no | | | `years[].index_version` | string \| null | no | | | `years[].year` | integer | no | | | `years_missing` | array of integer \| null | yes | Years not searchable now: listed years that cannot be opened, and damaged_years. | ## Example request ```bash curl -sS 'https://api.secblast.com/v3/search/status' ``` [Open this route in the console](https://www.secblast.com/console#get-v3-search-status) ## More in Full-text search Previous: [`GET /v3/search/parse`](https://www.secblast.com/docs/reference/get-search-parse) --- # GET /v3/filings/{accession}/sections The sections of a 10-K, 10-Q or 20-F: one row per item in force with its key (10k.1a, 10q.p1i2, 20f.3d), status (ok, incorporated_by_reference, combined_with, omitted, reserved, not_found), why an absent item is absent, spans and rule confidence; the amendment scope. 404 not_covered for another form. With section maps: for S-4, S-4/A, F-4, F-4/A, DEFM14A, PREM14A, DEFM14C and DEF 14A, the document's section map (schema SectionMapOfFiling): its table of contents as a two-level outline in document order. Top-level sections carry their key (summary, risk_factors, background_of_the_merger, the_merger_agreement, executive_compensation, pay_versus_performance, proposal_1, proposal_2, ...) or unmapped_\ with the heading as filed, toc_text, spans, signals and confidence; each runs to the next keyed heading or the next heading at its depth, and the unmapped sub-headings inside it are its subsections. proposal_\ rows carry proposal_title (the heading without its number). **API key:** required. See [Authentication](https://www.secblast.com/docs/authentication). **Group:** [Sections of 10-K, 10-Q and 20-F](https://www.secblast.com/docs/reference#sections-of-10-k-10-q-and-20-f) ## Parameters | Name | In | Type | Required | Default | Description | |---|---|---|---|---|---| | `accession` | path | string | yes | | Accession number, with dashes (0001829126-26-010431) or without (18 digits). | ## Responses | Status | Body | Description | |---|---|---| | `200` | [SectionsOfFiling](https://www.secblast.com/docs/reference/schemas#schema-sectionsoffiling) (`application/json`) | OK | | `400` | [Problem](https://www.secblast.com/docs/reference/schemas#schema-problem) (`application/problem+json`) | Invalid or unknown parameter. | | `401` | [Problem](https://www.secblast.com/docs/reference/schemas#schema-problem) (`application/problem+json`) | Missing, invalid or inactive API key (code unauthorized), or a refused access token (code invalid_token: malformed, unknown key, bad signature, expired, wrong issuer or audience, revoked grant). WWW-Authenticate names the protected-resource metadata (RFC 9728). | | `404` | [Problem](https://www.secblast.com/docs/reference/schemas#schema-problem) (`application/problem+json`) | No filing with this accession (code not_found); the filing's form is not covered by this route's dataset (code not_covered, with members form_type, dataset and routes: the routes that cover it); for a text route, no such item or section in the parsed filing (code not_found). | | `503` | [Problem](https://www.secblast.com/docs/reference/schemas#schema-problem) (`application/problem+json`) | Database unavailable; retry after the Retry-After delay. | | `default` | [Problem](https://www.secblast.com/docs/reference/schemas#schema-problem) (`application/problem+json`) | Any other error (405, 500, 504). | ## Response body A `200` carries a [SectionsOfFiling](https://www.secblast.com/docs/reference/schemas#schema-sectionsoffiling) object. | Field | Type | Required | Description | |---|---|---|---| | `accession` | string | no | | | `document` | object \| null | no | | | `extraction` | [Extraction](https://www.secblast.com/docs/reference/schemas#schema-extraction) | no | | | `filing` | [FilingRef](https://www.secblast.com/docs/reference/schemas#schema-filingref) | no | | | `financial_statements` | object \| null | no | | | `form` | string \| null | no | | | `scope` | [SectionScope](https://www.secblast.com/docs/reference/schemas#schema-sectionscope) | no | | | `sections` | array of [Section](https://www.secblast.com/docs/reference/schemas#schema-section) | no | | | `snapshot` | [Snapshot](https://www.secblast.com/docs/reference/schemas#schema-snapshot) | no | | | `versions` | string | no | | ## Example request ```bash curl -sS -H "Authorization: Bearer $SECBLAST_API_KEY" \ 'https://api.secblast.com/v3/filings/0001829126-26-010431/sections' ``` [Open this route in the console](https://www.secblast.com/console#get-v3-filings-accession-sections) ## More in Sections of 10-K, 10-Q and 20-F Next: [`GET /v3/filings/{accession}/sections/{section}/text`](https://www.secblast.com/docs/reference/get-filings-accession-sections-section-text) --- # GET /v3/filings/{accession}/sections/{section}/text One section's canonical text, under the same serving rule, paging, ETag, cache and time limit as an 8-K item's text. With section maps: {section} may be a section map key of a merger document or proxy statement (risk_factors, proposal_2, unmapped_7). **API key:** required. See [Authentication](https://www.secblast.com/docs/authentication). **Group:** [Sections of 10-K, 10-Q and 20-F](https://www.secblast.com/docs/reference#sections-of-10-k-10-q-and-20-f) ## Parameters | Name | In | Type | Required | Default | Description | |---|---|---|---|---|---| | `accession` | path | string | yes | | Accession number, with dashes (0001829126-26-010431) or without (18 digits). | | `section` | path | string | yes | | A section key, e.g. 10k.1a, 10q.p1i2, 20f.3d. | | `offset` | query | integer | no | `0` | Byte offset in the section's text, 0..text_total_bytes. | | `length` | query | integer | no | `4194304` | Bytes per page, 1..4194304. | ## Responses | Status | Body | Description | |---|---|---| | `200` | [SpanText](https://www.secblast.com/docs/reference/schemas#schema-spantext) (`application/json`) | OK | | `304` | none | Not modified: If-None-Match named this page's ETag (answered before the document is read). | | `400` | [Problem](https://www.secblast.com/docs/reference/schemas#schema-problem) (`application/problem+json`) | Invalid or unknown parameter. | | `401` | [Problem](https://www.secblast.com/docs/reference/schemas#schema-problem) (`application/problem+json`) | Missing, invalid or inactive API key (code unauthorized), or a refused access token (code invalid_token: malformed, unknown key, bad signature, expired, wrong issuer or audience, revoked grant). WWW-Authenticate names the protected-resource metadata (RFC 9728). | | `404` | [Problem](https://www.secblast.com/docs/reference/schemas#schema-problem) (`application/problem+json`) | No filing with this accession (code not_found); the filing's form is not covered by this route's dataset (code not_covered, with members form_type, dataset and routes: the routes that cover it); for a text route, no such item or section in the parsed filing (code not_found). | | `422` | [Problem](https://www.secblast.com/docs/reference/schemas#schema-problem) (`application/problem+json`) | The stored document is larger than this server converts to text (code document_too_large, with members document_bytes, limit and document: the document's URL, whose span_start..span_end Range holds the filed bytes of the passage). Nothing was read. | | `503` | [Problem](https://www.secblast.com/docs/reference/schemas#schema-problem) (`application/problem+json`) | Database unavailable (code db_unavailable); or the document's conversion to text did not finish within the request's time (code conversion_timeout, with Retry-After): it goes on, and the same request after the delay is answered from the converted text. | | `504` | [Problem](https://www.secblast.com/docs/reference/schemas#schema-problem) (`application/problem+json`) | The request's time ran out (code timeout), e.g. while it waited for the server's conversion budget; nothing was converted for it. | | `default` | [Problem](https://www.secblast.com/docs/reference/schemas#schema-problem) (`application/problem+json`) | Any other error (405, 500, 504). | ## Response body A `200` carries a [SpanText](https://www.secblast.com/docs/reference/schemas#schema-spantext) object. | Field | Type | Required | Description | |---|---|---|---| | `accession` | string | no | | | `docmodel_version` | string \| null | no | | | `document` | object \| null | no | | | `extraction` | [Extraction](https://www.secblast.com/docs/reference/schemas#schema-extraction) | no | | | `next_offset` | integer \| null | no | | | `section` | string | no | | | `served_model_version` | string | no | | | `text` | string \| null | no | | | `text_bytes` | integer \| null | no | | | `text_offset` | integer \| null | no | | | `text_reason` | string \| null | no | One of: `model_changed`, `bytes_unavailable`, `null`. | | `text_status` | string | no | One of: `current`, `from_version`, `reparse_pending`, `no_text`, `parse_pending`. | | `text_total_bytes` | integer \| null | no | | | `text_truncated` | boolean | no | | ## Example request ```bash curl -sS -H "Authorization: Bearer $SECBLAST_API_KEY" \ 'https://api.secblast.com/v3/filings/0001829126-26-010431/sections/10k.1a/text' ``` [Open this route in the console](https://www.secblast.com/console#get-v3-filings-accession-sections-section-text) ## More in Sections of 10-K, 10-Q and 20-F Previous: [`GET /v3/filings/{accession}/sections`](https://www.secblast.com/docs/reference/get-filings-accession-sections) · Next: [`GET /v3/sections`](https://www.secblast.com/docs/reference/get-sections) --- # GET /v3/sections One section across filings, newest first (by filing date, then accession). Default statuses: the placed ones (ok, incorporated_by_reference, combined_with, reserved); omitted and not_found when asked for. absence_basis, target_kind, amendments, min_confidence and flag need cik or filed_from and filed_to at most 366 days apart. as_of: only filings SEC had accepted by then (inclusive; a date is the whole UTC day). With section maps: section (or key) may be a section map key (background_of_the_merger, executive_compensation, pay_versus_performance, proposal_2, ...): that key across merger documents and proxy statements, newest first, filtered by filed_from/from, filed_to/to and cik; limit 1..1000, default 500. **API key:** required. See [Authentication](https://www.secblast.com/docs/authentication). **Group:** [Sections of 10-K, 10-Q and 20-F](https://www.secblast.com/docs/reference#sections-of-10-k-10-q-and-20-f) ## Parameters | Name | In | Type | Required | Default | Description | |---|---|---|---|---|---| | `section` | query | string | no | | A section key, e.g. 10k.1a, 10q.p1i2, 20f.3d. Required. With section maps: or a section map key (executive_compensation, proposal_2). | | `status` | query | comma-separated list of string | no | | ok, incorporated_by_reference, combined_with, omitted, reserved, not_found. | | `absence_basis` | query | comma-separated list of string | no | | none, form_optional, bracketed, amendment_scope. | | `target_kind` | query | comma-separated list of string | no | | proxy_statement, exhibit, annual_report, other_filing, unknown; only with status=incorporated_by_reference. | | `filed_from` | query | date (YYYY-MM-DD) | no | | filing_date \>= this date (inclusive). | | `filed_to` | query | date (YYYY-MM-DD) | no | | filing_date \<= this date (inclusive). | | `amendments` | query | string | no | `include` | Whether to include amendments. One of: `include`, `exclude`, `only`. | | `filing_status` | query | comma-separated list of string | no | | Status(es) of the rows' filings (named apart: status is the section's): provisional, final, deleted, comma-separated (as status of GET /v3/filings). Default: every status, deleted (SEC-withdrawn) filings included; filing_status=final,provisional leaves them out. | | `cik` | query | string | no | | The filing's primary CIK, padded or unpadded. | | `min_confidence` | query | string | no | | Rule confidence at least this, a number from 0 to 1. | | `flag` | query | comma-separated list of string | no | | Rows carrying any of these section flags. | | `as_of` | query | string | no | | Inclusive: YYYY-MM-DDTHH:MM:SSZ (UTC, through the end of that second), YYYY-MM-DDTHH:MM:SS.ffffffZ (exact, 1-6 fraction digits) or YYYY-MM-DD (the whole UTC day). | | `order` | query | string | no | `desc` | By filing date. One of: `desc`, `asc`. | | `limit` | query | integer | no | `50` | Page size, 1..1000. | | `cursor` | query | string | no | | Opaque cursor from a previous page's next_cursor; bound to the filters and order. | | `key` | query | string | no | | With section maps: a section map key, the same as section (summary, background_of_the_merger, executive_compensation, pay_versus_performance, proposal_\, ...). | | `from` | query | date (YYYY-MM-DD) | no | | With a section map key: the same as filed_from. | | `to` | query | date (YYYY-MM-DD) | no | | With a section map key: the same as filed_to. | ## Responses | Status | Body | Description | |---|---|---| | `200` | [SectionSearchList](https://www.secblast.com/docs/reference/schemas#schema-sectionsearchlist) (`application/json`) | OK | | `400` | [Problem](https://www.secblast.com/docs/reference/schemas#schema-problem) (`application/problem+json`) | Invalid or unknown parameter. | | `401` | [Problem](https://www.secblast.com/docs/reference/schemas#schema-problem) (`application/problem+json`) | Missing, invalid or inactive API key (code unauthorized), or a refused access token (code invalid_token: malformed, unknown key, bad signature, expired, wrong issuer or audience, revoked grant). WWW-Authenticate names the protected-resource metadata (RFC 9728). | | `503` | [Problem](https://www.secblast.com/docs/reference/schemas#schema-problem) (`application/problem+json`) | Database unavailable; retry after the Retry-After delay. | | `default` | [Problem](https://www.secblast.com/docs/reference/schemas#schema-problem) (`application/problem+json`) | Any other error (405, 500, 504). | ## Response body A `200` carries a [SectionSearchList](https://www.secblast.com/docs/reference/schemas#schema-sectionsearchlist) object. | Field | Type | Required | Description | |---|---|---|---| | `as_of` | string \| null | no | | | `data` | array of object | no | | | `data[].filing` | [FilingRef](https://www.secblast.com/docs/reference/schemas#schema-filingref) | no | | | `data[].form` | string | no | | | `data[].links` | object | no | | | `data[].scope_kind` | string | no | | | `data[].section` | [Section](https://www.secblast.com/docs/reference/schemas#schema-section) | no | | | `form` | string | no | | | `has_more` | boolean | no | | | `next_cursor` | string \| null | no | | | `section` | string | no | | | `snapshot` | [Snapshot](https://www.secblast.com/docs/reference/schemas#schema-snapshot) | no | | ## Example request ```bash curl -sS -H "Authorization: Bearer $SECBLAST_API_KEY" \ 'https://api.secblast.com/v3/sections' ``` [Open this route in the console](https://www.secblast.com/console#get-v3-sections) ## More in Sections of 10-K, 10-Q and 20-F Previous: [`GET /v3/filings/{accession}/sections/{section}/text`](https://www.secblast.com/docs/reference/get-filings-accession-sections-section-text) --- # GET /v3/filings/{accession}/parsed Which parsed datasets apply to the filing (13f, 8k_items, sections) and the state of each: status (ok, ok_with_warnings, partial, unparseable, not_applicable; pending, failed or not_parsed while there is no result), the extractor version that last verified the filing and the deployed one, a re-parse in progress, warnings (at most 100), the documents read, the dataset's derive steps for the filing, and a link to the dataset's route for the filing (null while this server does not answer it). Empty data when no dataset covers the form. A parser failure is never a 5xx. Measured accuracy is not published. A filing SEC deleted (withdrew) is served like any other on every /v3/filings/{accession}/... parsed route: its parsed rows are kept and its filing block says status deleted, deleted_at and deletion (as GET /v3/filings/{accession}). **API key:** required. See [Authentication](https://www.secblast.com/docs/authentication). **Group:** [Parsed data and tables](https://www.secblast.com/docs/reference#parsed-data-and-tables) ## Parameters | Name | In | Type | Required | Default | Description | |---|---|---|---|---|---| | `accession` | path | string | yes | | Accession number, with dashes (0001829126-26-010431) or without (18 digits). | | `dataset` | query | comma-separated list of string | no | | Only these datasets of the deployed parser (13f, 8k_items, sections); an unknown name is a 400. | ## Responses | Status | Body | Description | |---|---|---| | `200` | [ParsedList](https://www.secblast.com/docs/reference/schemas#schema-parsedlist) (`application/json`) | OK | | `400` | [Problem](https://www.secblast.com/docs/reference/schemas#schema-problem) (`application/problem+json`) | Invalid or unknown parameter. | | `401` | [Problem](https://www.secblast.com/docs/reference/schemas#schema-problem) (`application/problem+json`) | Missing, invalid or inactive API key (code unauthorized), or a refused access token (code invalid_token: malformed, unknown key, bad signature, expired, wrong issuer or audience, revoked grant). WWW-Authenticate names the protected-resource metadata (RFC 9728). | | `404` | [Problem](https://www.secblast.com/docs/reference/schemas#schema-problem) (`application/problem+json`) | Not found. | | `503` | [Problem](https://www.secblast.com/docs/reference/schemas#schema-problem) (`application/problem+json`) | Database unavailable; retry after the Retry-After delay. | | `default` | [Problem](https://www.secblast.com/docs/reference/schemas#schema-problem) (`application/problem+json`) | Any other error (405, 500, 504). | ## Response body A `200` carries a [ParsedList](https://www.secblast.com/docs/reference/schemas#schema-parsedlist) object. | Field | Type | Required | Description | |---|---|---|---| | `accession` | string | yes | | | `data` | array of [ParsedItem](https://www.secblast.com/docs/reference/schemas#schema-parseditem) | yes | One per extractor that covers the filing's form type; empty when none does. | | `filing` | [FilingRef](https://www.secblast.com/docs/reference/schemas#schema-filingref) | yes | | | `has_more` | boolean | yes | | | `next_cursor` | string \| null | yes | | | `snapshot` | [Snapshot](https://www.secblast.com/docs/reference/schemas#schema-snapshot) | yes | | ## Example request ```bash curl -sS -H "Authorization: Bearer $SECBLAST_API_KEY" \ 'https://api.secblast.com/v3/filings/0001829126-26-010431/parsed' ``` [Open this route in the console](https://www.secblast.com/console#get-v3-filings-accession-parsed) ## More in Parsed data and tables Next: [`GET /v3/filings/{accession}/parsed/changes`](https://www.secblast.com/docs/reference/get-filings-accession-parsed-changes) --- # GET /v3/filings/{accession}/parsed/changes Every earlier version of the filing's parsed data that is kept, newest first: each row of a dataset table a re-parse changed or removed (kind superseded: table, row key, from and to version, reason changed / removed / withdrawn, the old row), each group of rows rebuilt or replaced as a whole (kind replaced: the 13F ledger and manager-period rows, the filing's warning set and result row; the old rows) and each 13F unit decision (kind unit_decision). Numbers inside old rows are strings holding the stored value. extractor limits the list to that extractor's superseded rows. **API key:** required. See [Authentication](https://www.secblast.com/docs/authentication). **Group:** [Parsed data and tables](https://www.secblast.com/docs/reference#parsed-data-and-tables) ## Parameters | Name | In | Type | Required | Default | Description | |---|---|---|---|---|---| | `accession` | path | string | yes | | Accession number, with dashes (0001829126-26-010431) or without (18 digits). | | `extractor` | query | string | no | | Only the superseded rows of this extractor (f13f, items_8k, sections, ...). | | `limit` | query | integer | no | `100` | Page size, 1..500. | | `cursor` | query | string | no | | Opaque cursor from a previous page's next_cursor. | ## Responses | Status | Body | Description | |---|---|---| | `200` | [ParsedChanges](https://www.secblast.com/docs/reference/schemas#schema-parsedchanges) (`application/json`) | OK | | `400` | [Problem](https://www.secblast.com/docs/reference/schemas#schema-problem) (`application/problem+json`) | Invalid or unknown parameter. | | `401` | [Problem](https://www.secblast.com/docs/reference/schemas#schema-problem) (`application/problem+json`) | Missing, invalid or inactive API key (code unauthorized), or a refused access token (code invalid_token: malformed, unknown key, bad signature, expired, wrong issuer or audience, revoked grant). WWW-Authenticate names the protected-resource metadata (RFC 9728). | | `404` | [Problem](https://www.secblast.com/docs/reference/schemas#schema-problem) (`application/problem+json`) | Not found. | | `503` | [Problem](https://www.secblast.com/docs/reference/schemas#schema-problem) (`application/problem+json`) | Database unavailable; retry after the Retry-After delay. | | `default` | [Problem](https://www.secblast.com/docs/reference/schemas#schema-problem) (`application/problem+json`) | Any other error (405, 500, 504). | ## Response body A `200` carries a [ParsedChanges](https://www.secblast.com/docs/reference/schemas#schema-parsedchanges) object. | Field | Type | Required | Description | |---|---|---|---| | `accession` | string | yes | | | `data` | array of [ParsedChange](https://www.secblast.com/docs/reference/schemas#schema-parsedchange) | yes | | | `filing` | [FilingRef](https://www.secblast.com/docs/reference/schemas#schema-filingref) | yes | | | `has_more` | boolean | yes | | | `next_cursor` | string \| null | yes | | ## Example request ```bash curl -sS -H "Authorization: Bearer $SECBLAST_API_KEY" \ 'https://api.secblast.com/v3/filings/0001829126-26-010431/parsed/changes' ``` [Open this route in the console](https://www.secblast.com/console#get-v3-filings-accession-parsed-changes) ## More in Parsed data and tables Previous: [`GET /v3/filings/{accession}/parsed`](https://www.secblast.com/docs/reference/get-filings-accession-parsed) · Next: [`GET /v3/filings/{accession}/tables`](https://www.secblast.com/docs/reference/get-filings-accession-tables) --- # GET /v3/filings/{accession}/tables The tables of a 10-K, 10-Q or 20-F primary document. Without block: each table's outline in document order (data or layout and why, rows and columns, header rows, column headers, the unit scale the table states and where it was read, caption, page, spans). With block=b\: that table with its cells recomputed from the stored document: each cell's text as filed beside its number as displayed (value, negative, dash, percent, currency, footnote markers) and the scale that applies to it. cells_status current, from_version or reparse_pending (cells_reason model_changed or bytes_unavailable). 404 not_covered for another form, or while the parser does not run doc_tables. **API key:** required. See [Authentication](https://www.secblast.com/docs/authentication). **Group:** [Parsed data and tables](https://www.secblast.com/docs/reference#parsed-data-and-tables) ## Parameters | Name | In | Type | Required | Default | Description | |---|---|---|---|---|---| | `accession` | path | string | yes | | Accession number, with dashes (0001829126-26-010431) or without (18 digits). | | `block` | query | string | no | | One table by its block id (b17): its outline and its cells. | | `kind` | query | string | no | `all` | Only data or only layout tables (list only). One of: `data`, `layout`, `all`. | | `limit` | query | integer | no | `100` | Page size, 1..1000. | | `cursor` | query | string | no | | Opaque cursor from a previous page's next_cursor. | ## Responses | Status | Body | Description | |---|---|---| | `200` | [DocTables](https://www.secblast.com/docs/reference/schemas#schema-doctables) (`application/json`) | OK | | `400` | [Problem](https://www.secblast.com/docs/reference/schemas#schema-problem) (`application/problem+json`) | Invalid or unknown parameter. | | `401` | [Problem](https://www.secblast.com/docs/reference/schemas#schema-problem) (`application/problem+json`) | Missing, invalid or inactive API key (code unauthorized), or a refused access token (code invalid_token: malformed, unknown key, bad signature, expired, wrong issuer or audience, revoked grant). WWW-Authenticate names the protected-resource metadata (RFC 9728). | | `404` | [Problem](https://www.secblast.com/docs/reference/schemas#schema-problem) (`application/problem+json`) | Not found. | | `422` | [Problem](https://www.secblast.com/docs/reference/schemas#schema-problem) (`application/problem+json`) | The table's stored document is larger than this server converts (code document_too_large, with members document_bytes and limit). Nothing was read. | | `503` | [Problem](https://www.secblast.com/docs/reference/schemas#schema-problem) (`application/problem+json`) | Database unavailable; retry after the Retry-After delay. | | `504` | [Problem](https://www.secblast.com/docs/reference/schemas#schema-problem) (`application/problem+json`) | The request's time ran out (code timeout) while it waited for the server's conversion budget; nothing was converted for it. | | `default` | [Problem](https://www.secblast.com/docs/reference/schemas#schema-problem) (`application/problem+json`) | Any other error (405, 500, 504). | ## Response body A `200` carries a [DocTables](https://www.secblast.com/docs/reference/schemas#schema-doctables) object. | Field | Type | Required | Description | |---|---|---|---| | `accession` | string | no | | | `cells` | array of [DocTableCell](https://www.secblast.com/docs/reference/schemas#schema-doctablecell) \| null | no | | | `cells_reason` | string \| null | no | One of: `model_changed`, `bytes_unavailable`, `rules_changed`, `null`. | | `cells_status` | string | no | One of: `current`, `from_version`, `reparse_pending`. | | `data` | array of [DocTableOutline](https://www.secblast.com/docs/reference/schemas#schema-doctableoutline) | no | | | `document` | object \| null | no | | | `extraction` | object | no | | | `filing` | [FilingRef](https://www.secblast.com/docs/reference/schemas#schema-filingref) | no | | | `has_more` | boolean | no | | | `next_cursor` | string \| null | no | | | `rules_version` | string | no | | | `table` | [DocTableOutline](https://www.secblast.com/docs/reference/schemas#schema-doctableoutline) | no | | ## Example request ```bash curl -sS -H "Authorization: Bearer $SECBLAST_API_KEY" \ 'https://api.secblast.com/v3/filings/0001829126-26-010431/tables' ``` [Open this route in the console](https://www.secblast.com/console#get-v3-filings-accession-tables) ## More in Parsed data and tables Previous: [`GET /v3/filings/{accession}/parsed/changes`](https://www.secblast.com/docs/reference/get-filings-accession-parsed-changes) --- # GET /v3/events/8k/{item} One 8-K item's structured events across filings, newest first (by filing date, then accession): one row per filing with its events of that item, each a list of fields {value, value_as_found, span, rule_id, rule confidence} read from the item's text; exhibit numbers joined to the filing's documents by type. Only items whose rules passed the release gate are produced (others: 404 not_covered). Deleted (SEC-withdrawn) filings are listed, marked deleted, unless status leaves them out. event_type, min_confidence and a status set without final need cik or filed_from and filed_to at most 366 days apart. as_of: only filings SEC had accepted by then (inclusive; a date is the whole UTC day). **API key:** required. See [Authentication](https://www.secblast.com/docs/authentication). **Group:** [8-K items](https://www.secblast.com/docs/reference#8-k-items) ## Parameters | Name | In | Type | Required | Default | Description | |---|---|---|---|---|---| | `item` | path | string | yes | | An 8-K item code with structured events: 2.02 and 4.01 (produced); 4.02, 5.02, 5.07 (built, not produced). | | `filed_from` | query | date (YYYY-MM-DD) | no | | filing_date \>= this date (inclusive). | | `filed_to` | query | date (YYYY-MM-DD) | no | | filing_date \<= this date (inclusive). | | `cik` | query | string | no | | The filing's primary CIK, padded or unpadded. | | `event_type` | query | comma-separated list of string | no | | Filings with an event of any of these types (earnings_release, results_disclosure, ...). | | `min_confidence` | query | string | no | | The first event's rule confidence at least this, a number from 0 to 1. | | `status` | query | comma-separated list of string | no | | Status(es) of the rows' filings: provisional, final, deleted, comma-separated (as GET /v3/filings). Default: every status, deleted (SEC-withdrawn) filings included, each row's filing status saying so; status=final,provisional leaves deleted filings out. | | `as_of` | query | string | no | | Inclusive: YYYY-MM-DDTHH:MM:SSZ (UTC, through the end of that second), YYYY-MM-DDTHH:MM:SS.ffffffZ (exact, 1-6 fraction digits) or YYYY-MM-DD (the whole UTC day). | | `order` | query | string | no | `desc` | By filing date. One of: `desc`, `asc`. | | `limit` | query | integer | no | `50` | Page size, 1..500. | | `cursor` | query | string | no | | Opaque cursor from a previous page's next_cursor; bound to the filters (as_of included). | ## Responses | Status | Body | Description | |---|---|---| | `200` | [EightKEventList](https://www.secblast.com/docs/reference/schemas#schema-eightkeventlist) (`application/json`) | OK | | `400` | [Problem](https://www.secblast.com/docs/reference/schemas#schema-problem) (`application/problem+json`) | Invalid or unknown parameter. | | `401` | [Problem](https://www.secblast.com/docs/reference/schemas#schema-problem) (`application/problem+json`) | Missing, invalid or inactive API key (code unauthorized), or a refused access token (code invalid_token: malformed, unknown key, bad signature, expired, wrong issuer or audience, revoked grant). WWW-Authenticate names the protected-resource metadata (RFC 9728). | | `404` | [Problem](https://www.secblast.com/docs/reference/schemas#schema-problem) (`application/problem+json`) | Not found. | | `503` | [Problem](https://www.secblast.com/docs/reference/schemas#schema-problem) (`application/problem+json`) | Database unavailable; retry after the Retry-After delay. | | `default` | [Problem](https://www.secblast.com/docs/reference/schemas#schema-problem) (`application/problem+json`) | Any other error (405, 500, 504). | ## Response body A `200` carries a [EightKEventList](https://www.secblast.com/docs/reference/schemas#schema-eightkeventlist) object. | Field | Type | Required | Description | |---|---|---|---| | `accuracy` | object | no | Items 1.01 and 2.01 only (served with a field list): served_fields_version, served_fields, event_type_served, holdout, holdout_filings, and per served field (and event_type when served) precision, recall, tp, fp, fn, n on the item's holdout (static). 1.01 serves event_type, cash_per_share, exchange_ratio, price_per_share; 2.01 serves cash_per_share, exchange_ratio, price_per_share, closing_date, with event_type transaction_completed. | | `as_of` | string \| null | no | | | `data` | array of object | no | | | `data[].events` | array of [EightKEvent](https://www.secblast.com/docs/reference/schemas#schema-eightkevent) | no | | | `data[].filing` | [FilingRef](https://www.secblast.com/docs/reference/schemas#schema-filingref) | no | | | `data[].item_code` | string | no | | | `data[].links` | object | no | | | `has_more` | boolean | no | | | `item` | string | no | | | `next_cursor` | string \| null | no | | | `snapshot` | object | no | | ## Example request ```bash curl -sS -H "Authorization: Bearer $SECBLAST_API_KEY" \ 'https://api.secblast.com/v3/events/8k/2.02' ``` [Open this route in the console](https://www.secblast.com/console#get-v3-events-8k-item) ## More in 8-K items Next: [`GET /v3/events/items`](https://www.secblast.com/docs/reference/get-events-items) --- # GET /v3/events/items One 8-K item across filings, newest first (by filing date, then accession): the parsed union of header and body items, with which side named it. source, body_status, mismatch_kind, form_type, amendments, min_confidence and flag need cik or filed_from and filed_to at most 366 days apart. as_of: only filings SEC had accepted by then (inclusive; a date is the whole UTC day). min_confidence is refused when the server does not serve rule confidence. **API key:** required. See [Authentication](https://www.secblast.com/docs/authentication). **Group:** [8-K items](https://www.secblast.com/docs/reference#8-k-items) ## Parameters | Name | In | Type | Required | Default | Description | |---|---|---|---|---|---| | `item` | query | string | yes | | An 8-K item code, e.g. 2.02. Required. | | `filed_from` | query | date (YYYY-MM-DD) | no | | filing_date \>= this date (inclusive). | | `filed_to` | query | date (YYYY-MM-DD) | no | | filing_date \<= this date (inclusive). | | `source` | query | comma-separated list of string | no | | header, body, both. | | `body_status` | query | comma-separated list of string | no | | heading, combined_heading, not_applicable, not_found. | | `mismatch_kind` | query | comma-separated list of string | no | | none, header_omits_901, differs. | | `form_type` | query | comma-separated list of string | no | | Exact form types, e.g. 8-K/A. | | `amendments` | query | string | no | `include` | Whether to include amendments. One of: `include`, `exclude`, `only`. | | `status` | query | comma-separated list of string | no | | Status(es) of the rows' filings: provisional, final, deleted, comma-separated (as GET /v3/filings). Default: every status, deleted (SEC-withdrawn) filings included, each row's filing status saying so; status=final,provisional leaves deleted filings out. | | `cik` | query | string | no | | The filing's primary CIK, padded or unpadded. | | `min_confidence` | query | string | no | | Rule confidence at least this, a number from 0 to 1. | | `flag` | query | comma-separated list of string | no | | Rows carrying any of these item flags. | | `as_of` | query | string | no | | Inclusive: YYYY-MM-DDTHH:MM:SSZ (UTC, through the end of that second), YYYY-MM-DDTHH:MM:SS.ffffffZ (exact, 1-6 fraction digits) or YYYY-MM-DD (the whole UTC day). | | `order` | query | string | no | `desc` | By filing date. One of: `desc`, `asc`. | | `limit` | query | integer | no | `50` | Page size, 1..1000. | | `cursor` | query | string | no | | Opaque cursor from a previous page's next_cursor; bound to the filters and order. | ## Responses | Status | Body | Description | |---|---|---| | `200` | [EightKItemSearchList](https://www.secblast.com/docs/reference/schemas#schema-eightkitemsearchlist) (`application/json`) | OK | | `400` | [Problem](https://www.secblast.com/docs/reference/schemas#schema-problem) (`application/problem+json`) | Invalid or unknown parameter. | | `401` | [Problem](https://www.secblast.com/docs/reference/schemas#schema-problem) (`application/problem+json`) | Missing, invalid or inactive API key (code unauthorized), or a refused access token (code invalid_token: malformed, unknown key, bad signature, expired, wrong issuer or audience, revoked grant). WWW-Authenticate names the protected-resource metadata (RFC 9728). | | `503` | [Problem](https://www.secblast.com/docs/reference/schemas#schema-problem) (`application/problem+json`) | Database unavailable; retry after the Retry-After delay. | | `default` | [Problem](https://www.secblast.com/docs/reference/schemas#schema-problem) (`application/problem+json`) | Any other error (405, 500, 504). | ## Response body A `200` carries a [EightKItemSearchList](https://www.secblast.com/docs/reference/schemas#schema-eightkitemsearchlist) object. | Field | Type | Required | Description | |---|---|---|---| | `as_of` | string \| null | no | | | `data` | array of object | no | | | `data[].filing` | [FilingRef](https://www.secblast.com/docs/reference/schemas#schema-filingref) | no | | | `data[].item` | [EightKItem](https://www.secblast.com/docs/reference/schemas#schema-eightkitem) | no | | | `data[].links` | object | no | | | `data[].mismatch_kind` | string | no | | | `has_more` | boolean | no | | | `item` | string | no | | | `next_cursor` | string \| null | no | | | `snapshot` | [Snapshot](https://www.secblast.com/docs/reference/schemas#schema-snapshot) | no | | ## Example request ```bash curl -sS -H "Authorization: Bearer $SECBLAST_API_KEY" \ 'https://api.secblast.com/v3/events/items?item=2.02' ``` [Open this route in the console](https://www.secblast.com/console#get-v3-events-items) ## More in 8-K items Previous: [`GET /v3/events/8k/{item}`](https://www.secblast.com/docs/reference/get-events-8k-item) · Next: [`GET /v3/filings/{accession}/items`](https://www.secblast.com/docs/reference/get-filings-accession-items) --- # GET /v3/filings/{accession}/items An 8-K's item sets (the header's, the body's, their union), how they differ, one row per item (source, heading status, spans in the primary document, rule confidence) and the Item 9.01 exhibit rows. 404 not_covered for a form that is not an 8-K. **API key:** required. See [Authentication](https://www.secblast.com/docs/authentication). **Group:** [8-K items](https://www.secblast.com/docs/reference#8-k-items) ## Parameters | Name | In | Type | Required | Default | Description | |---|---|---|---|---|---| | `accession` | path | string | yes | | Accession number, with dashes (0001829126-26-010431) or without (18 digits). | ## Responses | Status | Body | Description | |---|---|---| | `200` | [EightKFiling](https://www.secblast.com/docs/reference/schemas#schema-eightkfiling) (`application/json`) | OK | | `400` | [Problem](https://www.secblast.com/docs/reference/schemas#schema-problem) (`application/problem+json`) | Invalid or unknown parameter. | | `401` | [Problem](https://www.secblast.com/docs/reference/schemas#schema-problem) (`application/problem+json`) | Missing, invalid or inactive API key (code unauthorized), or a refused access token (code invalid_token: malformed, unknown key, bad signature, expired, wrong issuer or audience, revoked grant). WWW-Authenticate names the protected-resource metadata (RFC 9728). | | `404` | [Problem](https://www.secblast.com/docs/reference/schemas#schema-problem) (`application/problem+json`) | No filing with this accession (code not_found); the filing's form is not covered by this route's dataset (code not_covered, with members form_type, dataset and routes: the routes that cover it); for a text route, no such item or section in the parsed filing (code not_found). | | `503` | [Problem](https://www.secblast.com/docs/reference/schemas#schema-problem) (`application/problem+json`) | Database unavailable; retry after the Retry-After delay. | | `default` | [Problem](https://www.secblast.com/docs/reference/schemas#schema-problem) (`application/problem+json`) | Any other error (405, 500, 504). | ## Response body A `200` carries a [EightKFiling](https://www.secblast.com/docs/reference/schemas#schema-eightkfiling) object. | Field | Type | Required | Description | |---|---|---|---| | `accession` | string | no | | | `document` | object \| null | no | | | `exhibits` | array of [EightKExhibit](https://www.secblast.com/docs/reference/schemas#schema-eightkexhibit) | no | | | `extraction` | [Extraction](https://www.secblast.com/docs/reference/schemas#schema-extraction) | no | | | `filing` | [FilingRef](https://www.secblast.com/docs/reference/schemas#schema-filingref) | no | | | `header_body_agree` | boolean \| null | no | | | `item_sets` | object \| null | no | | | `item_sets.body` | array of any | no | | | `item_sets.header` | array of any | no | | | `item_sets.union` | array of any | no | | | `items` | array of [EightKItem](https://www.secblast.com/docs/reference/schemas#schema-eightkitem) | no | | | `links` | object | no | | | `mismatch_kind` | string \| null | no | One of: `none`, `header_omits_901`, `differs`, `null`. | | `snapshot` | [Snapshot](https://www.secblast.com/docs/reference/schemas#schema-snapshot) | no | | ## Example request ```bash curl -sS -H "Authorization: Bearer $SECBLAST_API_KEY" \ 'https://api.secblast.com/v3/filings/0001829126-26-010431/items' ``` [Open this route in the console](https://www.secblast.com/console#get-v3-filings-accession-items) ## More in 8-K items Previous: [`GET /v3/events/items`](https://www.secblast.com/docs/reference/get-events-items) · Next: [`GET /v3/filings/{accession}/items/{code}/text`](https://www.secblast.com/docs/reference/get-filings-accession-items-code-text) --- # GET /v3/filings/{accession}/items/{code}/text One 8-K item's canonical text (not the filed HTML), cut from the stored primary document only when the document model and the exact bytes are at hand; otherwise text_status says why. Pages of at most 4 MiB on UTF-8 boundaries (offset, length; next_offset). Strong ETag over the whole response; If-None-Match answers 304 before the document is read. A document is converted once and its text kept in a cache while it is used; a conversion that does not finish within the request's time answers 503 conversion_timeout with Retry-After (it goes on, and the retry is served from the cache). **API key:** required. See [Authentication](https://www.secblast.com/docs/authentication). **Group:** [8-K items](https://www.secblast.com/docs/reference#8-k-items) ## Parameters | Name | In | Type | Required | Default | Description | |---|---|---|---|---|---| | `accession` | path | string | yes | | Accession number, with dashes (0001829126-26-010431) or without (18 digits). | | `code` | path | string | yes | | An item code (5.02) or its section key (8k.5.02). | | `offset` | query | integer | no | `0` | Byte offset in the item's text, 0..text_total_bytes. | | `length` | query | integer | no | `4194304` | Bytes per page, 1..4194304. | ## Responses | Status | Body | Description | |---|---|---| | `200` | [SpanText](https://www.secblast.com/docs/reference/schemas#schema-spantext) (`application/json`) | OK | | `304` | none | Not modified: If-None-Match named this page's ETag (answered before the document is read). | | `400` | [Problem](https://www.secblast.com/docs/reference/schemas#schema-problem) (`application/problem+json`) | Invalid or unknown parameter. | | `401` | [Problem](https://www.secblast.com/docs/reference/schemas#schema-problem) (`application/problem+json`) | Missing, invalid or inactive API key (code unauthorized), or a refused access token (code invalid_token: malformed, unknown key, bad signature, expired, wrong issuer or audience, revoked grant). WWW-Authenticate names the protected-resource metadata (RFC 9728). | | `404` | [Problem](https://www.secblast.com/docs/reference/schemas#schema-problem) (`application/problem+json`) | No filing with this accession (code not_found); the filing's form is not covered by this route's dataset (code not_covered, with members form_type, dataset and routes: the routes that cover it); for a text route, no such item or section in the parsed filing (code not_found). | | `422` | [Problem](https://www.secblast.com/docs/reference/schemas#schema-problem) (`application/problem+json`) | The stored document is larger than this server converts to text (code document_too_large, with members document_bytes, limit and document: the document's URL, whose span_start..span_end Range holds the filed bytes of the passage). Nothing was read. | | `503` | [Problem](https://www.secblast.com/docs/reference/schemas#schema-problem) (`application/problem+json`) | Database unavailable (code db_unavailable); or the document's conversion to text did not finish within the request's time (code conversion_timeout, with Retry-After): it goes on, and the same request after the delay is answered from the converted text. | | `504` | [Problem](https://www.secblast.com/docs/reference/schemas#schema-problem) (`application/problem+json`) | The request's time ran out (code timeout), e.g. while it waited for the server's conversion budget; nothing was converted for it. | | `default` | [Problem](https://www.secblast.com/docs/reference/schemas#schema-problem) (`application/problem+json`) | Any other error (405, 500, 504). | ## Response body A `200` carries a [SpanText](https://www.secblast.com/docs/reference/schemas#schema-spantext) object. | Field | Type | Required | Description | |---|---|---|---| | `accession` | string | no | | | `docmodel_version` | string \| null | no | | | `document` | object \| null | no | | | `extraction` | [Extraction](https://www.secblast.com/docs/reference/schemas#schema-extraction) | no | | | `next_offset` | integer \| null | no | | | `section` | string | no | | | `served_model_version` | string | no | | | `text` | string \| null | no | | | `text_bytes` | integer \| null | no | | | `text_offset` | integer \| null | no | | | `text_reason` | string \| null | no | One of: `model_changed`, `bytes_unavailable`, `null`. | | `text_status` | string | no | One of: `current`, `from_version`, `reparse_pending`, `no_text`, `parse_pending`. | | `text_total_bytes` | integer \| null | no | | | `text_truncated` | boolean | no | | ## Example request ```bash curl -sS -H "Authorization: Bearer $SECBLAST_API_KEY" \ 'https://api.secblast.com/v3/filings/0001829126-26-010431/items/5.02/text' ``` [Open this route in the console](https://www.secblast.com/console#get-v3-filings-accession-items-code-text) ## More in 8-K items Previous: [`GET /v3/filings/{accession}/items`](https://www.secblast.com/docs/reference/get-filings-accession-items) --- # GET /v3/companies/{cik}/periods One concept by fiscal period. Q4 = FY - 9M only when both are on the same basis at as_of; otherwise status basis_mismatch, no number, and the first-reported Q4 beside it (first_reported). The same rule for H2 = FY - H1 (semiannual filers), Q3 = 9M - H1 and Q2 = H1 - Q1. Per-share values, share counts and instants are never derived. Reported quarters, halves, nine months and years are served as filed (the incarnation known at as_of); derived values carry formula, inputs (accession, fact, concept, period, filed value) and rule version; TTM is the sum of four consecutive quarters and inherits a quarter's refusal. Fiscal labels come from the series' own dates. Deleted (SEC-withdrawn) filings are not read (an original stands again when its amendment is withdrawn; a derived value that used one is not served until derive:xbrl_periods has rebuilt it) and are named in excluded. **API key:** required. See [Authentication](https://www.secblast.com/docs/authentication). **Group:** [Financial data (XBRL)](https://www.secblast.com/docs/reference#financial-data-xbrl) ## Parameters | Name | In | Type | Required | Default | Description | |---|---|---|---|---|---| | `cik` | path | string | yes | | The entity's CIK, padded or unpadded. | | `concept` | query | string | yes | | prefix:LocalName, e.g. us-gaap:Revenues. Required. | | `unit` | query | string | no | | Only this unit as stored: iso4217:USD, shares, iso4217:USD/shares, ... | | `dims` | query | string | no | | none (default: no dimensions) or a dims_hash (32 hex digits) for one exact dimension set. | | `as_of` | query | string | no | | Inclusive: YYYY-MM-DDTHH:MM:SSZ (UTC, through the end of that second), YYYY-MM-DDTHH:MM:SS.ffffffZ (exact) or YYYY-MM-DD (the whole UTC day). Against each incarnation's filing acceptance time. | ## Responses | Status | Body | Description | |---|---|---| | `200` | [XbrlCompanyPeriods](https://www.secblast.com/docs/reference/schemas#schema-xbrlcompanyperiods) (`application/json`) | OK | | `400` | [Problem](https://www.secblast.com/docs/reference/schemas#schema-problem) (`application/problem+json`) | Invalid or unknown parameter. | | `401` | [Problem](https://www.secblast.com/docs/reference/schemas#schema-problem) (`application/problem+json`) | Missing, invalid or inactive API key (code unauthorized), or a refused access token (code invalid_token: malformed, unknown key, bad signature, expired, wrong issuer or audience, revoked grant). WWW-Authenticate names the protected-resource metadata (RFC 9728). | | `503` | [Problem](https://www.secblast.com/docs/reference/schemas#schema-problem) (`application/problem+json`) | Database unavailable; retry after the Retry-After delay. | | `default` | [Problem](https://www.secblast.com/docs/reference/schemas#schema-problem) (`application/problem+json`) | Any other error (405, 500, 504). | ## Response body A `200` carries a [XbrlCompanyPeriods](https://www.secblast.com/docs/reference/schemas#schema-xbrlcompanyperiods) object. | Field | Type | Required | Description | |---|---|---|---| | `as_of` | string \| null | yes | | | `cik` | string | yes | | | `concept` | string | yes | | | `data` | array of object | yes | | | `derivation` | object | yes | additivity of the concept's unit (flow, per_share, share_count, ratio, stock); derived false with the refusal status for anything but a flow. | | `dims` | string | yes | | | `excluded` | [Excluded](https://www.secblast.com/docs/reference/schemas#schema-excluded) | yes | | | `excluded_total` | integer | yes | | | `has_more` | boolean | yes | | | `next_cursor` | null | yes | | | `rule` | string | yes | | | `rule_version` | string | yes | | ## Example request ```bash curl -sS -H "Authorization: Bearer $SECBLAST_API_KEY" \ 'https://api.secblast.com/v3/companies/320193/periods' ``` The entity in this example is only an illustration. [Open this route in the console](https://www.secblast.com/console#get-v3-companies-cik-periods) ## More in Financial data (XBRL) Next: [`GET /v3/companies/{cik}/segments`](https://www.secblast.com/docs/reference/get-companies-cik-segments) --- # GET /v3/companies/{cik}/segments The company's breakdowns by period from its own dimensional facts: business segment, product or service, geography and major customer; revenue, operating income, assets, long-lived assets, D&A, capital expenditure and (from 2024) segment expenses. Each member under the company's own label (standard members named: country:XX, srt regions) with the fact behind it; reconciling items with their sign; the consolidated value (L4, else the filing's own total) and the check (pass, fail: served and flagged, not_evaluable, not_applicable for major customers). One filing's breakdown per period, axis and kind: view latest (as of a time) or first_reported. Deleted (SEC-withdrawn) filings are not read and are named in excluded. **API key:** required. See [Authentication](https://www.secblast.com/docs/authentication). **Group:** [Financial data (XBRL)](https://www.secblast.com/docs/reference#financial-data-xbrl) ## Parameters | Name | In | Type | Required | Default | Description | |---|---|---|---|---|---| | `cik` | path | string | yes | | The entity's CIK, padded or unpadded. | | `axis` | query | comma-separated list of string | no | | Axes, comma-separated (default: all): segment, product, geography, customer. | | `kind` | query | comma-separated list of string | no | | Value kinds, comma-separated (default: all): revenue, operating_income, assets, long_lived_assets, depreciation_amortization, capital_expenditure, expense. | | `periods` | query | comma-separated list of string | no | `annual` | Period classes, comma-separated: annual (the year ends: years and the instants on those dates), quarterly, ytd (half years, nine months), instant, or all. Default annual (all with period). | | `from` | query | string | no | | Periods ending on or after this date (YYYY-MM-DD). | | `to` | query | string | no | | Periods ending on or before this date (YYYY-MM-DD). | | `period` | query | string | no | | One period START/END, or every period ending on END (YYYY-MM-DD); not with from / to. | | `limit` | query | integer | no | `1` | Period ends per page, newest first, 1..200 (default 1: the latest fiscal year). | | `cursor` | query | string | no | | next_cursor of the previous page (same filters). | | `view` | query | string | no | `latest` | latest (default; as known at as_of) or first_reported (the earliest filing that stated the breakdown). One of: `latest`, `first_reported`. | | `as_of` | query | string | no | | Inclusive: YYYY-MM-DDTHH:MM:SSZ, YYYY-MM-DDTHH:MM:SS.ffffffZ or YYYY-MM-DD (the whole UTC day), against each incarnation's filing acceptance time; with view=latest. | ## Responses | Status | Body | Description | |---|---|---| | `200` | [XbrlCompanySegments](https://www.secblast.com/docs/reference/schemas#schema-xbrlcompanysegments) (`application/json`) | OK | | `400` | [Problem](https://www.secblast.com/docs/reference/schemas#schema-problem) (`application/problem+json`) | Invalid or unknown parameter. | | `401` | [Problem](https://www.secblast.com/docs/reference/schemas#schema-problem) (`application/problem+json`) | Missing, invalid or inactive API key (code unauthorized), or a refused access token (code invalid_token: malformed, unknown key, bad signature, expired, wrong issuer or audience, revoked grant). WWW-Authenticate names the protected-resource metadata (RFC 9728). | | `404` | [Problem](https://www.secblast.com/docs/reference/schemas#schema-problem) (`application/problem+json`) | Not found. | | `503` | [Problem](https://www.secblast.com/docs/reference/schemas#schema-problem) (`application/problem+json`) | Database unavailable; retry after the Retry-After delay. | | `default` | [Problem](https://www.secblast.com/docs/reference/schemas#schema-problem) (`application/problem+json`) | Any other error (405, 500, 504). | ## Response body A `200` carries a [XbrlCompanySegments](https://www.secblast.com/docs/reference/schemas#schema-xbrlcompanysegments) object. | Field | Type | Required | Description | |---|---|---|---| | `accuracy` | object | no | Measured precision and coverage of each requested kind on the latest unseen holdout (static; contract 2.10). | | `as_of` | string \| null | yes | | | `axes` | array of string | yes | | | `cik` | string | yes | | | `data` | array of object | yes | | | `excluded` | [Excluded](https://www.secblast.com/docs/reference/schemas#schema-excluded) | yes | | | `excluded_total` | integer | yes | | | `from` | string \| null | yes | | | `has_more` | boolean | yes | | | `kinds` | array of string | yes | | | `limit` | integer | yes | Period ends per page (default 1: the latest fiscal year). | | `next_cursor` | string \| null | yes | Opaque: the next page (earlier period ends), same filters. | | `period` | string \| null | yes | | | `periods` | string | yes | The period classes served, canonical (default annual: the year ends, their years and instants). | | `rule` | string | yes | | | `rules` | object | yes | | | `to` | string \| null | yes | | | `view` | string | yes | One of: `latest`, `first_reported`. | ## Example request ```bash curl -sS -H "Authorization: Bearer $SECBLAST_API_KEY" \ 'https://api.secblast.com/v3/companies/320193/segments' ``` The entity in this example is only an illustration. [Open this route in the console](https://www.secblast.com/console#get-v3-companies-cik-segments) ## More in Financial data (XBRL) Previous: [`GET /v3/companies/{cik}/periods`](https://www.secblast.com/docs/reference/get-companies-cik-periods) · Next: [`GET /v3/companies/{cik}/standard`](https://www.secblast.com/docs/reference/get-companies-cik-standard) --- # GET /v3/companies/{cik}/standard The company's standard fields by period (fields x periods), from each filing's own statements through a pinned concept map: each value with its status (ok, not_reported, ambiguous, not_applicable; a blank is never a zero), the facts behind it, the rule (candidate:\ or rollup), the map version and fingerprint, and flags (failed identities, scale outliers). Every filing's statement of a period is an incarnation: view latest (as of a time) or first_reported. Q4, Q3, Q2 and H2 of monetary flow fields are derived at read time only on one basis (else basis_mismatch with the first-reported value beside it). Banks, insurers, REITs, BDCs and IFRS filers: not_applicable. Pages of period ends, newest first (default: annual and quarterly periods of the 8 latest ends); each filing once in filings. Deleted (SEC-withdrawn) filings among those read are skipped and named in excluded. **API key:** required. See [Authentication](https://www.secblast.com/docs/authentication). **Group:** [Financial data (XBRL)](https://www.secblast.com/docs/reference#financial-data-xbrl) ## Parameters | Name | In | Type | Required | Default | Description | |---|---|---|---|---|---| | `cik` | path | string | yes | | The entity's CIK, padded or unpadded. | | `fields` | query | comma-separated list of string | no | | Standard fields, comma-separated (default: all core fields): revenue, cost_of_revenue, gross_profit, operating_income, pretax_income, net_income, eps_basic, eps_diluted, total_assets, total_liabilities, total_equity, cash_and_equivalents, operating_cash_flow, capital_expenditure, shares_outstanding, and the full template's measured fields (the accuracy object names each served field with its precision and coverage). | | `view` | query | string | no | `latest` | latest (default; as known at as_of) or first_reported (the earliest filing that stated the value). One of: `latest`, `first_reported`. | | `as_of` | query | string | no | | Inclusive: YYYY-MM-DDTHH:MM:SSZ (UTC, through the end of that second), YYYY-MM-DDTHH:MM:SS.ffffffZ (exact) or YYYY-MM-DD (the whole UTC day). Against each incarnation's filing acceptance time; with view=latest. | | `periods` | query | comma-separated list of string | no | `annual,quarterly` | Period classes, comma-separated: annual (years), quarterly (quarters, reported or derived), ytd (half years, nine months), instant (instants on no duration's end), or all. Default annual,quarterly (all with period). | | `from` | query | string | no | | Periods ending on or after this date (YYYY-MM-DD). | | `to` | query | string | no | | Periods ending on or before this date (YYYY-MM-DD). | | `period` | query | string | no | | One period START/END, or every period ending on END (YYYY-MM-DD); not with from / to. | | `limit` | query | integer | no | `8` | Period ends per page, newest first, 1..1000. | | `cursor` | query | string | no | | next_cursor of the previous page (same filters). | | `ttm` | query | string | no | `false` | true: also the trailing twelve months ending at each quarter end of the monetary flow fields (class ttm, Q1+Q2+Q3+Q4). One of: `true`, `false`. | ## Responses | Status | Body | Description | |---|---|---| | `200` | [XbrlCompanyStandard](https://www.secblast.com/docs/reference/schemas#schema-xbrlcompanystandard) (`application/json`) | OK | | `400` | [Problem](https://www.secblast.com/docs/reference/schemas#schema-problem) (`application/problem+json`) | Invalid or unknown parameter. | | `401` | [Problem](https://www.secblast.com/docs/reference/schemas#schema-problem) (`application/problem+json`) | Missing, invalid or inactive API key (code unauthorized), or a refused access token (code invalid_token: malformed, unknown key, bad signature, expired, wrong issuer or audience, revoked grant). WWW-Authenticate names the protected-resource metadata (RFC 9728). | | `404` | [Problem](https://www.secblast.com/docs/reference/schemas#schema-problem) (`application/problem+json`) | Not found. | | `503` | [Problem](https://www.secblast.com/docs/reference/schemas#schema-problem) (`application/problem+json`) | Database unavailable; retry after the Retry-After delay. | | `default` | [Problem](https://www.secblast.com/docs/reference/schemas#schema-problem) (`application/problem+json`) | Any other error (405, 500, 504). | ## Response body A `200` carries a [XbrlCompanyStandard](https://www.secblast.com/docs/reference/schemas#schema-xbrlcompanystandard) object. | Field | Type | Required | Description | |---|---|---|---| | `accuracy` | object | no | Measured precision and coverage of each requested field on the named map version (static; contract 2.9). | | `as_of` | string \| null | yes | | | `cik` | string | yes | | | `data` | array of object | yes | | | `data[].values` | object | no | | | `excluded` | [Excluded](https://www.secblast.com/docs/reference/schemas#schema-excluded) | yes | | | `excluded_total` | integer | yes | | | `fields` | array of string | yes | | | `filings` | object | yes | By accession, each filing a value of the page comes from (or a derived value's input): form_type, filing_date, accepted_at, template, map {version, fingerprint}. | | `from` | string \| null | yes | | | `has_more` | boolean | yes | | | `limit` | integer | yes | Period ends per page. | | `map` | object | yes | | | `next_cursor` | string \| null | yes | Opaque: the next page (earlier period ends), same filters. | | `period` | string \| null | yes | | | `periods` | string | yes | The period classes served, canonical (default annual,quarterly). | | `rule` | string | yes | | | `to` | string \| null | yes | | | `ttm` | boolean | no | true: TTM rows (class ttm) at each quarter end of the monetary flow fields. | | `view` | string | yes | One of: `latest`, `first_reported`. | ## Example request ```bash curl -sS -H "Authorization: Bearer $SECBLAST_API_KEY" \ 'https://api.secblast.com/v3/companies/320193/standard' ``` The entity in this example is only an illustration. [Open this route in the console](https://www.secblast.com/console#get-v3-companies-cik-standard) ## More in Financial data (XBRL) Previous: [`GET /v3/companies/{cik}/segments`](https://www.secblast.com/docs/reference/get-companies-cik-segments) · Next: [`GET /v3/companies/{cik}/statements`](https://www.secblast.com/docs/reference/get-companies-cik-statements) --- # GET /v3/companies/{cik}/statements A company's statement as presented in its latest periodic report (10-K, 10-Q, 10-KT, 10-QT, 20-F, 40-F and amendments) SEC had accepted by as_of that has one: of one kind (with its parentheticals), of one menu category (notes, details, ...) or one role URI; limit \> 1 gives the previous reports' too, newest first. Each report's statements are paged as on /v3/filings/{accession}/statements (has_more; links.next continues there). A category without kind or role_uri names one report (limit 1): its roles are paged here, with has_more and next_cursor. Deleted (SEC-withdrawn) reports are skipped (the previous report is served) and the ones the answer would have read are named in excluded. **API key:** required. See [Authentication](https://www.secblast.com/docs/authentication). **Group:** [Financial data (XBRL)](https://www.secblast.com/docs/reference#financial-data-xbrl) ## Parameters | Name | In | Type | Required | Default | Description | |---|---|---|---|---|---| | `cik` | path | string | yes | | The company's CIK (the filing's primary filer), padded or unpadded. | | `kind` | query | string | no | | BS, IS, CF, EQ, CI, CP or UN. Required unless category or role_uri is given. One of: `BS`, `IS`, `CF`, `EQ`, `CI`, `CP`, `UN`. | | `category` | query | string | no | | The role's menu category as SEC's FilingSummary states it, any letter case: Cover, Statements, Notes, Policies, Tables, Details, Other or Uncategorized (notes, policies, tables and details are served like statements). | | `role_uri` | query | string | no | | Only the role with this URI (roles\[\].role_uri), e.g. a company's own detail role. | | `as_of` | query | string | no | | Inclusive: YYYY-MM-DDTHH:MM:SSZ (UTC, through the end of that second), YYYY-MM-DDTHH:MM:SS.ffffffZ (exact) or YYYY-MM-DD (the whole UTC day). Against each incarnation's filing acceptance time. | | `limit` | query | integer | no | `1` | Reports, 1..8 (1 with a category alone). | | `cursor` | query | string | no | | next_cursor of the previous page (a category alone; same filters). | ## Responses | Status | Body | Description | |---|---|---| | `200` | [XbrlCompanyStatements](https://www.secblast.com/docs/reference/schemas#schema-xbrlcompanystatements) (`application/json`) | OK | | `400` | [Problem](https://www.secblast.com/docs/reference/schemas#schema-problem) (`application/problem+json`) | Invalid or unknown parameter. | | `401` | [Problem](https://www.secblast.com/docs/reference/schemas#schema-problem) (`application/problem+json`) | Missing, invalid or inactive API key (code unauthorized), or a refused access token (code invalid_token: malformed, unknown key, bad signature, expired, wrong issuer or audience, revoked grant). WWW-Authenticate names the protected-resource metadata (RFC 9728). | | `503` | [Problem](https://www.secblast.com/docs/reference/schemas#schema-problem) (`application/problem+json`) | Database unavailable; retry after the Retry-After delay. | | `default` | [Problem](https://www.secblast.com/docs/reference/schemas#schema-problem) (`application/problem+json`) | Any other error (405, 500, 504). | ## Response body A `200` carries a [XbrlCompanyStatements](https://www.secblast.com/docs/reference/schemas#schema-xbrlcompanystatements) object. | Field | Type | Required | Description | |---|---|---|---| | `as_of` | string \| null | yes | | | `category` | string \| null | yes | | | `cik` | string | yes | | | `data` | array of object | yes | | | `data[].accession` | string | no | | | `data[].filing` | object | no | With links.next: the filing route's next page of this report. | | `data[].has_more` | boolean | no | | | `data[].statements` | array of [XbrlStatement](https://www.secblast.com/docs/reference/schemas#schema-xbrlstatement) | no | | | `excluded` | [Excluded](https://www.secblast.com/docs/reference/schemas#schema-excluded) | yes | | | `excluded_total` | integer | yes | | | `has_more` | boolean | yes | A category alone: the report's next roles (next_cursor). | | `kind` | string \| null | yes | | | `next_cursor` | string \| null | yes | | | `role_uri` | string \| null | yes | | ## Example request ```bash curl -sS -H "Authorization: Bearer $SECBLAST_API_KEY" \ 'https://api.secblast.com/v3/companies/320193/statements' ``` The entity in this example is only an illustration. [Open this route in the console](https://www.secblast.com/console#get-v3-companies-cik-statements) ## More in Financial data (XBRL) Previous: [`GET /v3/companies/{cik}/standard`](https://www.secblast.com/docs/reference/get-companies-cik-standard) · Next: [`GET /v3/filings/{accession}/facts`](https://www.secblast.com/docs/reference/get-filings-accession-facts) --- # GET /v3/filings/{accession}/facts Every XBRL fact of a filing as filed: every instance read (the SEC-extracted one when there is one, else the filer's), facts numbered across them in reading order, each with its concept, context (entity, period, dimensions), unit, the exact value beside the filed text, decimals as filed (INF kept), nil, its duplicate class, and footnotes. A text block's content is not served: its span in the stored instance is. The xbrl block has the instances, taxonomy years, counts and dei cover values. Keyset pagination on fact_seq. 404 not_covered for a form under which no instance is filed. **API key:** required. See [Authentication](https://www.secblast.com/docs/authentication). **Group:** [Financial data (XBRL)](https://www.secblast.com/docs/reference#financial-data-xbrl) ## Parameters | Name | In | Type | Required | Default | Description | |---|---|---|---|---|---| | `accession` | path | string | yes | | Accession number, with dashes (0001829126-26-010431) or without (18 digits). | | `concept` | query | comma-separated list of string | no | | Only these concepts, as prefix:LocalName (standard taxonomies by their usual prefix: us-gaap, dei, ifrs-full, srt, ...). | | `limit` | query | integer | no | `1000` | Page size, 1..5000. | | `cursor` | query | string | no | | Opaque cursor from a previous page's next_cursor. | ## Responses | Status | Body | Description | |---|---|---| | `200` | [XbrlFilingFacts](https://www.secblast.com/docs/reference/schemas#schema-xbrlfilingfacts) (`application/json`) | OK | | `400` | [Problem](https://www.secblast.com/docs/reference/schemas#schema-problem) (`application/problem+json`) | Invalid or unknown parameter. | | `401` | [Problem](https://www.secblast.com/docs/reference/schemas#schema-problem) (`application/problem+json`) | Missing, invalid or inactive API key (code unauthorized), or a refused access token (code invalid_token: malformed, unknown key, bad signature, expired, wrong issuer or audience, revoked grant). WWW-Authenticate names the protected-resource metadata (RFC 9728). | | `404` | [Problem](https://www.secblast.com/docs/reference/schemas#schema-problem) (`application/problem+json`) | Not found. | | `503` | [Problem](https://www.secblast.com/docs/reference/schemas#schema-problem) (`application/problem+json`) | Database unavailable; retry after the Retry-After delay. | | `default` | [Problem](https://www.secblast.com/docs/reference/schemas#schema-problem) (`application/problem+json`) | Any other error (405, 500, 504). | ## Response body A `200` carries a [XbrlFilingFacts](https://www.secblast.com/docs/reference/schemas#schema-xbrlfilingfacts) object. | Field | Type | Required | Description | |---|---|---|---| | `accession` | string | yes | | | `data` | array of [XbrlFact](https://www.secblast.com/docs/reference/schemas#schema-xbrlfact) | yes | | | `extraction` | [Extraction](https://www.secblast.com/docs/reference/schemas#schema-extraction) | yes | | | `filing` | [FilingRef](https://www.secblast.com/docs/reference/schemas#schema-filingref) | yes | | | `footnotes` | array of object | yes | | | `has_more` | boolean | yes | | | `next_cursor` | string \| null | yes | | | `snapshot` | [Snapshot](https://www.secblast.com/docs/reference/schemas#schema-snapshot) | yes | | | `xbrl` | object \| null | yes | The instances read, namespaces, taxonomy years, counts, dei cover values as filed, cover (registrants, securities, shares outstanding, public float, auditors), flags; null before a parse. | ## Example request ```bash curl -sS -H "Authorization: Bearer $SECBLAST_API_KEY" \ 'https://api.secblast.com/v3/filings/0001829126-26-010431/facts' ``` [Open this route in the console](https://www.secblast.com/console#get-v3-filings-accession-facts) ## More in Financial data (XBRL) Previous: [`GET /v3/companies/{cik}/statements`](https://www.secblast.com/docs/reference/get-companies-cik-statements) · Next: [`GET /v3/filings/{accession}/statements`](https://www.secblast.com/docs/reference/get-filings-accession-statements) --- # GET /v3/filings/{accession}/statements The filing's statements as presented: every role of the filing (with its R page), and for the roles asked -- by default the statement and cover roles; kind, category, role_no or role_uri name others, notes, policies, tables and details included -- the presentation tree in the filer's order with preferred labels, negating / total / period start and end flags, its calculation arcs, and the columns and cells assembled from the filing's facts (each cell the filed fact: exact value and filed text; a blank is null, never zero; a text block's cell says where its text is). A negating label flips the displayed sign only: the cell is the fact as filed. matches_sec_render says whether the assembled layout has the rows of SEC's R page in its order (null: no R page). Paged: at most 25 roles and 2 MB of statements a page, a role longer than the rest of the page continues on the next one (rows_from_seq, rows_has_more); has_more and next_cursor; the role listing (roles, its first 500) on the first page only. 404 not_covered for a form under which no XBRL is filed. **API key:** required. See [Authentication](https://www.secblast.com/docs/authentication). **Group:** [Financial data (XBRL)](https://www.secblast.com/docs/reference#financial-data-xbrl) ## Parameters | Name | In | Type | Required | Default | Description | |---|---|---|---|---|---| | `accession` | path | string | yes | | Accession number, with dashes (0001829126-26-010431) or without (18 digits). | | `kind` | query | string | no | | The statement kind: BS balance sheet, IS income statement, CF cash flow, EQ changes in equity, CI comprehensive income, CP cover page, UN a statement no name rule classifies. One of: `BS`, `IS`, `CF`, `EQ`, `CI`, `CP`, `UN`. | | `category` | query | string | no | | The role's menu category as SEC's FilingSummary states it, any letter case: Cover, Statements, Notes, Policies, Tables, Details, Other or Uncategorized (notes, policies, tables and details are served like statements). | | `role_no` | query | integer | no | | Only this role (v3 role number, from roles\[\].role_no). | | `role_uri` | query | string | no | | Only the role with this URI (roles\[\].role_uri), e.g. a company's own detail role. | | `limit` | query | integer | no | `25` | Roles per page, 1..25. | | `cursor` | query | string | no | | next_cursor of the previous page (same filters). | ## Responses | Status | Body | Description | |---|---|---| | `200` | [XbrlFilingStatements](https://www.secblast.com/docs/reference/schemas#schema-xbrlfilingstatements) (`application/json`) | OK | | `400` | [Problem](https://www.secblast.com/docs/reference/schemas#schema-problem) (`application/problem+json`) | Invalid or unknown parameter. | | `401` | [Problem](https://www.secblast.com/docs/reference/schemas#schema-problem) (`application/problem+json`) | Missing, invalid or inactive API key (code unauthorized), or a refused access token (code invalid_token: malformed, unknown key, bad signature, expired, wrong issuer or audience, revoked grant). WWW-Authenticate names the protected-resource metadata (RFC 9728). | | `404` | [Problem](https://www.secblast.com/docs/reference/schemas#schema-problem) (`application/problem+json`) | Not found. | | `503` | [Problem](https://www.secblast.com/docs/reference/schemas#schema-problem) (`application/problem+json`) | Database unavailable; retry after the Retry-After delay. | | `default` | [Problem](https://www.secblast.com/docs/reference/schemas#schema-problem) (`application/problem+json`) | Any other error (405, 500, 504). | ## Response body A `200` carries a [XbrlFilingStatements](https://www.secblast.com/docs/reference/schemas#schema-xbrlfilingstatements) object. | Field | Type | Required | Description | |---|---|---|---| | `accession` | string | yes | | | `data` | array of [XbrlStatement](https://www.secblast.com/docs/reference/schemas#schema-xbrlstatement) | yes | At most 25 roles (limit) and 2 MB of statement JSON a page. | | `extraction` | [Extraction](https://www.secblast.com/docs/reference/schemas#schema-extraction) | yes | | | `filing` | [FilingRef](https://www.secblast.com/docs/reference/schemas#schema-filingref) | yes | | | `has_more` | boolean | yes | | | `next_cursor` | string \| null | yes | | | `roles` | array of object \| null | yes | The filing's roles, role number order: on the first page (no cursor) only, its first 500 (the rest: /statements/roles); null on later pages. | | `roles_has_more` | boolean | yes | | | `snapshot` | [Snapshot](https://www.secblast.com/docs/reference/schemas#schema-snapshot) | yes | | | `xbrl_statements` | object \| null | yes | Metadata source, documents read, counts, flags; null before a parse. | ## Example request ```bash curl -sS -H "Authorization: Bearer $SECBLAST_API_KEY" \ 'https://api.secblast.com/v3/filings/0001829126-26-010431/statements' ``` [Open this route in the console](https://www.secblast.com/console#get-v3-filings-accession-statements) ## More in Financial data (XBRL) Previous: [`GET /v3/filings/{accession}/facts`](https://www.secblast.com/docs/reference/get-filings-accession-facts) · Next: [`GET /v3/filings/{accession}/statements/roles`](https://www.secblast.com/docs/reference/get-filings-accession-statements-roles) --- # GET /v3/filings/{accession}/statements/roles The filing's roles without their statements: every role (statements, cover, notes, policies, tables, details) in position order, with its menu category, statement kind, R page, tree size and matches_sec_render, and a link to its statement. 404 not_covered for a form under which no XBRL is filed. Paged by role number: 500 a page, has_more and next_cursor. **API key:** required. See [Authentication](https://www.secblast.com/docs/authentication). **Group:** [Financial data (XBRL)](https://www.secblast.com/docs/reference#financial-data-xbrl) ## Parameters | Name | In | Type | Required | Default | Description | |---|---|---|---|---|---| | `accession` | path | string | yes | | Accession number, with dashes (0001829126-26-010431) or without (18 digits). | | `category` | query | string | no | | The role's menu category as SEC's FilingSummary states it, any letter case: Cover, Statements, Notes, Policies, Tables, Details, Other or Uncategorized (notes, policies, tables and details are served like statements). | | `limit` | query | integer | no | `500` | Roles per page, 1..500. | | `cursor` | query | string | no | | next_cursor of the previous page (same filters). | ## Responses | Status | Body | Description | |---|---|---| | `200` | [XbrlFilingRoles](https://www.secblast.com/docs/reference/schemas#schema-xbrlfilingroles) (`application/json`) | OK | | `400` | [Problem](https://www.secblast.com/docs/reference/schemas#schema-problem) (`application/problem+json`) | Invalid or unknown parameter. | | `401` | [Problem](https://www.secblast.com/docs/reference/schemas#schema-problem) (`application/problem+json`) | Missing, invalid or inactive API key (code unauthorized), or a refused access token (code invalid_token: malformed, unknown key, bad signature, expired, wrong issuer or audience, revoked grant). WWW-Authenticate names the protected-resource metadata (RFC 9728). | | `404` | [Problem](https://www.secblast.com/docs/reference/schemas#schema-problem) (`application/problem+json`) | Not found. | | `503` | [Problem](https://www.secblast.com/docs/reference/schemas#schema-problem) (`application/problem+json`) | Database unavailable; retry after the Retry-After delay. | | `default` | [Problem](https://www.secblast.com/docs/reference/schemas#schema-problem) (`application/problem+json`) | Any other error (405, 500, 504). | ## Response body A `200` carries a [XbrlFilingRoles](https://www.secblast.com/docs/reference/schemas#schema-xbrlfilingroles) object. | Field | Type | Required | Description | |---|---|---|---| | `accession` | string | yes | | | `category` | string \| null | yes | | | `data` | array of [XbrlRole](https://www.secblast.com/docs/reference/schemas#schema-xbrlrole) | yes | Role number order, at most 500 a page. | | `extraction` | [Extraction](https://www.secblast.com/docs/reference/schemas#schema-extraction) | yes | | | `filing` | [FilingRef](https://www.secblast.com/docs/reference/schemas#schema-filingref) | yes | | | `has_more` | boolean | yes | | | `next_cursor` | string \| null | yes | | | `snapshot` | [Snapshot](https://www.secblast.com/docs/reference/schemas#schema-snapshot) | yes | | | `xbrl_statements` | object \| null | yes | | ## Example request ```bash curl -sS -H "Authorization: Bearer $SECBLAST_API_KEY" \ 'https://api.secblast.com/v3/filings/0001829126-26-010431/statements/roles' ``` [Open this route in the console](https://www.secblast.com/console#get-v3-filings-accession-statements-roles) ## More in Financial data (XBRL) Previous: [`GET /v3/filings/{accession}/statements`](https://www.secblast.com/docs/reference/get-filings-accession-statements) · Next: [`GET /v3/financials/facts`](https://www.secblast.com/docs/reference/get-financials-facts) --- # GET /v3/financials/facts One company's facts of one concept across its filings, newest period first (then accession, fact_seq): every fact as filed, with its filing's form, filing date and acceptance time. as_of keeps the facts of filings SEC had accepted by then (inclusive; a date is the whole UTC day). Facts of a co-registrant are found by its own CIK. Facts without a period end (forever) are served by the filing route only. Facts of deleted (SEC-withdrawn) filings are listed (filing.status deleted) unless status leaves them out. **API key:** required. See [Authentication](https://www.secblast.com/docs/authentication). **Group:** [Financial data (XBRL)](https://www.secblast.com/docs/reference#financial-data-xbrl) ## Parameters | Name | In | Type | Required | Default | Description | |---|---|---|---|---|---| | `cik` | query | string | yes | | The entity's CIK (the context's entity, or the co-registrant's), padded or unpadded. Required. | | `concept` | query | string | yes | | prefix:LocalName, e.g. us-gaap:Revenues. Required. | | `period` | query | string | no | | YYYY-MM-DD: facts whose period ends that day (instants at it and durations ending on it); YYYY-MM-DD/YYYY-MM-DD: the duration with exactly that start and end. | | `dims` | query | string | no | | none (default: facts without dimensions), any, or a dims_hash (32 hex digits) for one exact dimension set. | | `status` | query | comma-separated list of string | no | | Status(es) of the rows' filings: provisional, final, deleted, comma-separated (as GET /v3/filings). Default: every status, deleted (SEC-withdrawn) filings included, each row's filing status saying so; status=final,provisional leaves deleted filings out. | | `as_of` | query | string | no | | Inclusive: YYYY-MM-DDTHH:MM:SSZ (UTC, through the end of that second), YYYY-MM-DDTHH:MM:SS.ffffffZ (exact, 1-6 fraction digits) or YYYY-MM-DD (the whole UTC day). | | `limit` | query | integer | no | `200` | Page size, 1..2000. | | `cursor` | query | string | no | | Opaque cursor from a previous page's next_cursor; bound to the filters. | ## Responses | Status | Body | Description | |---|---|---| | `200` | [XbrlFinancialFactList](https://www.secblast.com/docs/reference/schemas#schema-xbrlfinancialfactlist) (`application/json`) | OK | | `400` | [Problem](https://www.secblast.com/docs/reference/schemas#schema-problem) (`application/problem+json`) | Invalid or unknown parameter. | | `401` | [Problem](https://www.secblast.com/docs/reference/schemas#schema-problem) (`application/problem+json`) | Missing, invalid or inactive API key (code unauthorized), or a refused access token (code invalid_token: malformed, unknown key, bad signature, expired, wrong issuer or audience, revoked grant). WWW-Authenticate names the protected-resource metadata (RFC 9728). | | `503` | [Problem](https://www.secblast.com/docs/reference/schemas#schema-problem) (`application/problem+json`) | Database unavailable; retry after the Retry-After delay. | | `default` | [Problem](https://www.secblast.com/docs/reference/schemas#schema-problem) (`application/problem+json`) | Any other error (405, 500, 504). | ## Response body A `200` carries a [XbrlFinancialFactList](https://www.secblast.com/docs/reference/schemas#schema-xbrlfinancialfactlist) object. | Field | Type | Required | Description | |---|---|---|---| | `as_of` | string \| null | yes | | | `cik` | string | yes | | | `concept` | string | yes | | | `data` | array of [XbrlFinancialFact](https://www.secblast.com/docs/reference/schemas#schema-xbrlfinancialfact) | yes | | | `dims` | string | yes | | | `has_more` | boolean | yes | | | `next_cursor` | string \| null | yes | | | `period` | string \| null | yes | | ## Example request ```bash curl -sS -H "Authorization: Bearer $SECBLAST_API_KEY" \ 'https://api.secblast.com/v3/financials/facts?cik=320193' ``` The entity in this example is only an illustration. [Open this route in the console](https://www.secblast.com/console#get-v3-financials-facts) ## More in Financial data (XBRL) Previous: [`GET /v3/filings/{accession}/statements/roles`](https://www.secblast.com/docs/reference/get-filings-accession-statements-roles) · Next: [`GET /v3/financials/frames`](https://www.secblast.com/docs/reference/get-financials-frames) --- # GET /v3/financials/frames One concept and period across companies: each company's latest incarnation known at as_of (one per CIK, unit and dimension set), from one index range per filing year, the period being the filed dates. With frame instead of period, a CALENDAR frame (layer L3): CY2024Q4 (durations of 91 +/- 30 days whose midpoint is in the quarter), CY2024 (365 +/- 30 days, midpoint in the year) or CY2024Q4I (instants nearest the quarter's end), one value per company as known at as_of -- reported before derived (a derived Q4 = FY - 9M); a derived quarter refused as basis_mismatch is never a number in the frame, only counted in refused.basis_mismatch. Frames hold facts without dimensions only. Deleted (SEC-withdrawn) filings are left out (each company's latest remaining incarnation) and named in excluded. **API key:** required. See [Authentication](https://www.secblast.com/docs/authentication). **Group:** [Financial data (XBRL)](https://www.secblast.com/docs/reference#financial-data-xbrl) ## Parameters | Name | In | Type | Required | Default | Description | |---|---|---|---|---|---| | `concept` | query | string | yes | | prefix:LocalName, e.g. us-gaap:Assets. Required. | | `period` | query | string | no | | YYYY-MM-DD: the instant; YYYY-MM-DD/YYYY-MM-DD: the duration (the filed dates). Required unless frame is given. | | `frame` | query | string | no | | A calendar frame instead of period: CY2024Q4, CY2024 or CY2024Q4I. | | `unit` | query | string | no | | Only this unit as stored: iso4217:USD, shares, iso4217:USD/shares, ... | | `dims` | query | string | no | | none (default: no dimensions), any, or a dims_hash (32 hex digits) for one exact dimension set. | | `as_of` | query | string | no | | Inclusive: YYYY-MM-DDTHH:MM:SSZ (UTC, through the end of that second), YYYY-MM-DDTHH:MM:SS.ffffffZ (exact) or YYYY-MM-DD (the whole UTC day). Against each incarnation's filing acceptance time. | | `limit` | query | integer | no | `500` | Page size, 1..50000: rows in CIK, unit and dimension order. | | `cursor` | query | string | no | | Opaque cursor from a previous page's next_cursor; bound to the other parameters. | ## Responses | Status | Body | Description | |---|---|---| | `200` | [XbrlFrame](https://www.secblast.com/docs/reference/schemas#schema-xbrlframe) (`application/json`) | OK | | `400` | [Problem](https://www.secblast.com/docs/reference/schemas#schema-problem) (`application/problem+json`) | Invalid or unknown parameter. | | `401` | [Problem](https://www.secblast.com/docs/reference/schemas#schema-problem) (`application/problem+json`) | Missing, invalid or inactive API key (code unauthorized), or a refused access token (code invalid_token: malformed, unknown key, bad signature, expired, wrong issuer or audience, revoked grant). WWW-Authenticate names the protected-resource metadata (RFC 9728). | | `503` | [Problem](https://www.secblast.com/docs/reference/schemas#schema-problem) (`application/problem+json`) | Database unavailable; retry after the Retry-After delay. | | `default` | [Problem](https://www.secblast.com/docs/reference/schemas#schema-problem) (`application/problem+json`) | Any other error (405, 500, 504). | ## Response body A `200` carries a [XbrlFrame](https://www.secblast.com/docs/reference/schemas#schema-xbrlframe) object. | Field | Type | Required | Description | |---|---|---|---| | `as_of` | string \| null | yes | | | `concept` | string | yes | | | `data` | array of object | yes | | | `data[].accepted_at` | string | no | | | `data[].accession` | string | no | | | `data[].decimals` | string \| null | no | | | `data[].derived_key` | string \| null | no | | | `data[].dims_hash` | string \| null | no | | | `data[].entity_cik` | string | no | | | `data[].fact_seq` | integer \| null | no | | | `data[].from_accession` | string | no | | | `data[].period` | object | no | With frame only: the fact's own start and end. | | `data[].source` | string | no | With frame only. One of: `reported`, `derived`. | | `data[].unit_norm` | string | no | | | `data[].valid_from` | string | no | | | `data[].value` | [NullableDecimal](https://www.secblast.com/docs/reference/schemas#schema-nullabledecimal) | no | | | `data[].value_raw` | string \| null | no | | | `dims` | string | yes | | | `excluded` | [Excluded](https://www.secblast.com/docs/reference/schemas#schema-excluded) | no | | | `excluded_total` | integer | no | | | `frame` | string | no | With frame only: CY2024Q4, CY2024 or CY2024Q4I. | | `has_more` | boolean | yes | | | `next_cursor` | string \| null | yes | Pass as cursor for the next page; null on the last. | | `period` | string | yes | As requested; with frame, the calendar period's dates (YYYY-MM-DD/YYYY-MM-DD, or the instant). | | `refused` | object | no | With frame only: basis_mismatch, the number of companies whose only value for the frame is a derived quarter refused as basis_mismatch (no number in the frame). | | `rule` | string | no | | | `rule_version` | string | no | | | `unit` | string \| null | no | | ## Example request ```bash curl -sS -H "Authorization: Bearer $SECBLAST_API_KEY" \ 'https://api.secblast.com/v3/financials/frames' ``` [Open this route in the console](https://www.secblast.com/console#get-v3-financials-frames) ## More in Financial data (XBRL) Previous: [`GET /v3/financials/facts`](https://www.secblast.com/docs/reference/get-financials-facts) · Next: [`GET /v3/financials/series`](https://www.secblast.com/docs/reference/get-financials-series) --- # GET /v3/financials/series One company's values of one concept, point in time. Each identity (period, unit, dimensions) with view=latest: its last incarnation known at as_of (without as_of: the latest); view=first_reported: its first; view=revisions: every incarnation in order of acceptance, numbered, with the original value and whether the value changed. Every value as filed with its filing and acceptance time. A deleted (SEC-withdrawn) filing's facts are not an incarnation: the remaining filings decide every view (an amendment withdrawn leaves the original as latest); the deleted filings are named in excluded. **API key:** required. See [Authentication](https://www.secblast.com/docs/authentication). **Group:** [Financial data (XBRL)](https://www.secblast.com/docs/reference#financial-data-xbrl) ## Parameters | Name | In | Type | Required | Default | Description | |---|---|---|---|---|---| | `cik` | query | string | yes | | The entity's CIK, padded or unpadded. Required. | | `concept` | query | string | yes | | prefix:LocalName, e.g. us-gaap:Revenues. Required. | | `period` | query | string | no | | YYYY-MM-DD: an instant (frames) or periods ending that day (series); YYYY-MM-DD/YYYY-MM-DD: that exact duration. | | `unit` | query | string | no | | Only this unit as stored: iso4217:USD, shares, iso4217:USD/shares, ... | | `dims` | query | string | no | | none (default: no dimensions), any, or a dims_hash (32 hex digits) for one exact dimension set. | | `view` | query | string | no | `latest` | Which incarnation of each identity. One of: `latest`, `first_reported`, `revisions`. | | `as_of` | query | string | no | | Inclusive: YYYY-MM-DDTHH:MM:SSZ (UTC, through the end of that second), YYYY-MM-DDTHH:MM:SS.ffffffZ (exact) or YYYY-MM-DD (the whole UTC day). Against each incarnation's filing acceptance time. | ## Responses | Status | Body | Description | |---|---|---| | `200` | [XbrlSeries](https://www.secblast.com/docs/reference/schemas#schema-xbrlseries) (`application/json`) | OK | | `400` | [Problem](https://www.secblast.com/docs/reference/schemas#schema-problem) (`application/problem+json`) | Invalid or unknown parameter. | | `401` | [Problem](https://www.secblast.com/docs/reference/schemas#schema-problem) (`application/problem+json`) | Missing, invalid or inactive API key (code unauthorized), or a refused access token (code invalid_token: malformed, unknown key, bad signature, expired, wrong issuer or audience, revoked grant). WWW-Authenticate names the protected-resource metadata (RFC 9728). | | `503` | [Problem](https://www.secblast.com/docs/reference/schemas#schema-problem) (`application/problem+json`) | Database unavailable; retry after the Retry-After delay. | | `default` | [Problem](https://www.secblast.com/docs/reference/schemas#schema-problem) (`application/problem+json`) | Any other error (405, 500, 504). | ## Response body A `200` carries a [XbrlSeries](https://www.secblast.com/docs/reference/schemas#schema-xbrlseries) object. | Field | Type | Required | Description | |---|---|---|---| | `as_of` | string \| null | yes | | | `cik` | string | yes | | | `concept` | string | yes | | | `data` | array of object | yes | | | `data[].accession` | string | no | | | `data[].decimals` | string \| null | no | | | `data[].dup_inconsistent` | boolean | no | | | `data[].fact_seq` | integer | no | | | `data[].filing` | object | no | | | `data[].identity` | object | no | | | `data[].identity.dims_hash` | string \| null | no | | | `data[].identity.period` | [XbrlPeriod](https://www.secblast.com/docs/reference/schemas#schema-xbrlperiod) | no | | | `data[].identity.unit_norm` | string | no | | | `data[].is_nil` | boolean | no | | | `data[].revision` | object | no | number: 1 = first reported; of: incarnations known at as_of; original_value: the first one's; changed: the value differs from the previous incarnation's. | | `data[].value` | [NullableDecimal](https://www.secblast.com/docs/reference/schemas#schema-nullabledecimal) | no | | | `data[].value_raw` | string \| null | no | | | `dims` | string | yes | | | `excluded` | [Excluded](https://www.secblast.com/docs/reference/schemas#schema-excluded) | no | | | `excluded_total` | integer | no | | | `has_more` | boolean | yes | | | `next_cursor` | null | yes | | | `view` | string | yes | One of: `latest`, `first_reported`, `revisions`. | ## Example request ```bash curl -sS -H "Authorization: Bearer $SECBLAST_API_KEY" \ 'https://api.secblast.com/v3/financials/series?cik=320193' ``` The entity in this example is only an illustration. [Open this route in the console](https://www.secblast.com/console#get-v3-financials-series) ## More in Financial data (XBRL) Previous: [`GET /v3/financials/frames`](https://www.secblast.com/docs/reference/get-financials-frames) · Next: [`GET /v3/financials/standard`](https://www.secblast.com/docs/reference/get-financials-standard) --- # GET /v3/financials/standard One standard field across companies for a calendar frame (CY2024Q4, CY2024; CY2024Q4I for balance-sheet fields): each company's reported value (view latest as of a time, or first_reported) with its facts, rule, map pin and flags; in a quarter frame, a company without a reported quarter gets its quarter derived from its year, nine months, half or first quarter on one basis (monetary flows); ttm=true gives the trailing twelve months ending in the quarter. Companies whose answer is not ok are counted in refused, never a number. Deleted (SEC-withdrawn) filings are not read and are named in excluded. **API key:** required. See [Authentication](https://www.secblast.com/docs/authentication). **Group:** [Financial data (XBRL)](https://www.secblast.com/docs/reference#financial-data-xbrl) ## Parameters | Name | In | Type | Required | Default | Description | |---|---|---|---|---|---| | `field` | query | string | yes | | A standard field (as for /v3/companies/{cik}/standard). Required. | | `frame` | query | string | yes | | CY2024Q4 (a quarter), CY2024 (a year) or CY2024Q4I (an instant). Required. | | `ttm` | query | string | no | `false` | true: the sum of the four consecutive quarters ending in the frame's quarter (a quarter frame, a monetary flow field). One of: `true`, `false`. | | `view` | query | string | no | `latest` | latest (default; as known at as_of) or first_reported (the earliest filing that stated the value). One of: `latest`, `first_reported`. | | `as_of` | query | string | no | | Inclusive: YYYY-MM-DDTHH:MM:SSZ (UTC, through the end of that second), YYYY-MM-DDTHH:MM:SS.ffffffZ (exact) or YYYY-MM-DD (the whole UTC day). Against each incarnation's filing acceptance time; with view=latest. | | `limit` | query | integer | no | `100` | Companies with a value per page, CIK order, 1..10000. | | `cursor` | query | string | no | | next_cursor of the previous page (opaque; same filters). | ## Responses | Status | Body | Description | |---|---|---| | `200` | [XbrlStandardFrame](https://www.secblast.com/docs/reference/schemas#schema-xbrlstandardframe) (`application/json`) | OK | | `400` | [Problem](https://www.secblast.com/docs/reference/schemas#schema-problem) (`application/problem+json`) | Invalid or unknown parameter. | | `401` | [Problem](https://www.secblast.com/docs/reference/schemas#schema-problem) (`application/problem+json`) | Missing, invalid or inactive API key (code unauthorized), or a refused access token (code invalid_token: malformed, unknown key, bad signature, expired, wrong issuer or audience, revoked grant). WWW-Authenticate names the protected-resource metadata (RFC 9728). | | `404` | [Problem](https://www.secblast.com/docs/reference/schemas#schema-problem) (`application/problem+json`) | Not found. | | `503` | [Problem](https://www.secblast.com/docs/reference/schemas#schema-problem) (`application/problem+json`) | Database unavailable; retry after the Retry-After delay. | | `default` | [Problem](https://www.secblast.com/docs/reference/schemas#schema-problem) (`application/problem+json`) | Any other error (405, 500, 504). | ## Response body A `200` carries a [XbrlStandardFrame](https://www.secblast.com/docs/reference/schemas#schema-xbrlstandardframe) object. | Field | Type | Required | Description | |---|---|---|---| | `accuracy` | object | no | Measured precision and coverage of the field on the named map version (static; contract 2.9). | | `as_of` | string \| null | yes | | | `data` | array of [XbrlStdValue](https://www.secblast.com/docs/reference/schemas#schema-xbrlstdvalue) | yes | One ok value per company, CIK order, with entity_cik, period and links.company: reported, or derived (a quarter of a quarter frame, a TTM) with formula and inputs. | | `excluded` | [Excluded](https://www.secblast.com/docs/reference/schemas#schema-excluded) | yes | | | `excluded_total` | integer | yes | | | `field` | string | yes | | | `frame` | string | yes | | | `has_more` | boolean | yes | | | `limit` | integer | yes | Companies with a value per page. | | `map` | object | yes | | | `next_cursor` | string \| null | yes | Opaque: the companies after this page, same filters. | | `period` | string | yes | | | `refused` | object | yes | Companies left out by status: ambiguous, not_reported, not_applicable, basis_mismatch, refused_\*. | | `rule` | string | yes | | | `ttm` | boolean | yes | true: each value is the trailing twelve months ending in the frame's quarter. | | `view` | string | yes | | ## Example request ```bash curl -sS -H "Authorization: Bearer $SECBLAST_API_KEY" \ 'https://api.secblast.com/v3/financials/standard' ``` [Open this route in the console](https://www.secblast.com/console#get-v3-financials-standard) ## More in Financial data (XBRL) Previous: [`GET /v3/financials/series`](https://www.secblast.com/docs/reference/get-financials-series) --- # GET /v3/filings/{accession}/ownership A Form 3, 4 or 5 (or its /A) as filed: the document's filing-level fields, the issuer, every reporting owner with the whole address and relationship, the SEC header's entities (addresses and phone numbers), the four tables (non-derivative and derivative transactions and holdings) with each row's footnote references and footnote text, the footnotes, the signatures, and the filing's amendment chain (provisional). Numbers are exact decimal strings with their filed text beside them (_raw); a price given only in a footnote is null with the flag price_in_footnote. 404 not_covered for another form. **API key:** required. See [Authentication](https://www.secblast.com/docs/authentication). **Group:** [Insider ownership (Forms 3, 4, 5)](https://www.secblast.com/docs/reference#insider-ownership-forms-3-4-5) ## Parameters | Name | In | Type | Required | Default | Description | |---|---|---|---|---|---| | `accession` | path | string | yes | | Accession number, with dashes (0001829126-26-010431) or without (18 digits). | ## Responses | Status | Body | Description | |---|---|---| | `200` | [OwnershipFiling](https://www.secblast.com/docs/reference/schemas#schema-ownershipfiling) (`application/json`) | OK | | `400` | [Problem](https://www.secblast.com/docs/reference/schemas#schema-problem) (`application/problem+json`) | Invalid or unknown parameter. | | `401` | [Problem](https://www.secblast.com/docs/reference/schemas#schema-problem) (`application/problem+json`) | Missing, invalid or inactive API key (code unauthorized), or a refused access token (code invalid_token: malformed, unknown key, bad signature, expired, wrong issuer or audience, revoked grant). WWW-Authenticate names the protected-resource metadata (RFC 9728). | | `404` | [Problem](https://www.secblast.com/docs/reference/schemas#schema-problem) (`application/problem+json`) | No filing with this accession (code not_found); the filing's form is not covered by this route's dataset (code not_covered, with members form_type, dataset and routes: the routes that cover it); for a text route, no such item or section in the parsed filing (code not_found). | | `503` | [Problem](https://www.secblast.com/docs/reference/schemas#schema-problem) (`application/problem+json`) | Database unavailable; retry after the Retry-After delay. | | `default` | [Problem](https://www.secblast.com/docs/reference/schemas#schema-problem) (`application/problem+json`) | Any other error (405, 500, 504). | ## Response body A `200` carries a [OwnershipFiling](https://www.secblast.com/docs/reference/schemas#schema-ownershipfiling) object. | Field | Type | Required | Description | |---|---|---|---| | `accession` | string | no | | | `amendment_chain` | object \| null | no | Provisional: the original with the amendments that name it, the steps, how each amendment was linked and its row links. | | `document` | object \| null | no | | | `extraction` | [Extraction](https://www.secblast.com/docs/reference/schemas#schema-extraction) | no | | | `filing` | [FilingRef](https://www.secblast.com/docs/reference/schemas#schema-filingref) | no | | | `footnotes` | array of object | no | | | `header_entities` | array of object | no | The SEC header's entities with every field, addresses and phone numbers included. | | `issuer` | object \| null | no | | | `links` | object | no | | | `other_footnote_references` | array of object | no | | | `owners` | array of object | no | Every reporting owner, document order, with the whole address and relationship. | | `signatures` | array of object | no | | | `snapshot` | [Snapshot](https://www.secblast.com/docs/reference/schemas#schema-snapshot) | no | | | `tables` | object | no | | | `tables.derivative_holdings` | array of [InsiderRow](https://www.secblast.com/docs/reference/schemas#schema-insiderrow) | no | | | `tables.derivative_transactions` | array of [InsiderRow](https://www.secblast.com/docs/reference/schemas#schema-insiderrow) | no | | | `tables.non_derivative_holdings` | array of [InsiderRow](https://www.secblast.com/docs/reference/schemas#schema-insiderrow) | no | | | `tables.non_derivative_transactions` | array of [InsiderRow](https://www.secblast.com/docs/reference/schemas#schema-insiderrow) | no | | ## Example request ```bash curl -sS -H "Authorization: Bearer $SECBLAST_API_KEY" \ 'https://api.secblast.com/v3/filings/0001829126-26-010431/ownership' ``` [Open this route in the console](https://www.secblast.com/console#get-v3-filings-accession-ownership) ## More in Insider ownership (Forms 3, 4, 5) Next: [`GET /v3/ownership/insiders/holdings`](https://www.secblast.com/docs/reference/get-ownership-insiders-holdings) --- # GET /v3/ownership/insiders/holdings Forms 3/4/5 holding rows (Table I and Table II) across filings, newest filing first, then table and row, with the same filing, issuer, owner and footnote members and the same views as the transactions route. Without issuer_cik or owner_cik, filed_from and filed_to are required and at most 31 days apart. **API key:** required. See [Authentication](https://www.secblast.com/docs/authentication). **Group:** [Insider ownership (Forms 3, 4, 5)](https://www.secblast.com/docs/reference#insider-ownership-forms-3-4-5) ## Parameters | Name | In | Type | Required | Default | Description | |---|---|---|---|---|---| | `issuer_cik` | query | string | no | | Issuer CIK, padded or unpadded. | | `owner_cik` | query | string | no | | Reporting owner CIK, padded or unpadded (any owner of the filing). | | `table` | query | string | no | `all` | all, non_derivative (Table I) or derivative (Table II). One of: `all`, `non_derivative`, `derivative`. | | `filed_from` | query | date (YYYY-MM-DD) | no | | First filing date (inclusive), YYYY-MM-DD. | | `filed_to` | query | date (YYYY-MM-DD) | no | | Last filing date (inclusive), YYYY-MM-DD. | | `view` | query | string | no | `as_filed` | as_filed or effective (provisional). One of: `as_filed`, `effective`. | | `status` | query | comma-separated list of string | no | | With view=as_filed, status(es) of the rows' filings: provisional, final, deleted, comma-separated (as GET /v3/filings). Default: every status, deleted (SEC-withdrawn) filings included; status=final,provisional leaves them out. With view=effective it is a 400: the effective view always leaves deleted filings out and names them in excluded. | | `footnote_contains` | query | string | no | | Only rows with a footnote whose text contains this, case-insensitive (3 to 200 characters; % and _ are plain characters). Needs issuer_cik, owner_cik, or filed_from and filed_to at most 31 days apart. | | `as_of` | query | string | no | | Inclusive: YYYY-MM-DDTHH:MM:SSZ (UTC, through the end of that second), YYYY-MM-DDTHH:MM:SS.ffffffZ (exact, 1-6 fraction digits) or YYYY-MM-DD (the whole UTC day). | | `limit` | query | integer | no | `100` | Page size, 1..500. | | `cursor` | query | string | no | | Opaque cursor from a previous page's next_cursor; bound to the filters (as_of included). | ## Responses | Status | Body | Description | |---|---|---| | `200` | [InsiderRowList](https://www.secblast.com/docs/reference/schemas#schema-insiderrowlist) (`application/json`) | OK | | `400` | [Problem](https://www.secblast.com/docs/reference/schemas#schema-problem) (`application/problem+json`) | Invalid or unknown parameter. | | `401` | [Problem](https://www.secblast.com/docs/reference/schemas#schema-problem) (`application/problem+json`) | Missing, invalid or inactive API key (code unauthorized), or a refused access token (code invalid_token: malformed, unknown key, bad signature, expired, wrong issuer or audience, revoked grant). WWW-Authenticate names the protected-resource metadata (RFC 9728). | | `503` | [Problem](https://www.secblast.com/docs/reference/schemas#schema-problem) (`application/problem+json`) | Database unavailable; retry after the Retry-After delay. | | `default` | [Problem](https://www.secblast.com/docs/reference/schemas#schema-problem) (`application/problem+json`) | Any other error (405, 500, 504). | ## Response body A `200` carries a [InsiderRowList](https://www.secblast.com/docs/reference/schemas#schema-insiderrowlist) object. | Field | Type | Required | Description | |---|---|---|---| | `as_of` | string \| null | no | | | `data` | array of [InsiderRow](https://www.secblast.com/docs/reference/schemas#schema-insiderrow) + object | no | | | `excluded` | [Excluded](https://www.secblast.com/docs/reference/schemas#schema-excluded) | no | view=effective only. | | `excluded_total` | integer | no | view=effective only. | | `has_more` | boolean | no | | | `next_cursor` | string \| null | no | | | `provisional` | boolean | no | True for view=effective: the row-level amendment view is provisional. | | `view` | string | no | One of: `as_filed`, `effective`. | ## Example request ```bash curl -sS -H "Authorization: Bearer $SECBLAST_API_KEY" \ 'https://api.secblast.com/v3/ownership/insiders/holdings' ``` [Open this route in the console](https://www.secblast.com/console#get-v3-ownership-insiders-holdings) ## More in Insider ownership (Forms 3, 4, 5) Previous: [`GET /v3/filings/{accession}/ownership`](https://www.secblast.com/docs/reference/get-filings-accession-ownership) · Next: [`GET /v3/ownership/insiders/transactions`](https://www.secblast.com/docs/reference/get-ownership-insiders-transactions) --- # GET /v3/ownership/insiders/transactions Forms 3/4/5 transaction rows (Table I and Table II) across filings, newest filing first, then table and row. Each row carries its filing, issuer, every reporting owner and its footnotes; rows belong to the filing and are never repeated per owner. view=as_filed lists every filed row; view=effective (provisional) applies the amendments row by row: a row an amendment restated is replaced by the amendment's row, rows of an amendment that could not be matched unambiguously stay as filed with the flag amendment_unreconciled, and every row of a chain names its original and its amending filing. as_of: only filings SEC had accepted by then. Without issuer_cik, owner_cik or code, filed_from and filed_to are required and at most 31 days apart. Deleted (SEC-withdrawn) filings: listed by view=as_filed (filing.status deleted) unless status leaves them out; left out of view=effective (a deleted amendment does not amend) and named in excluded. **API key:** required. See [Authentication](https://www.secblast.com/docs/authentication). **Group:** [Insider ownership (Forms 3, 4, 5)](https://www.secblast.com/docs/reference#insider-ownership-forms-3-4-5) ## Parameters | Name | In | Type | Required | Default | Description | |---|---|---|---|---|---| | `issuer_cik` | query | string | no | | Issuer CIK, padded or unpadded. | | `owner_cik` | query | string | no | | Reporting owner CIK, padded or unpadded (any owner of the filing). | | `code` | query | comma-separated list of string | no | | Transaction codes (P, S, A, M, F, G, ...), comma-separated or repeated. | | `table` | query | string | no | `all` | all, non_derivative (Table I) or derivative (Table II). One of: `all`, `non_derivative`, `derivative`. | | `filed_from` | query | date (YYYY-MM-DD) | no | | First filing date (inclusive), YYYY-MM-DD. | | `filed_to` | query | date (YYYY-MM-DD) | no | | Last filing date (inclusive), YYYY-MM-DD. | | `view` | query | string | no | `as_filed` | as_filed or effective (provisional). One of: `as_filed`, `effective`. | | `status` | query | comma-separated list of string | no | | With view=as_filed, status(es) of the rows' filings: provisional, final, deleted, comma-separated (as GET /v3/filings). Default: every status, deleted (SEC-withdrawn) filings included; status=final,provisional leaves them out. With view=effective it is a 400: the effective view always leaves deleted filings out and names them in excluded. | | `footnote_contains` | query | string | no | | Only rows with a footnote whose text contains this, case-insensitive (3 to 200 characters; % and _ are plain characters). Needs issuer_cik, owner_cik, or filed_from and filed_to at most 31 days apart. | | `as_of` | query | string | no | | Inclusive: YYYY-MM-DDTHH:MM:SSZ (UTC, through the end of that second), YYYY-MM-DDTHH:MM:SS.ffffffZ (exact, 1-6 fraction digits) or YYYY-MM-DD (the whole UTC day). | | `limit` | query | integer | no | `100` | Page size, 1..500. | | `cursor` | query | string | no | | Opaque cursor from a previous page's next_cursor; bound to the filters (as_of included). | ## Responses | Status | Body | Description | |---|---|---| | `200` | [InsiderRowList](https://www.secblast.com/docs/reference/schemas#schema-insiderrowlist) (`application/json`) | OK | | `400` | [Problem](https://www.secblast.com/docs/reference/schemas#schema-problem) (`application/problem+json`) | Invalid or unknown parameter. | | `401` | [Problem](https://www.secblast.com/docs/reference/schemas#schema-problem) (`application/problem+json`) | Missing, invalid or inactive API key (code unauthorized), or a refused access token (code invalid_token: malformed, unknown key, bad signature, expired, wrong issuer or audience, revoked grant). WWW-Authenticate names the protected-resource metadata (RFC 9728). | | `503` | [Problem](https://www.secblast.com/docs/reference/schemas#schema-problem) (`application/problem+json`) | Database unavailable; retry after the Retry-After delay. | | `default` | [Problem](https://www.secblast.com/docs/reference/schemas#schema-problem) (`application/problem+json`) | Any other error (405, 500, 504). | ## Response body A `200` carries a [InsiderRowList](https://www.secblast.com/docs/reference/schemas#schema-insiderrowlist) object. | Field | Type | Required | Description | |---|---|---|---| | `as_of` | string \| null | no | | | `data` | array of [InsiderRow](https://www.secblast.com/docs/reference/schemas#schema-insiderrow) + object | no | | | `excluded` | [Excluded](https://www.secblast.com/docs/reference/schemas#schema-excluded) | no | view=effective only. | | `excluded_total` | integer | no | view=effective only. | | `has_more` | boolean | no | | | `next_cursor` | string \| null | no | | | `provisional` | boolean | no | True for view=effective: the row-level amendment view is provisional. | | `view` | string | no | One of: `as_filed`, `effective`. | ## Example request ```bash curl -sS -H "Authorization: Bearer $SECBLAST_API_KEY" \ 'https://api.secblast.com/v3/ownership/insiders/transactions' ``` [Open this route in the console](https://www.secblast.com/console#get-v3-ownership-insiders-transactions) ## More in Insider ownership (Forms 3, 4, 5) Previous: [`GET /v3/ownership/insiders/holdings`](https://www.secblast.com/docs/reference/get-ownership-insiders-holdings) --- # GET /v3/filings/{accession}/13f A 13F filing's cover page (contact fields: city, state or country, ZIP code; no street line, no phone), summary page, both lists of other managers, the unit decision of its values (value_unit) and its step in the manager-period's amendment ledger. Numbers are exact decimal strings with their filed text beside them (_raw). 404 not_covered for a form that is not 13F. **API key:** required. See [Authentication](https://www.secblast.com/docs/authentication). **Group:** [Institutional holdings (Form 13F)](https://www.secblast.com/docs/reference#institutional-holdings-form-13f) ## Parameters | Name | In | Type | Required | Default | Description | |---|---|---|---|---|---| | `accession` | path | string | yes | | Accession number, with dashes (0001829126-26-010431) or without (18 digits). | ## Responses | Status | Body | Description | |---|---|---| | `200` | [F13fFiling](https://www.secblast.com/docs/reference/schemas#schema-f13ffiling) (`application/json`) | OK | | `400` | [Problem](https://www.secblast.com/docs/reference/schemas#schema-problem) (`application/problem+json`) | Invalid or unknown parameter. | | `401` | [Problem](https://www.secblast.com/docs/reference/schemas#schema-problem) (`application/problem+json`) | Missing, invalid or inactive API key (code unauthorized), or a refused access token (code invalid_token: malformed, unknown key, bad signature, expired, wrong issuer or audience, revoked grant). WWW-Authenticate names the protected-resource metadata (RFC 9728). | | `404` | [Problem](https://www.secblast.com/docs/reference/schemas#schema-problem) (`application/problem+json`) | No filing with this accession (code not_found); the filing's form is not covered by this route's dataset (code not_covered, with members form_type, dataset and routes: the routes that cover it); for a text route, no such item or section in the parsed filing (code not_found). | | `503` | [Problem](https://www.secblast.com/docs/reference/schemas#schema-problem) (`application/problem+json`) | Database unavailable; retry after the Retry-After delay. | | `default` | [Problem](https://www.secblast.com/docs/reference/schemas#schema-problem) (`application/problem+json`) | Any other error (405, 500, 504). | ## Response body A `200` carries a [F13fFiling](https://www.secblast.com/docs/reference/schemas#schema-f13ffiling) object. | Field | Type | Required | Description | |---|---|---|---| | `accession` | string | no | | | `cover` | [F13fCover](https://www.secblast.com/docs/reference/schemas#schema-f13fcover) | no | | | `extraction` | [Extraction](https://www.secblast.com/docs/reference/schemas#schema-extraction) | no | | | `filing` | [FilingRef](https://www.secblast.com/docs/reference/schemas#schema-filingref) | no | | | `ledger` | any | no | | | `links` | object | no | | | `other_managers` | object | no | | | `other_managers.included` | array of [F13fOtherManager](https://www.secblast.com/docs/reference/schemas#schema-f13fothermanager) | no | | | `other_managers.reporting_for_filer` | array of [F13fOtherManager](https://www.secblast.com/docs/reference/schemas#schema-f13fothermanager) | no | | | `snapshot` | [Snapshot](https://www.secblast.com/docs/reference/schemas#schema-snapshot) | no | | | `summary` | [F13fSummary](https://www.secblast.com/docs/reference/schemas#schema-f13fsummary) | no | | | `value_unit` | [ValueUnit](https://www.secblast.com/docs/reference/schemas#schema-valueunit) | no | | ## Example request ```bash curl -sS -H "Authorization: Bearer $SECBLAST_API_KEY" \ 'https://api.secblast.com/v3/filings/0001829126-26-010431/13f' ``` [Open this route in the console](https://www.secblast.com/console#get-v3-filings-accession-13f) ## More in Institutional holdings (Form 13F) Next: [`GET /v3/filings/{accession}/13f/holdings`](https://www.secblast.com/docs/reference/get-filings-accession-13f-holdings) --- # GET /v3/filings/{accession}/13f/holdings The information-table rows of a 13F filing exactly as filed, in document order, with value_usd = value_reported x the unit decision's multiplier (null when the unit is ambiguous or not decided). Keyset pagination on row_no. **API key:** required. See [Authentication](https://www.secblast.com/docs/authentication). **Group:** [Institutional holdings (Form 13F)](https://www.secblast.com/docs/reference#institutional-holdings-form-13f) ## Parameters | Name | In | Type | Required | Default | Description | |---|---|---|---|---|---| | `accession` | path | string | yes | | Accession number, with dashes (0001829126-26-010431) or without (18 digits). | | `limit` | query | integer | no | `200` | Page size, 1..1000. | | `cursor` | query | string | no | | Opaque cursor from a previous page's next_cursor. | ## Responses | Status | Body | Description | |---|---|---| | `200` | [F13fHoldingList](https://www.secblast.com/docs/reference/schemas#schema-f13fholdinglist) (`application/json`) | OK | | `400` | [Problem](https://www.secblast.com/docs/reference/schemas#schema-problem) (`application/problem+json`) | Invalid or unknown parameter. | | `401` | [Problem](https://www.secblast.com/docs/reference/schemas#schema-problem) (`application/problem+json`) | Missing, invalid or inactive API key (code unauthorized), or a refused access token (code invalid_token: malformed, unknown key, bad signature, expired, wrong issuer or audience, revoked grant). WWW-Authenticate names the protected-resource metadata (RFC 9728). | | `404` | [Problem](https://www.secblast.com/docs/reference/schemas#schema-problem) (`application/problem+json`) | No filing with this accession (code not_found); the filing's form is not covered by this route's dataset (code not_covered, with members form_type, dataset and routes: the routes that cover it); for a text route, no such item or section in the parsed filing (code not_found). | | `503` | [Problem](https://www.secblast.com/docs/reference/schemas#schema-problem) (`application/problem+json`) | Database unavailable; retry after the Retry-After delay. | | `default` | [Problem](https://www.secblast.com/docs/reference/schemas#schema-problem) (`application/problem+json`) | Any other error (405, 500, 504). | ## Response body A `200` carries a [F13fHoldingList](https://www.secblast.com/docs/reference/schemas#schema-f13fholdinglist) object. | Field | Type | Required | Description | |---|---|---|---| | `accession` | string | no | | | `data` | array of [F13fHolding](https://www.secblast.com/docs/reference/schemas#schema-f13fholding) | no | | | `extraction` | [Extraction](https://www.secblast.com/docs/reference/schemas#schema-extraction) | no | | | `filing` | [FilingRef](https://www.secblast.com/docs/reference/schemas#schema-filingref) | no | | | `has_more` | boolean | no | | | `next_cursor` | string \| null | no | | | `snapshot` | [Snapshot](https://www.secblast.com/docs/reference/schemas#schema-snapshot) | no | | | `value_unit` | [ValueUnit](https://www.secblast.com/docs/reference/schemas#schema-valueunit) | no | | ## Example request ```bash curl -sS -H "Authorization: Bearer $SECBLAST_API_KEY" \ 'https://api.secblast.com/v3/filings/0001829126-26-010431/13f/holdings' ``` [Open this route in the console](https://www.secblast.com/console#get-v3-filings-accession-13f-holdings) ## More in Institutional holdings (Form 13F) Previous: [`GET /v3/filings/{accession}/13f`](https://www.secblast.com/docs/reference/get-filings-accession-13f) · Next: [`GET /v3/ownership/institutional/holders`](https://www.secblast.com/docs/reference/get-ownership-institutional-holders) --- # GET /v3/ownership/institutional/holders The effective 13F rows of one CUSIP across managers for one period (as known at as_of), ordered by manager CIK, ledger step and row; options are their own rows. Matched against the normalised CUSIP as filed; no total. Rows of deleted (SEC-withdrawn) filings are left out; those filings are named in excluded. **API key:** required. See [Authentication](https://www.secblast.com/docs/authentication). **Group:** [Institutional holdings (Form 13F)](https://www.secblast.com/docs/reference#institutional-holdings-form-13f) ## Parameters | Name | In | Type | Required | Default | Description | |---|---|---|---|---|---| | `cusip` | query | string | yes | | Nine characters of 0-9, A-Z, \*, @, # (trimmed, upper-cased). Required. | | `period` | query | date (YYYY-MM-DD) | yes | | The report period, YYYY-MM-DD. Required. | | `put_call` | query | string | no | `any` | any, none (rows without an option), put, call. One of: `any`, `none`, `put`, `call`. | | `as_of` | query | string | no | | Inclusive: YYYY-MM-DDTHH:MM:SSZ (UTC, through the end of that second), YYYY-MM-DDTHH:MM:SS.ffffffZ (exact, 1-6 fraction digits) or YYYY-MM-DD (the whole UTC day). | | `limit` | query | integer | no | `200` | Page size, 1..1000. | | `cursor` | query | string | no | | Opaque cursor from a previous page's next_cursor. | ## Responses | Status | Body | Description | |---|---|---| | `200` | [F13fHolderList](https://www.secblast.com/docs/reference/schemas#schema-f13fholderlist) (`application/json`) | OK | | `400` | [Problem](https://www.secblast.com/docs/reference/schemas#schema-problem) (`application/problem+json`) | Invalid or unknown parameter. | | `401` | [Problem](https://www.secblast.com/docs/reference/schemas#schema-problem) (`application/problem+json`) | Missing, invalid or inactive API key (code unauthorized), or a refused access token (code invalid_token: malformed, unknown key, bad signature, expired, wrong issuer or audience, revoked grant). WWW-Authenticate names the protected-resource metadata (RFC 9728). | | `503` | [Problem](https://www.secblast.com/docs/reference/schemas#schema-problem) (`application/problem+json`) | Database unavailable; retry after the Retry-After delay. | | `default` | [Problem](https://www.secblast.com/docs/reference/schemas#schema-problem) (`application/problem+json`) | Any other error (405, 500, 504). | ## Response body A `200` carries a [F13fHolderList](https://www.secblast.com/docs/reference/schemas#schema-f13fholderlist) object. | Field | Type | Required | Description | |---|---|---|---| | `as_of` | string \| null | no | | | `cusip` | string | no | | | `data` | array of [F13fHolding](https://www.secblast.com/docs/reference/schemas#schema-f13fholding) + object | no | | | `excluded` | [Excluded](https://www.secblast.com/docs/reference/schemas#schema-excluded) | no | | | `excluded_total` | integer | no | | | `has_more` | boolean | no | | | `limits` | [F13fLimits](https://www.secblast.com/docs/reference/schemas#schema-f13flimits) | no | | | `next_cursor` | string \| null | no | | | `period` | date (YYYY-MM-DD) | no | | ## Example request ```bash curl -sS -H "Authorization: Bearer $SECBLAST_API_KEY" \ 'https://api.secblast.com/v3/ownership/institutional/holders' ``` [Open this route in the console](https://www.secblast.com/console#get-v3-ownership-institutional-holders) ## More in Institutional holdings (Form 13F) Previous: [`GET /v3/filings/{accession}/13f/holdings`](https://www.secblast.com/docs/reference/get-filings-accession-13f-holdings) · Next: [`GET /v3/ownership/institutional/managers/{cik}/holdings`](https://www.secblast.com/docs/reference/get-ownership-institutional-managers-cik-holdings) --- # GET /v3/ownership/institutional/managers/{cik}/holdings A 13F manager's holdings for one period: view=effective applies the amendment ledger (the last restatement or original, plus later additions) as known at as_of; view=as_filed lists the rows of every applied step. Each row carries its step, action, acceptance time, its filing's status (filing_status) and its own filing's unit decision. Deleted (SEC-withdrawn) filings: view=effective leaves them out (a deleted amendment does not amend; the remaining filings make the answer) and names them in excluded; view=as_filed lists their rows too (after the ledger's steps, step and applied_action null once the rebuilt ledger no longer names them) unless status leaves them out. 404 when nothing is known for the period at as_of. **API key:** required. See [Authentication](https://www.secblast.com/docs/authentication). **Group:** [Institutional holdings (Form 13F)](https://www.secblast.com/docs/reference#institutional-holdings-form-13f) ## Parameters | Name | In | Type | Required | Default | Description | |---|---|---|---|---|---| | `cik` | path | string | yes | | Manager CIK, padded or unpadded. | | `period` | query | date (YYYY-MM-DD) | yes | | The report period, YYYY-MM-DD. Required. | | `view` | query | string | no | `effective` | effective or as_filed. One of: `effective`, `as_filed`. | | `status` | query | comma-separated list of string | no | | With view=as_filed, status(es) of the rows' filings: provisional, final, deleted, comma-separated (as GET /v3/filings). Default: every status, deleted (SEC-withdrawn) filings included; status=final,provisional leaves them out. With view=effective it is a 400: the effective view always leaves deleted filings out and names them in excluded. | | `as_of` | query | string | no | | Inclusive: YYYY-MM-DDTHH:MM:SSZ (UTC, through the end of that second), YYYY-MM-DDTHH:MM:SS.ffffffZ (exact, 1-6 fraction digits) or YYYY-MM-DD (the whole UTC day). | | `limit` | query | integer | no | `200` | Page size, 1..1000. | | `cursor` | query | string | no | | Opaque cursor from a previous page's next_cursor. | ## Responses | Status | Body | Description | |---|---|---| | `200` | [F13fEffectiveHoldingList](https://www.secblast.com/docs/reference/schemas#schema-f13feffectiveholdinglist) (`application/json`) | OK | | `400` | [Problem](https://www.secblast.com/docs/reference/schemas#schema-problem) (`application/problem+json`) | Invalid or unknown parameter. | | `401` | [Problem](https://www.secblast.com/docs/reference/schemas#schema-problem) (`application/problem+json`) | Missing, invalid or inactive API key (code unauthorized), or a refused access token (code invalid_token: malformed, unknown key, bad signature, expired, wrong issuer or audience, revoked grant). WWW-Authenticate names the protected-resource metadata (RFC 9728). | | `404` | [Problem](https://www.secblast.com/docs/reference/schemas#schema-problem) (`application/problem+json`) | Not found. | | `503` | [Problem](https://www.secblast.com/docs/reference/schemas#schema-problem) (`application/problem+json`) | Database unavailable; retry after the Retry-After delay. | | `default` | [Problem](https://www.secblast.com/docs/reference/schemas#schema-problem) (`application/problem+json`) | Any other error (405, 500, 504). | ## Response body A `200` carries a [F13fEffectiveHoldingList](https://www.secblast.com/docs/reference/schemas#schema-f13feffectiveholdinglist) object. | Field | Type | Required | Description | |---|---|---|---| | `as_of` | string \| null | no | | | `confidential_omitted` | boolean | no | | | `data` | array of [F13fHolding](https://www.secblast.com/docs/reference/schemas#schema-f13fholding) + object | no | | | `effective` | object | no | | | `effective.reported_13f_long_value_usd` | [NullableDecimal](https://www.secblast.com/docs/reference/schemas#schema-nullabledecimal) | no | | | `effective.rows` | integer \| null | no | | | `excluded` | [Excluded](https://www.secblast.com/docs/reference/schemas#schema-excluded) | no | view=effective only. | | `excluded_total` | integer | no | view=effective only. | | `has_more` | boolean | no | | | `has_notice` | boolean | no | | | `ledger` | array of [LedgerStep](https://www.secblast.com/docs/reference/schemas#schema-ledgerstep) | no | | | `limits` | [F13fLimits](https://www.secblast.com/docs/reference/schemas#schema-f13flimits) | no | | | `manager_cik` | string | no | | | `next_cursor` | string \| null | no | | | `period` | date (YYYY-MM-DD) | no | | | `rebuild_pending` | boolean | no | A member filing was deleted since the group was built: its rows are not served and the total is null until the rebuild. | | `view` | string | no | One of: `effective`, `as_filed`. | ## Example request ```bash curl -sS -H "Authorization: Bearer $SECBLAST_API_KEY" \ 'https://api.secblast.com/v3/ownership/institutional/managers/320193/holdings' ``` The entity in this example is only an illustration. [Open this route in the console](https://www.secblast.com/console#get-v3-ownership-institutional-managers-cik-holdings) ## More in Institutional holdings (Form 13F) Previous: [`GET /v3/ownership/institutional/holders`](https://www.secblast.com/docs/reference/get-ownership-institutional-holders) · Next: [`GET /v3/ownership/institutional/managers/{cik}/periods`](https://www.secblast.com/docs/reference/get-ownership-institutional-managers-cik-periods) --- # GET /v3/ownership/institutional/managers/{cik}/periods One row per period a 13F manager filed for, newest first: ledger steps, base and latest filing, effective rows and reported 13F long value (not assets under management), flags. as_of gives the state as SEC had published it at that time (by acceptance time). Deleted (SEC-withdrawn) filings are left out: the remaining filings make each period, and the left-out filings are named in excluded (at most 20, with period; excluded_total counts them). 404 for a CIK with neither a 13F ledger row nor a deleted 13F filing. **API key:** required. See [Authentication](https://www.secblast.com/docs/authentication). **Group:** [Institutional holdings (Form 13F)](https://www.secblast.com/docs/reference#institutional-holdings-form-13f) ## Parameters | Name | In | Type | Required | Default | Description | |---|---|---|---|---|---| | `cik` | path | string | yes | | Manager CIK, padded or unpadded. | | `period_from` | query | date (YYYY-MM-DD) | no | | First period (inclusive), YYYY-MM-DD. | | `period_to` | query | date (YYYY-MM-DD) | no | | Last period (inclusive), YYYY-MM-DD. | | `as_of` | query | string | no | | YYYY-MM-DDTHH:MM:SSZ (UTC) or YYYY-MM-DD (the whole UTC day): only filings accepted by then. | | `limit` | query | integer | no | `50` | Page size, 1..200. | | `cursor` | query | string | no | | Opaque cursor from a previous page's next_cursor; bound to the filters (as_of included). | ## Responses | Status | Body | Description | |---|---|---| | `200` | [F13fManagerPeriodList](https://www.secblast.com/docs/reference/schemas#schema-f13fmanagerperiodlist) (`application/json`) | OK | | `400` | [Problem](https://www.secblast.com/docs/reference/schemas#schema-problem) (`application/problem+json`) | Invalid or unknown parameter. | | `401` | [Problem](https://www.secblast.com/docs/reference/schemas#schema-problem) (`application/problem+json`) | Missing, invalid or inactive API key (code unauthorized), or a refused access token (code invalid_token: malformed, unknown key, bad signature, expired, wrong issuer or audience, revoked grant). WWW-Authenticate names the protected-resource metadata (RFC 9728). | | `404` | [Problem](https://www.secblast.com/docs/reference/schemas#schema-problem) (`application/problem+json`) | Not found. | | `503` | [Problem](https://www.secblast.com/docs/reference/schemas#schema-problem) (`application/problem+json`) | Database unavailable; retry after the Retry-After delay. | | `default` | [Problem](https://www.secblast.com/docs/reference/schemas#schema-problem) (`application/problem+json`) | Any other error (405, 500, 504). | ## Response body A `200` carries a [F13fManagerPeriodList](https://www.secblast.com/docs/reference/schemas#schema-f13fmanagerperiodlist) object. | Field | Type | Required | Description | |---|---|---|---| | `as_of` | string \| null | no | | | `data` | array of [F13fManagerPeriod](https://www.secblast.com/docs/reference/schemas#schema-f13fmanagerperiod) | no | | | `excluded` | [Excluded](https://www.secblast.com/docs/reference/schemas#schema-excluded) | no | | | `excluded_total` | integer | no | | | `has_more` | boolean | no | | | `limits` | [F13fLimits](https://www.secblast.com/docs/reference/schemas#schema-f13flimits) | no | | | `manager_cik` | string | no | | | `next_cursor` | string \| null | no | | ## Example request ```bash curl -sS -H "Authorization: Bearer $SECBLAST_API_KEY" \ 'https://api.secblast.com/v3/ownership/institutional/managers/320193/periods' ``` The entity in this example is only an illustration. [Open this route in the console](https://www.secblast.com/console#get-v3-ownership-institutional-managers-cik-periods) ## More in Institutional holdings (Form 13F) Previous: [`GET /v3/ownership/institutional/managers/{cik}/holdings`](https://www.secblast.com/docs/reference/get-ownership-institutional-managers-cik-holdings) --- # GET /v3/filings/{accession}/144 A Form 144 notice (or 144/A) as filed: issuer with address and phone, seller (CIK from the SEC header's reporting owner; the form names the seller only), relationships, the securities proposed to be sold with broker and approximate sale date, how they were acquired, the seller's sales of the past three months, plan adoption dates, and the notice's amendment chain on previousAccessionNumber (provisional). A notice is not a sale. 404 not_covered for another form. **API key:** required. See [Authentication](https://www.secblast.com/docs/authentication). **Group:** [Proposed sales (Form 144)](https://www.secblast.com/docs/reference#proposed-sales-form-144) ## Parameters | Name | In | Type | Required | Default | Description | |---|---|---|---|---|---| | `accession` | path | string | yes | | Accession number, with dashes (0001829126-26-010431) or without (18 digits). | ## Responses | Status | Body | Description | |---|---|---| | `200` | [F144Filing](https://www.secblast.com/docs/reference/schemas#schema-f144filing) (`application/json`) | OK | | `400` | [Problem](https://www.secblast.com/docs/reference/schemas#schema-problem) (`application/problem+json`) | Invalid or unknown parameter. | | `401` | [Problem](https://www.secblast.com/docs/reference/schemas#schema-problem) (`application/problem+json`) | Missing, invalid or inactive API key (code unauthorized), or a refused access token (code invalid_token: malformed, unknown key, bad signature, expired, wrong issuer or audience, revoked grant). WWW-Authenticate names the protected-resource metadata (RFC 9728). | | `404` | [Problem](https://www.secblast.com/docs/reference/schemas#schema-problem) (`application/problem+json`) | No filing with this accession (code not_found); the filing's form is not covered by this route's dataset (code not_covered, with members form_type, dataset and routes: the routes that cover it); for a text route, no such item or section in the parsed filing (code not_found). | | `503` | [Problem](https://www.secblast.com/docs/reference/schemas#schema-problem) (`application/problem+json`) | Database unavailable; retry after the Retry-After delay. | | `default` | [Problem](https://www.secblast.com/docs/reference/schemas#schema-problem) (`application/problem+json`) | Any other error (405, 500, 504). | ## Response body A `200` carries a [F144Filing](https://www.secblast.com/docs/reference/schemas#schema-f144filing) object. | Field | Type | Required | Description | |---|---|---|---| | `accession` | string | no | | | `chain` | object \| null | no | | | `extraction` | [Extraction](https://www.secblast.com/docs/reference/schemas#schema-extraction) | no | | | `filing` | [FilingRef](https://www.secblast.com/docs/reference/schemas#schema-filingref) | no | | | `header_entities` | array of object | no | | | `limits` | array of string | no | | | `notice` | [F144Notice](https://www.secblast.com/docs/reference/schemas#schema-f144notice) | no | | | `snapshot` | [Snapshot](https://www.secblast.com/docs/reference/schemas#schema-snapshot) | no | | ## Example request ```bash curl -sS -H "Authorization: Bearer $SECBLAST_API_KEY" \ 'https://api.secblast.com/v3/filings/0001829126-26-010431/144' ``` [Open this route in the console](https://www.secblast.com/console#get-v3-filings-accession-144) ## More in Proposed sales (Form 144) Next: [`GET /v3/ownership/proposed-sales`](https://www.secblast.com/docs/reference/get-ownership-proposed-sales) --- # GET /v3/ownership/proposed-sales Form 144 notices across filings, newest first, each with its securities, acquisitions and past sales. view=effective (provisional) lists only the latest notice of each amendment chain known at as_of. A notice is not a sale. Deleted (SEC-withdrawn) notices: listed by view=as_filed (filing_status deleted) unless status leaves them out; left out of view=effective (a deleted 144/A does not amend) and named in excluded. **API key:** required. See [Authentication](https://www.secblast.com/docs/authentication). **Group:** [Proposed sales (Form 144)](https://www.secblast.com/docs/reference#proposed-sales-form-144) ## Parameters | Name | In | Type | Required | Default | Description | |---|---|---|---|---|---| | `issuer_cik` | query | string | no | | Issuer CIK, padded or unpadded. | | `seller_cik` | query | string | no | | Seller CIK (the SEC header's reporting owner), padded or unpadded. | | `filed_from` | query | date (YYYY-MM-DD) | no | | First filing date (inclusive), YYYY-MM-DD. | | `filed_to` | query | date (YYYY-MM-DD) | no | | Last filing date (inclusive), YYYY-MM-DD. | | `view` | query | string | no | `as_filed` | as_filed or effective (provisional). One of: `as_filed`, `effective`. | | `status` | query | comma-separated list of string | no | | With view=as_filed, status(es) of the rows' filings: provisional, final, deleted, comma-separated (as GET /v3/filings). Default: every status, deleted (SEC-withdrawn) filings included; status=final,provisional leaves them out. With view=effective it is a 400: the effective view always leaves deleted filings out and names them in excluded. | | `as_of` | query | string | no | | Inclusive: YYYY-MM-DDTHH:MM:SSZ (UTC, through the end of that second), YYYY-MM-DDTHH:MM:SS.ffffffZ (exact, 1-6 fraction digits) or YYYY-MM-DD (the whole UTC day). | | `limit` | query | integer | no | `50` | Page size, 1..200. | | `cursor` | query | string | no | | Opaque cursor from a previous page's next_cursor; bound to the filters (as_of included). | ## Responses | Status | Body | Description | |---|---|---| | `200` | [ProposedSaleList](https://www.secblast.com/docs/reference/schemas#schema-proposedsalelist) (`application/json`) | OK | | `400` | [Problem](https://www.secblast.com/docs/reference/schemas#schema-problem) (`application/problem+json`) | Invalid or unknown parameter. | | `401` | [Problem](https://www.secblast.com/docs/reference/schemas#schema-problem) (`application/problem+json`) | Missing, invalid or inactive API key (code unauthorized), or a refused access token (code invalid_token: malformed, unknown key, bad signature, expired, wrong issuer or audience, revoked grant). WWW-Authenticate names the protected-resource metadata (RFC 9728). | | `503` | [Problem](https://www.secblast.com/docs/reference/schemas#schema-problem) (`application/problem+json`) | Database unavailable; retry after the Retry-After delay. | | `default` | [Problem](https://www.secblast.com/docs/reference/schemas#schema-problem) (`application/problem+json`) | Any other error (405, 500, 504). | ## Response body A `200` carries a [ProposedSaleList](https://www.secblast.com/docs/reference/schemas#schema-proposedsalelist) object. | Field | Type | Required | Description | |---|---|---|---| | `as_of` | string \| null | no | | | `data` | array of [F144Notice](https://www.secblast.com/docs/reference/schemas#schema-f144notice) + object | no | | | `excluded` | [Excluded](https://www.secblast.com/docs/reference/schemas#schema-excluded) | no | view=effective only. | | `excluded_total` | integer | no | view=effective only. | | `has_more` | boolean | no | | | `limits` | array of string | no | | | `next_cursor` | string \| null | no | | | `provisional` | boolean | no | | | `view` | string | no | One of: `as_filed`, `effective`. | ## Example request ```bash curl -sS -H "Authorization: Bearer $SECBLAST_API_KEY" \ 'https://api.secblast.com/v3/ownership/proposed-sales' ``` [Open this route in the console](https://www.secblast.com/console#get-v3-ownership-proposed-sales) ## More in Proposed sales (Form 144) Previous: [`GET /v3/filings/{accession}/144`](https://www.secblast.com/docs/reference/get-filings-accession-144) --- # GET /v3/filings/{accession}/formd One Form D notice of an exempt offering as filed: offering (industry, exemptions, first sale, securities, minimum investment, the total offering amount, amount sold and remaining -- whole dollars, or Indefinite as filed -- investors, commissions, finders' fees, proceeds to related persons), every issuer, the related persons, the sales compensation recipients with their states, the header entities, and the offering chain (a D/A restates the whole notice: the chain's latest member is the offering). 404 not_covered for another form. **API key:** required. See [Authentication](https://www.secblast.com/docs/authentication). **Group:** [Exempt offerings (Form D)](https://www.secblast.com/docs/reference#exempt-offerings-form-d) ## Parameters | Name | In | Type | Required | Default | Description | |---|---|---|---|---|---| | `accession` | path | string | yes | | Accession number, with dashes (0001829126-26-010431) or without (18 digits). | ## Responses | Status | Body | Description | |---|---|---| | `200` | [FormDFiling](https://www.secblast.com/docs/reference/schemas#schema-formdfiling) (`application/json`) | OK | | `400` | [Problem](https://www.secblast.com/docs/reference/schemas#schema-problem) (`application/problem+json`) | Invalid or unknown parameter. | | `401` | [Problem](https://www.secblast.com/docs/reference/schemas#schema-problem) (`application/problem+json`) | Missing, invalid or inactive API key (code unauthorized), or a refused access token (code invalid_token: malformed, unknown key, bad signature, expired, wrong issuer or audience, revoked grant). WWW-Authenticate names the protected-resource metadata (RFC 9728). | | `404` | [Problem](https://www.secblast.com/docs/reference/schemas#schema-problem) (`application/problem+json`) | Not found. | | `503` | [Problem](https://www.secblast.com/docs/reference/schemas#schema-problem) (`application/problem+json`) | Database unavailable; retry after the Retry-After delay. | | `default` | [Problem](https://www.secblast.com/docs/reference/schemas#schema-problem) (`application/problem+json`) | Any other error (405, 500, 504). | ## Response body A `200` carries a [FormDFiling](https://www.secblast.com/docs/reference/schemas#schema-formdfiling) object. | Field | Type | Required | Description | |---|---|---|---| | `accession` | string | yes | | | `chain` | object \| null | yes | The offering chain: chain_id, members \[{accession, chain_seq, link_method root \| previous_accession \| issuer_file_number, form_type, filing_date, accepted_at, flags, filing_status}\], effective_accession (the latest member: its rows are the offering), steps, flags, derive_version, computed_at. | | `extraction` | object | yes | | | `filing` | object | yes | | | `header_entities` | array of object | yes | | | `issuers` | array of object | yes | | | `offering` | any | yes | | | `recipients` | array of object | yes | | | `related_persons` | array of object | yes | | | `snapshot` | object | yes | | ## Example request ```bash curl -sS -H "Authorization: Bearer $SECBLAST_API_KEY" \ 'https://api.secblast.com/v3/filings/0001829126-26-010431/formd' ``` [Open this route in the console](https://www.secblast.com/console#get-v3-filings-accession-formd) ## More in Exempt offerings (Form D) Next: [`GET /v3/offerings`](https://www.secblast.com/docs/reference/get-offerings) --- # GET /v3/offerings Form D notices across filings, newest first (filing date, accession). cik selects the notices naming that issuer (primary or additional). view=effective lists only the latest notice of each offering chain known at as_of: its amounts are the offering's (amount sold is cumulative as filed, never summed). Deleted (SEC-withdrawn) notices: listed by view=as_filed (filing_status deleted) unless status leaves them out; left out of view=effective and named in excluded. **API key:** required. See [Authentication](https://www.secblast.com/docs/authentication). **Group:** [Exempt offerings (Form D)](https://www.secblast.com/docs/reference#exempt-offerings-form-d) ## Parameters | Name | In | Type | Required | Default | Description | |---|---|---|---|---|---| | `cik` | query | string | no | | Issuer CIK (primary or additional issuer), padded or unpadded. | | `filed_from` | query | date (YYYY-MM-DD) | no | | First filing date (inclusive), YYYY-MM-DD. | | `filed_to` | query | date (YYYY-MM-DD) | no | | Last filing date (inclusive), YYYY-MM-DD. | | `view` | query | string | no | `as_filed` | as_filed or effective. One of: `as_filed`, `effective`. | | `status` | query | comma-separated list of string | no | | With view=as_filed, status(es) of the rows' filings: provisional, final, deleted, comma-separated (as GET /v3/filings). Default: every status, deleted (SEC-withdrawn) filings included; status=final,provisional leaves them out. With view=effective it is a 400: the effective view always leaves deleted filings out and names them in excluded. | | `as_of` | query | string | no | | Inclusive: YYYY-MM-DDTHH:MM:SSZ (UTC, through the end of that second), YYYY-MM-DDTHH:MM:SS.ffffffZ (exact, 1-6 fraction digits) or YYYY-MM-DD (the whole UTC day). | | `limit` | query | integer | no | `500` | Page size, 1..1000. | | `cursor` | query | string | no | | Opaque cursor from a previous page's next_cursor; bound to the filters (as_of included). | ## Responses | Status | Body | Description | |---|---|---| | `200` | [FormDOfferings](https://www.secblast.com/docs/reference/schemas#schema-formdofferings) (`application/json`) | OK | | `400` | [Problem](https://www.secblast.com/docs/reference/schemas#schema-problem) (`application/problem+json`) | Invalid or unknown parameter. | | `401` | [Problem](https://www.secblast.com/docs/reference/schemas#schema-problem) (`application/problem+json`) | Missing, invalid or inactive API key (code unauthorized), or a refused access token (code invalid_token: malformed, unknown key, bad signature, expired, wrong issuer or audience, revoked grant). WWW-Authenticate names the protected-resource metadata (RFC 9728). | | `503` | [Problem](https://www.secblast.com/docs/reference/schemas#schema-problem) (`application/problem+json`) | Database unavailable; retry after the Retry-After delay. | | `default` | [Problem](https://www.secblast.com/docs/reference/schemas#schema-problem) (`application/problem+json`) | Any other error (405, 500, 504). | ## Response body A `200` carries a [FormDOfferings](https://www.secblast.com/docs/reference/schemas#schema-formdofferings) object. | Field | Type | Required | Description | |---|---|---|---| | `as_of` | string \| null | yes | | | `cik` | string \| null | yes | | | `data` | array of object | yes | | | `excluded` | [Excluded](https://www.secblast.com/docs/reference/schemas#schema-excluded) | no | | | `excluded_total` | integer | no | | | `has_more` | boolean | yes | | | `next_cursor` | string \| null | yes | | | `view` | string | yes | One of: `as_filed`, `effective`. | ## Example request ```bash curl -sS -H "Authorization: Bearer $SECBLAST_API_KEY" \ 'https://api.secblast.com/v3/offerings' ``` [Open this route in the console](https://www.secblast.com/console#get-v3-offerings) ## More in Exempt offerings (Form D) Previous: [`GET /v3/filings/{accession}/formd`](https://www.secblast.com/docs/reference/get-filings-accession-formd) --- # GET /v3/filings/{accession}/nport One N-PORT report as filed: registrant, series, share classes, report date, total assets, liabilities and net assets, monthly flows (sales, reinvestment, redemption) and other gains, monthly total returns per class, its place in the report ledger (an NPORT-P/A restates the whole report: one filing per series and report date is effective), and a page of its holdings in document order: identifiers (CUSIP classified -- a placeholder is never a CUSIP -- ISIN, ticker, LEI, other), balance, units, currency, value in USD, percent of net assets, asset and issuer categories, country, fair value level, and debt, repo, derivative and lending detail as filed. Fund-level holdings: never summed with Form 13F. 404 not_covered for another form. **API key:** required. See [Authentication](https://www.secblast.com/docs/authentication). **Group:** [Fund holdings (Form N-PORT)](https://www.secblast.com/docs/reference#fund-holdings-form-n-port) ## Parameters | Name | In | Type | Required | Default | Description | |---|---|---|---|---|---| | `accession` | path | string | yes | | Accession number, with dashes (0001829126-26-010431) or without (18 digits). | | `limit` | query | integer | no | `500` | Holdings per page, 1..5000. | | `cursor` | query | string | no | | Opaque cursor from a previous page's next_cursor. | ## Responses | Status | Body | Description | |---|---|---| | `200` | [NportFiling](https://www.secblast.com/docs/reference/schemas#schema-nportfiling) (`application/json`) | OK | | `400` | [Problem](https://www.secblast.com/docs/reference/schemas#schema-problem) (`application/problem+json`) | Invalid or unknown parameter. | | `401` | [Problem](https://www.secblast.com/docs/reference/schemas#schema-problem) (`application/problem+json`) | Missing, invalid or inactive API key (code unauthorized), or a refused access token (code invalid_token: malformed, unknown key, bad signature, expired, wrong issuer or audience, revoked grant). WWW-Authenticate names the protected-resource metadata (RFC 9728). | | `404` | [Problem](https://www.secblast.com/docs/reference/schemas#schema-problem) (`application/problem+json`) | Not found. | | `503` | [Problem](https://www.secblast.com/docs/reference/schemas#schema-problem) (`application/problem+json`) | Database unavailable; retry after the Retry-After delay. | | `default` | [Problem](https://www.secblast.com/docs/reference/schemas#schema-problem) (`application/problem+json`) | Any other error (405, 500, 504). | ## Response body A `200` carries a [NportFiling](https://www.secblast.com/docs/reference/schemas#schema-nportfiling) object. | Field | Type | Required | Description | |---|---|---|---| | `accession` | string | yes | | | `extraction` | object | yes | | | `filing` | object | yes | | | `has_more` | boolean | yes | | | `holdings` | array of [NportHolding](https://www.secblast.com/docs/reference/schemas#schema-nportholding) | yes | | | `ledger` | object \| null | yes | series_id, report_date, step, applied_action base \| replace \| ignored_duplicate, applied_rule, flags, effective_accession, steps, is_effective. | | `limits` | array of string | yes | | | `next_cursor` | string \| null | yes | | | `report` | any | yes | | ## Example request ```bash curl -sS -H "Authorization: Bearer $SECBLAST_API_KEY" \ 'https://api.secblast.com/v3/filings/0001829126-26-010431/nport' ``` [Open this route in the console](https://www.secblast.com/console#get-v3-filings-accession-nport) ## More in Fund holdings (Form N-PORT) Next: [`GET /v3/funds/holdings`](https://www.secblast.com/docs/reference/get-funds-holdings) --- # GET /v3/funds/holdings The N-PORT holdings of one security across funds, newest filing first: exactly one of cusip (only rows whose filed CUSIP is nine characters), isin or ticker (the holding's identifiers as filed). view=effective (default): only the effective filing of each series and report date. Fund-level holdings: never summed with Form 13F. **API key:** required. See [Authentication](https://www.secblast.com/docs/authentication). **Group:** [Fund holdings (Form N-PORT)](https://www.secblast.com/docs/reference#fund-holdings-form-n-port) ## Parameters | Name | In | Type | Required | Default | Description | |---|---|---|---|---|---| | `cusip` | query | string | no | | Nine-character CUSIP. | | `isin` | query | string | no | | Twelve-character ISIN. | | `ticker` | query | string | no | | Ticker as filed in the holding's identifiers. | | `filed_from` | query | date (YYYY-MM-DD) | no | | First filing date (inclusive), YYYY-MM-DD. | | `filed_to` | query | date (YYYY-MM-DD) | no | | Last filing date (inclusive), YYYY-MM-DD. | | `view` | query | string | no | `effective` | effective or as_filed. One of: `effective`, `as_filed`. | | `limit` | query | integer | no | `500` | Page size, 1..1000. | | `cursor` | query | string | no | | Opaque cursor from a previous page's next_cursor; bound to the filters. | ## Responses | Status | Body | Description | |---|---|---| | `200` | [NportFundHoldings](https://www.secblast.com/docs/reference/schemas#schema-nportfundholdings) (`application/json`) | OK | | `400` | [Problem](https://www.secblast.com/docs/reference/schemas#schema-problem) (`application/problem+json`) | Invalid or unknown parameter. | | `401` | [Problem](https://www.secblast.com/docs/reference/schemas#schema-problem) (`application/problem+json`) | Missing, invalid or inactive API key (code unauthorized), or a refused access token (code invalid_token: malformed, unknown key, bad signature, expired, wrong issuer or audience, revoked grant). WWW-Authenticate names the protected-resource metadata (RFC 9728). | | `503` | [Problem](https://www.secblast.com/docs/reference/schemas#schema-problem) (`application/problem+json`) | Database unavailable; retry after the Retry-After delay. | | `default` | [Problem](https://www.secblast.com/docs/reference/schemas#schema-problem) (`application/problem+json`) | Any other error (405, 500, 504). | ## Response body A `200` carries a [NportFundHoldings](https://www.secblast.com/docs/reference/schemas#schema-nportfundholdings) object. | Field | Type | Required | Description | |---|---|---|---| | `data` | array of object | yes | | | `has_more` | boolean | yes | | | `id_type` | string | yes | | | `id_value` | string | yes | | | `limits` | array of string | yes | | | `next_cursor` | string \| null | yes | | | `view` | string | yes | One of: `effective`, `as_filed`. | ## Example request ```bash curl -sS -H "Authorization: Bearer $SECBLAST_API_KEY" \ 'https://api.secblast.com/v3/funds/holdings' ``` [Open this route in the console](https://www.secblast.com/console#get-v3-funds-holdings) ## More in Fund holdings (Form N-PORT) Previous: [`GET /v3/filings/{accession}/nport`](https://www.secblast.com/docs/reference/get-filings-accession-nport) · Next: [`GET /v3/funds/{series_id}/reports`](https://www.secblast.com/docs/reference/get-funds-series-id-reports) --- # GET /v3/funds/{series_id}/reports A fund series' N-PORT reports, newest report date first. view=effective (default): one filing per report date (the latest, which restates the whole report); as_filed: every filing. **API key:** required. See [Authentication](https://www.secblast.com/docs/authentication). **Group:** [Fund holdings (Form N-PORT)](https://www.secblast.com/docs/reference#fund-holdings-form-n-port) ## Parameters | Name | In | Type | Required | Default | Description | |---|---|---|---|---|---| | `series_id` | path | string | yes | | SEC series id, S followed by nine digits (S000040371). | | `from` | query | date (YYYY-MM-DD) | no | | First report date (inclusive), YYYY-MM-DD. | | `to` | query | date (YYYY-MM-DD) | no | | Last report date (inclusive), YYYY-MM-DD. | | `view` | query | string | no | `effective` | effective or as_filed. One of: `effective`, `as_filed`. | | `limit` | query | integer | no | `500` | Page size, 1..1000. | | `cursor` | query | string | no | | Opaque cursor from a previous page's next_cursor; bound to the filters. | ## Responses | Status | Body | Description | |---|---|---| | `200` | [NportSeriesReports](https://www.secblast.com/docs/reference/schemas#schema-nportseriesreports) (`application/json`) | OK | | `400` | [Problem](https://www.secblast.com/docs/reference/schemas#schema-problem) (`application/problem+json`) | Invalid or unknown parameter. | | `401` | [Problem](https://www.secblast.com/docs/reference/schemas#schema-problem) (`application/problem+json`) | Missing, invalid or inactive API key (code unauthorized), or a refused access token (code invalid_token: malformed, unknown key, bad signature, expired, wrong issuer or audience, revoked grant). WWW-Authenticate names the protected-resource metadata (RFC 9728). | | `503` | [Problem](https://www.secblast.com/docs/reference/schemas#schema-problem) (`application/problem+json`) | Database unavailable; retry after the Retry-After delay. | | `default` | [Problem](https://www.secblast.com/docs/reference/schemas#schema-problem) (`application/problem+json`) | Any other error (405, 500, 504). | ## Response body A `200` carries a [NportSeriesReports](https://www.secblast.com/docs/reference/schemas#schema-nportseriesreports) object. | Field | Type | Required | Description | |---|---|---|---| | `data` | array of [NportReport](https://www.secblast.com/docs/reference/schemas#schema-nportreport) | yes | | | `has_more` | boolean | yes | | | `next_cursor` | string \| null | yes | | | `series_id` | string | yes | | | `view` | string | yes | One of: `effective`, `as_filed`. | ## Example request ```bash curl -sS -H "Authorization: Bearer $SECBLAST_API_KEY" \ 'https://api.secblast.com/v3/funds/S000040371/reports' ``` [Open this route in the console](https://www.secblast.com/console#get-v3-funds-series-id-reports) ## More in Fund holdings (Form N-PORT) Previous: [`GET /v3/funds/holdings`](https://www.secblast.com/docs/reference/get-funds-holdings) --- # GET /v3/datasets The catalogue of parsed datasets: per dataset its extractor, forms, deployed version, derive steps, tables, status (available or in_preparation), coverage (the first and last filing date of successful results: a range, not a statement that every filing in it is parsed), estimated row counts, when it last changed, and its parse queue. Computed in the background, never by a request (at start, then every few minutes); computed_at says when. Until the first computation after a start the answer is 503 warming_up with Retry-After. Measured accuracy is not published. Cache-Control: public, max-age=300. **API key:** not needed. **Group:** [Datasets](https://www.secblast.com/docs/reference#datasets) ## Parameters This route takes no parameters. ## Responses | Status | Body | Description | |---|---|---| | `200` | [DatasetList](https://www.secblast.com/docs/reference/schemas#schema-datasetlist) (`application/json`) | OK | | `503` | [Problem](https://www.secblast.com/docs/reference/schemas#schema-problem) (`application/problem+json`) | Database unavailable (code db_unavailable); or the answer, which the server computes in the background, has not been computed yet since it started (code warming_up). Retry the same request after the Retry-After delay. | | `default` | [Problem](https://www.secblast.com/docs/reference/schemas#schema-problem) (`application/problem+json`) | Any other error (405, 500, 504). | ## Response body A `200` carries a [DatasetList](https://www.secblast.com/docs/reference/schemas#schema-datasetlist) object. | Field | Type | Required | Description | |---|---|---|---| | `computed_at` | date-time (RFC 3339, UTC) | yes | | | `data` | array of [Dataset](https://www.secblast.com/docs/reference/schemas#schema-dataset) | yes | | | `has_more` | boolean | yes | | | `next_cursor` | string \| null | yes | | ## Example request ```bash curl -sS 'https://api.secblast.com/v3/datasets' ``` [Open this route in the console](https://www.secblast.com/console#get-v3-datasets) --- # GET /v3/stream The filing stream: a cursor long-poll over every new, updated, corrected and deleted filing. **API key:** required. See [Authentication](https://www.secblast.com/docs/authentication). **Group:** [Filing stream](https://www.secblast.com/docs/reference#filing-stream) ## Parameters | Name | In | Type | Required | Default | Description | |---|---|---|---|---|---| | `after` | query | string | no | | A cursor (next_cursor of an earlier answer), or now. Omitted: the head. | | `wait` | query | integer | no | `25` | Seconds to hold the request while nothing matches, 0 to 30. | | `limit` | query | integer | no | `100` | Events per answer, 1 to 1000. | | `types` | query | comma-separated list of string | no | `filing.new,filing.corrected,filing.deleted` | Event types: filing.new, filing.updated, filing.corrected, filing.deleted, feed.day_closed. | | `detail` | query | string | no | `full` | summary (no document list) or full. One of: `summary`, `full`. | | `include_late` | query | string | no | `true` | Include filings first seen in the nightly feed (late: true). One of: `true`, `false`. | | `schema_version` | query | integer | no | `1` | The payload schema version; only 1 exists. | | `forms` | query | comma-separated list of string | no | | Root form types (EDGAR alias): 10-K matches 10-K, 10-K/A, 10-K405. A leading - excludes (forms=-3,-4,-5). | | `form_types` | query | comma-separated list of string | no | | Exact form types, for example 10-K/A. A leading - excludes. | | `form_families` | query | comma-separated list of string | no | | Root form types. A leading - excludes. | | `ciks` | query | comma-separated list of string | no | | CIKs (1 to 10 digits each, at most 1,024); any entity role. | | `tickers` | query | comma-separated list of string | no | | Tickers (at most 64), resolved to CIKs through the current SEC ticker list; an unknown ticker adds no CIK. | | `sics` | query | comma-separated list of string | no | | SIC codes; a \* suffix matches a prefix (73\*). | | `states` | query | comma-separated list of string | no | | Business-address state codes. | | `items` | query | comma-separated list of string | no | | 8-K item codes, exact (2.02). | ## Responses | Status | Body | Description | |---|---|---| | `200` | [StreamPage](https://www.secblast.com/docs/reference/schemas#schema-streampage) (`application/json`) | OK | | `400` | [Problem](https://www.secblast.com/docs/reference/schemas#schema-problem) (`application/problem+json`) | Invalid or unknown parameter (invalid_parameter, unknown_parameter), or an after that is not a cursor or is past the head (invalid_cursor). | | `401` | [Problem](https://www.secblast.com/docs/reference/schemas#schema-problem) (`application/problem+json`) | Missing, invalid or inactive API key. | | `403` | [Problem](https://www.secblast.com/docs/reference/schemas#schema-problem) (`application/problem+json`) | The plan of the key's organization does not include the stream (code plan_required; a legacy key follows the plan of the legacy organization), or the organization is suspended (code blocked). | | `410` | [Problem](https://www.secblast.com/docs/reference/schemas#schema-problem) (`application/problem+json`) | The cursor is older than the 30-day retention (code cursor_expired, with oldest_cursor). | | `429` | [Problem](https://www.secblast.com/docs/reference/schemas#schema-problem) (`application/problem+json`) | More requests at once than the plan's stream connections, per organization (per key for a legacy key); a waiting request counts (code rate_limited, reason stream_connections). | | `503` | [Problem](https://www.secblast.com/docs/reference/schemas#schema-problem) (`application/problem+json`) | Postgres cannot answer (code db_unavailable; reason cold_queue_full when the queue of reads for old cursors is full, entitlements_unknown when the plan of the key's organization cannot be read and has not been read before). Retry after the Retry-After delay. | | `default` | [Problem](https://www.secblast.com/docs/reference/schemas#schema-problem) (`application/problem+json`) | Any other error (405, 500, 504). | ## Response body A `200` carries a [StreamPage](https://www.secblast.com/docs/reference/schemas#schema-streampage) object. | Field | Type | Required | Description | |---|---|---|---| | `data` | array of [StreamEvent](https://www.secblast.com/docs/reference/schemas#schema-streamevent) | yes | In stream order (the order of emission, not acceptance order). | | `has_more` | boolean | yes | true when more events are waiting: ask again at once. | | `head_cursor` | string | yes | | | `live` | object | yes | | | `live.covered_until` | date-time (RFC 3339, UTC) \| null | no | | | `live.state` | string | no | The live ingest daemon's state, or down. | | `next_cursor` | string | yes | On every answer, an empty one included; with filters it moves past the events they dropped. | | `retention` | object | yes | | | `retention.days` | integer | no | | | `retention.oldest_cursor` | string \| null | no | | ## Example request ```bash curl -sS -H "Authorization: Bearer $SECBLAST_API_KEY" \ 'https://api.secblast.com/v3/stream' ``` [Open this route in the console](https://www.secblast.com/console#get-v3-stream) ## More in Filing stream Next: [`GET /v3/stream/status`](https://www.secblast.com/docs/reference/get-stream-status) --- # GET /v3/stream/status Stream state: the head cursor, live ingest state, sequencer lag and latency percentiles of the last hour and day. **API key:** not needed. **Group:** [Filing stream](https://www.secblast.com/docs/reference#filing-stream) ## Parameters This route takes no parameters. ## Responses | Status | Body | Description | |---|---|---| | `200` | [StreamStatus](https://www.secblast.com/docs/reference/schemas#schema-streamstatus) (`application/json`) | OK | | `default` | [Problem](https://www.secblast.com/docs/reference/schemas#schema-problem) (`application/problem+json`) | Any other error (405, 500, 503). | ## Response body A `200` carries a [StreamStatus](https://www.secblast.com/docs/reference/schemas#schema-streamstatus) object. | Field | Type | Required | Description | |---|---|---|---| | `head_cursor` | string | yes | | | `latency` | object | yes | Percentiles in seconds of live filing.new, over the last hour and the last 24 hours: from SEC's acceptance to the event, and from registration to the event. | | `latency.from_accepted` | object | no | | | `latency.from_registered` | object | no | | | `live` | object | yes | | | `live.covered_until` | date-time (RFC 3339, UTC) \| null | no | | | `live.state` | string | no | | | `retention` | object | yes | | | `retention.days` | integer | no | | | `retention.oldest_cursor` | string \| null | no | | | `sequencer` | object | yes | | | `sequencer.lag_events` | integer \| null | no | | | `sequencer.lag_seconds` | number \| null | no | | | `sequencer.leading` | boolean \| null | no | | ## Example request ```bash curl -sS 'https://api.secblast.com/v3/stream/status' ``` [Open this route in the console](https://www.secblast.com/console#get-v3-stream-status) ## More in Filing stream Previous: [`GET /v3/stream`](https://www.secblast.com/docs/reference/get-stream) --- # GET /v3/callbacks/deliveries The organization's webhook deliveries, newest first (created_at, then id), with the attempt count, the last status and error, when the next attempt is due (only while pending) and the bytes billed. Filters: endpoint_id, subscription_id, state, type, accession, from (inclusive) and to (exclusive) on created_at. An endpoint_id or subscription_id that is not the organization's is 404. Deliveries are kept 30 days after their final state. 503 callbacks_unavailable while this server has no callback key file or its database lacks the callback tables. **API key:** required. See [Authentication](https://www.secblast.com/docs/authentication). **Group:** [Webhooks (API: callbacks)](https://www.secblast.com/docs/reference#webhooks-api-callbacks) ## Parameters | Name | In | Type | Required | Default | Description | |---|---|---|---|---|---| | `endpoint_id` | query | string | no | | Only deliveries to this endpoint (cbe_ and 24 hex digits). | | `subscription_id` | query | string | no | | Only deliveries of this subscription (sub_ and 24 hex digits). | | `state` | query | string | no | | Only deliveries in this state. One of: `pending`, `held`, `delivering`, `delivered`, `failed`, `dropped`. | | `type` | query | string | no | | Only this event type, for example filing.new. | | `accession` | query | string | no | | Only deliveries about this filing (0000000000-00-000000 or 18 digits). | | `from` | query | string | no | | created_at at or after this time (YYYY-MM-DDTHH:MM:SSZ, or YYYY-MM-DD for midnight UTC). | | `to` | query | string | no | | created_at before this time (same forms). | | `cursor` | query | string | no | | Opaque cursor from a previous page's next_cursor (GET). | | `limit` | query | integer | no | `20` | Page size, 1..100. | ## Responses | Status | Body | Description | |---|---|---| | `200` | [CallbackDeliveryList](https://www.secblast.com/docs/reference/schemas#schema-callbackdeliverylist) (`application/json`) | OK | | `400` | [Problem](https://www.secblast.com/docs/reference/schemas#schema-problem) (`application/problem+json`) | Invalid or unknown parameter. | | `401` | [Problem](https://www.secblast.com/docs/reference/schemas#schema-problem) (`application/problem+json`) | Missing, invalid or inactive API key (code unauthorized), or a refused access token (code invalid_token: malformed, unknown key, bad signature, expired, wrong issuer or audience, revoked grant). WWW-Authenticate names the protected-resource metadata (RFC 9728). | | `403` | [Problem](https://www.secblast.com/docs/reference/schemas#schema-problem) (`application/problem+json`) | The credential's scope does not cover this route (code forbidden), or the organization's plan has no callbacks (code plan_required). | | `404` | [Problem](https://www.secblast.com/docs/reference/schemas#schema-problem) (`application/problem+json`) | Not found. | | `503` | [Problem](https://www.secblast.com/docs/reference/schemas#schema-problem) (`application/problem+json`) | Callbacks are not available: this server has no callback key file or its database lacks the callback tables (code callbacks_unavailable); too many callback URLs are being checked at once (code db_unavailable, reason resolver_busy, Retry-After 1); or the database is unavailable (code db_unavailable). | | `default` | [Problem](https://www.secblast.com/docs/reference/schemas#schema-problem) (`application/problem+json`) | Any other error (405, 500, 504). | ## Response body A `200` carries a [CallbackDeliveryList](https://www.secblast.com/docs/reference/schemas#schema-callbackdeliverylist) object. | Field | Type | Required | Description | |---|---|---|---| | `data` | array of [CallbackDelivery](https://www.secblast.com/docs/reference/schemas#schema-callbackdelivery) | yes | | | `next_cursor` | string \| null | yes | Pass it as cursor for the next page; null on the last page. | ## Example request ```bash curl -sS -H "Authorization: Bearer $SECBLAST_API_KEY" \ 'https://api.secblast.com/v3/callbacks/deliveries' ``` [Open this route in the console](https://www.secblast.com/console#get-v3-callbacks-deliveries) ## More in Webhooks (API: callbacks) Next: [`GET /v3/callbacks/deliveries/{id}`](https://www.secblast.com/docs/reference/get-callbacks-deliveries-id) --- # GET /v3/callbacks/deliveries/{id} One delivery of the organization with its payload and every attempt (n, at, duration_ms, http_status, error_class, remote_ip, response_excerpt), oldest first. Another organization's delivery is 404. 503 callbacks_unavailable while this server has no callback key file or its database lacks the callback tables. **API key:** required. See [Authentication](https://www.secblast.com/docs/authentication). **Group:** [Webhooks (API: callbacks)](https://www.secblast.com/docs/reference#webhooks-api-callbacks) ## Parameters | Name | In | Type | Required | Default | Description | |---|---|---|---|---|---| | `id` | path | string | yes | | The delivery's id (dlv_ and 24 hex digits). | ## Responses | Status | Body | Description | |---|---|---| | `200` | [CallbackDeliveryDetail](https://www.secblast.com/docs/reference/schemas#schema-callbackdeliverydetail) (`application/json`) | OK | | `400` | [Problem](https://www.secblast.com/docs/reference/schemas#schema-problem) (`application/problem+json`) | Invalid or unknown parameter. | | `401` | [Problem](https://www.secblast.com/docs/reference/schemas#schema-problem) (`application/problem+json`) | Missing, invalid or inactive API key (code unauthorized), or a refused access token (code invalid_token: malformed, unknown key, bad signature, expired, wrong issuer or audience, revoked grant). WWW-Authenticate names the protected-resource metadata (RFC 9728). | | `403` | [Problem](https://www.secblast.com/docs/reference/schemas#schema-problem) (`application/problem+json`) | The credential's scope does not cover this route (code forbidden), or the organization's plan has no callbacks (code plan_required). | | `404` | [Problem](https://www.secblast.com/docs/reference/schemas#schema-problem) (`application/problem+json`) | Not found. | | `503` | [Problem](https://www.secblast.com/docs/reference/schemas#schema-problem) (`application/problem+json`) | Callbacks are not available: this server has no callback key file or its database lacks the callback tables (code callbacks_unavailable); too many callback URLs are being checked at once (code db_unavailable, reason resolver_busy, Retry-After 1); or the database is unavailable (code db_unavailable). | | `default` | [Problem](https://www.secblast.com/docs/reference/schemas#schema-problem) (`application/problem+json`) | Any other error (405, 500, 504). | ## Response body A `200` carries a [CallbackDeliveryDetail](https://www.secblast.com/docs/reference/schemas#schema-callbackdeliverydetail) object. | Field | Type | Required | Description | |---|---|---|---| | `accession` | string \| null | yes | The filing's accession number, for filing events. | | `attempt_count` | integer | yes | Attempts made so far; a manual retry or a replay continues the count. | | `billed_bytes` | integer | yes | The payload bytes billed: the payload size once the endpoint answered 2xx, else 0. Failed attempts, test events and endpoint verification are not billed. | | `created_at` | date-time (RFC 3339, UTC) | yes | | | `delivered_at` | date-time (RFC 3339, UTC) \| null | yes | | | `endpoint_id` | string | yes | cbe_ and 24 hex digits. | | `held_reason` | string \| null | yes | Only while state is held. One of: `quota_exceeded`, `plan_required`, `endpoint_disabled`, `endpoint_unverified`, `digest`, `null`. | | `id` | string | yes | dlv_ and 24 hex digits. | | `last_attempt_at` | date-time (RFC 3339, UTC) \| null | yes | When the newest attempt was made; null before the first. | | `last_error` | string \| null | yes | Why the last attempt failed (an error class such as timeout, or gone, quota_exceeded, plan_required, hold_expired, endpoint_inactive, superseded: a verification challenge replaced by a newer one before it was sent). | | `last_status` | integer \| null | yes | The HTTP status of the last attempt that got one. | | `next_attempt_at` | date-time (RFC 3339, UTC) \| null | yes | When the next attempt is due; only while state is pending. | | `state` | string | yes | pending: waiting for its next attempt. held: waiting for a condition (held_reason). delivering: an attempt is in flight. delivered: the endpoint answered 2xx. failed: every attempt failed, or the endpoint answered 410, or a hold ran out (last_error says which). dropped: the endpoint was inactive or the hold on an unverified or disabled endpoint ran out, or (a verification) a newer challenge replaced it. One of: `pending`, `held`, `delivering`, `delivered`, `failed`, `dropped`. | | `subscription_id` | string \| null | yes | sub_ and 24 hex digits; null for an event that belongs to no subscription. | | `type` | string | yes | The event type, for example filing.new. | | `attempts` | array of [CallbackAttempt](https://www.secblast.com/docs/reference/schemas#schema-callbackattempt) | yes | Every attempt, oldest first; empty before the first. | | `payload` | object | yes | The event as sent, the body of the request. | ## Example request ```bash curl -sS -H "Authorization: Bearer $SECBLAST_API_KEY" \ 'https://api.secblast.com/v3/callbacks/deliveries/dlv_0123456789abcdef01234567' ``` [Open this route in the console](https://www.secblast.com/console#get-v3-callbacks-deliveries-id) ## More in Webhooks (API: callbacks) Previous: [`GET /v3/callbacks/deliveries`](https://www.secblast.com/docs/reference/get-callbacks-deliveries) · Next: [`POST /v3/callbacks/deliveries/{id}/retry`](https://www.secblast.com/docs/reference/post-callbacks-deliveries-id-retry) --- # POST /v3/callbacks/deliveries/{id}/retry Queues one more attempt of a failed delivery now (202, the delivery): it becomes pending and its attempts are not reset. At most twice per delivery (409 limit_reached). Only a failed delivery that was never billed: any other state, a test delivery and an endpoint verification are 409 invalid_state. 403 plan_required for a plan without deliveries; 409 endpoint_unverified or endpoint_disabled while the endpoint cannot be sent to. The body is optional and has no members. 503 callbacks_unavailable while this server has no callback key file or its database lacks the callback tables. **API key:** required. See [Authentication](https://www.secblast.com/docs/authentication). **Group:** [Webhooks (API: callbacks)](https://www.secblast.com/docs/reference#webhooks-api-callbacks) ## Parameters | Name | In | Type | Required | Default | Description | |---|---|---|---|---|---| | `id` | path | string | yes | | The delivery's id (dlv_ and 24 hex digits). | ## Request body A [CallbackRetryRequest](https://www.secblast.com/docs/reference/schemas#schema-callbackretryrequest) object, as JSON. ## Responses | Status | Body | Description | |---|---|---| | `202` | [CallbackDelivery](https://www.secblast.com/docs/reference/schemas#schema-callbackdelivery) (`application/json`) | OK | | `400` | [Problem](https://www.secblast.com/docs/reference/schemas#schema-problem) (`application/problem+json`) | Invalid or unknown parameter, or a body that is not one JSON document (code invalid_body). | | `401` | [Problem](https://www.secblast.com/docs/reference/schemas#schema-problem) (`application/problem+json`) | Missing, invalid or inactive API key (code unauthorized), or a refused access token (code invalid_token: malformed, unknown key, bad signature, expired, wrong issuer or audience, revoked grant). WWW-Authenticate names the protected-resource metadata (RFC 9728). | | `403` | [Problem](https://www.secblast.com/docs/reference/schemas#schema-problem) (`application/problem+json`) | The credential's scope does not cover this route (code forbidden), or the organization's plan has no webhook deliveries (code plan_required). | | `404` | [Problem](https://www.secblast.com/docs/reference/schemas#schema-problem) (`application/problem+json`) | Not found. | | `409` | [Problem](https://www.secblast.com/docs/reference/schemas#schema-problem) (`application/problem+json`) | invalid_state: the delivery is not failed, or it was billed, or it is a test delivery or an endpoint verification; limit_reached (kind manual_retries, limit, used): the delivery was retried by hand twice already; replay_running (Retry-After): a replay of this endpoint started less than 60 seconds ago; endpoint_unverified or endpoint_disabled: the endpoint cannot be sent to now. | | `415` | [Problem](https://www.secblast.com/docs/reference/schemas#schema-problem) (`application/problem+json`) | The body is not sent as Content-Type: application/json (code unsupported_media_type). | | `503` | [Problem](https://www.secblast.com/docs/reference/schemas#schema-problem) (`application/problem+json`) | Callbacks are not available: this server has no callback key file or its database lacks the callback tables (code callbacks_unavailable); too many callback URLs are being checked at once (code db_unavailable, reason resolver_busy, Retry-After 1); or the database is unavailable (code db_unavailable). | | `default` | [Problem](https://www.secblast.com/docs/reference/schemas#schema-problem) (`application/problem+json`) | Any other error (405, 500, 504). | ## Response body A `202` carries a [CallbackDelivery](https://www.secblast.com/docs/reference/schemas#schema-callbackdelivery) object. | Field | Type | Required | Description | |---|---|---|---| | `accession` | string \| null | yes | The filing's accession number, for filing events. | | `attempt_count` | integer | yes | Attempts made so far; a manual retry or a replay continues the count. | | `billed_bytes` | integer | yes | The payload bytes billed: the payload size once the endpoint answered 2xx, else 0. Failed attempts, test events and endpoint verification are not billed. | | `created_at` | date-time (RFC 3339, UTC) | yes | | | `delivered_at` | date-time (RFC 3339, UTC) \| null | yes | | | `endpoint_id` | string | yes | cbe_ and 24 hex digits. | | `held_reason` | string \| null | yes | Only while state is held. One of: `quota_exceeded`, `plan_required`, `endpoint_disabled`, `endpoint_unverified`, `digest`, `null`. | | `id` | string | yes | dlv_ and 24 hex digits. | | `last_attempt_at` | date-time (RFC 3339, UTC) \| null | yes | When the newest attempt was made; null before the first. | | `last_error` | string \| null | yes | Why the last attempt failed (an error class such as timeout, or gone, quota_exceeded, plan_required, hold_expired, endpoint_inactive, superseded: a verification challenge replaced by a newer one before it was sent). | | `last_status` | integer \| null | yes | The HTTP status of the last attempt that got one. | | `next_attempt_at` | date-time (RFC 3339, UTC) \| null | yes | When the next attempt is due; only while state is pending. | | `state` | string | yes | pending: waiting for its next attempt. held: waiting for a condition (held_reason). delivering: an attempt is in flight. delivered: the endpoint answered 2xx. failed: every attempt failed, or the endpoint answered 410, or a hold ran out (last_error says which). dropped: the endpoint was inactive or the hold on an unverified or disabled endpoint ran out, or (a verification) a newer challenge replaced it. One of: `pending`, `held`, `delivering`, `delivered`, `failed`, `dropped`. | | `subscription_id` | string \| null | yes | sub_ and 24 hex digits; null for an event that belongs to no subscription. | | `type` | string | yes | The event type, for example filing.new. | ## Example request ```bash curl -sS -X POST -H "Authorization: Bearer $SECBLAST_API_KEY" \ -H "Content-Type: application/json" -d @body.json \ 'https://api.secblast.com/v3/callbacks/deliveries/dlv_0123456789abcdef01234567/retry' ``` ## More in Webhooks (API: callbacks) Previous: [`GET /v3/callbacks/deliveries/{id}`](https://www.secblast.com/docs/reference/get-callbacks-deliveries-id) · Next: [`GET /v3/callbacks/endpoints`](https://www.secblast.com/docs/reference/get-callbacks-endpoints) --- # GET /v3/callbacks/endpoints The organization's webhook endpoints, newest first, with limits.endpoints (the plan's limit and the active endpoints), each with its health and last 24 hours of deliveries. 403 plan_required for a plan without callbacks. 503 callbacks_unavailable while this server has no callback key file or its database lacks the callback tables. **API key:** required. See [Authentication](https://www.secblast.com/docs/authentication). **Group:** [Webhooks (API: callbacks)](https://www.secblast.com/docs/reference#webhooks-api-callbacks) ## Parameters | Name | In | Type | Required | Default | Description | |---|---|---|---|---|---| | `limit` | query | integer | no | `50` | Page size, 1..100 (GET). | | `cursor` | query | string | no | | Opaque cursor from a previous page's next_cursor (GET). | ## Responses | Status | Body | Description | |---|---|---| | `200` | [CallbackEndpointList](https://www.secblast.com/docs/reference/schemas#schema-callbackendpointlist) (`application/json`) | OK | | `400` | [Problem](https://www.secblast.com/docs/reference/schemas#schema-problem) (`application/problem+json`) | Invalid or unknown parameter. | | `401` | [Problem](https://www.secblast.com/docs/reference/schemas#schema-problem) (`application/problem+json`) | Missing, invalid or inactive API key (code unauthorized), or a refused access token (code invalid_token: malformed, unknown key, bad signature, expired, wrong issuer or audience, revoked grant). WWW-Authenticate names the protected-resource metadata (RFC 9728). | | `403` | [Problem](https://www.secblast.com/docs/reference/schemas#schema-problem) (`application/problem+json`) | The credential's scope does not cover this route (code forbidden), or the organization's plan has no callbacks (code plan_required). | | `409` | [Problem](https://www.secblast.com/docs/reference/schemas#schema-problem) (`application/problem+json`) | The plan's limit of active endpoints is reached (code limit_reached, with members kind, limit and used); or the endpoint changed while a PATCH was being checked (code conflict: retry). | | `503` | [Problem](https://www.secblast.com/docs/reference/schemas#schema-problem) (`application/problem+json`) | Callbacks are not available: this server has no callback key file or its database lacks the callback tables (code callbacks_unavailable); too many callback URLs are being checked at once (code db_unavailable, reason resolver_busy, Retry-After 1); or the database is unavailable (code db_unavailable). | | `default` | [Problem](https://www.secblast.com/docs/reference/schemas#schema-problem) (`application/problem+json`) | Any other error (405, 500, 504). | ## Response body A `200` carries a [CallbackEndpointList](https://www.secblast.com/docs/reference/schemas#schema-callbackendpointlist) object. | Field | Type | Required | Description | |---|---|---|---| | `data` | array of [CallbackEndpoint](https://www.secblast.com/docs/reference/schemas#schema-callbackendpoint) | yes | | | `has_more` | boolean | yes | | | `limits` | object | yes | | | `limits.endpoints` | object | no | | | `limits.endpoints.limit` | integer \| null | no | The plan's limit; 0 without callbacks. | | `limits.endpoints.used` | integer | no | Active endpoints. | | `next_cursor` | string \| null | yes | | ## Example request ```bash curl -sS -H "Authorization: Bearer $SECBLAST_API_KEY" \ 'https://api.secblast.com/v3/callbacks/endpoints' ``` [Open this route in the console](https://www.secblast.com/console#get-v3-callbacks-endpoints) ## More in Webhooks (API: callbacks) Previous: [`POST /v3/callbacks/deliveries/{id}/retry`](https://www.secblast.com/docs/reference/post-callbacks-deliveries-id-retry) · Next: [`POST /v3/callbacks/endpoints`](https://www.secblast.com/docs/reference/post-callbacks-endpoints) --- # POST /v3/callbacks/endpoints Create a webhook endpoint. **API key:** required. See [Authentication](https://www.secblast.com/docs/authentication). **Group:** [Webhooks (API: callbacks)](https://www.secblast.com/docs/reference#webhooks-api-callbacks) ## Parameters This route takes no parameters. ## Request body A [CallbackEndpointCreate](https://www.secblast.com/docs/reference/schemas#schema-callbackendpointcreate) object, as JSON. | Field | Type | Required | Description | |---|---|---|---| | `description` | string \| null | no | At most 800 bytes. | | `event_types` | array of string | yes | | | `url` | string | yes | https only, port 443 only, no user name or password, a public DNS name (not an IP address, localhost, .local or .internal) of letters, digits and hyphens (an international name in its xn-- form) that resolves to a public address; at most 2,048 characters. | ## Responses | Status | Body | Description | |---|---|---| | `201` | [CallbackEndpointCreated](https://www.secblast.com/docs/reference/schemas#schema-callbackendpointcreated) (`application/json`) | Created | | `400` | [Problem](https://www.secblast.com/docs/reference/schemas#schema-problem) (`application/problem+json`) | Invalid or unknown parameter, or a body that is not one JSON document (code invalid_body). | | `401` | [Problem](https://www.secblast.com/docs/reference/schemas#schema-problem) (`application/problem+json`) | Missing, invalid or inactive API key (code unauthorized), or a refused access token (code invalid_token: malformed, unknown key, bad signature, expired, wrong issuer or audience, revoked grant). WWW-Authenticate names the protected-resource metadata (RFC 9728). | | `403` | [Problem](https://www.secblast.com/docs/reference/schemas#schema-problem) (`application/problem+json`) | The credential's scope does not cover this route (code forbidden), or the organization's plan has no callbacks (code plan_required). | | `409` | [Problem](https://www.secblast.com/docs/reference/schemas#schema-problem) (`application/problem+json`) | The plan's limit of active endpoints is reached (code limit_reached, with members kind, limit and used); or the endpoint changed while a PATCH was being checked (code conflict: retry). | | `415` | [Problem](https://www.secblast.com/docs/reference/schemas#schema-problem) (`application/problem+json`) | The body is not sent as Content-Type: application/json (code unsupported_media_type). | | `503` | [Problem](https://www.secblast.com/docs/reference/schemas#schema-problem) (`application/problem+json`) | Callbacks are not available: this server has no callback key file or its database lacks the callback tables (code callbacks_unavailable); too many callback URLs are being checked at once (code db_unavailable, reason resolver_busy, Retry-After 1); or the database is unavailable (code db_unavailable). | | `default` | [Problem](https://www.secblast.com/docs/reference/schemas#schema-problem) (`application/problem+json`) | Any other error (405, 500, 504). | ## Response body A `201` carries a [CallbackEndpointCreated](https://www.secblast.com/docs/reference/schemas#schema-callbackendpointcreated) object. | Field | Type | Required | Description | |---|---|---|---| | `active` | boolean | yes | | | `created_at` | date-time (RFC 3339, UTC) | yes | | | `description` | string \| null | yes | | | `event_types` | array of string | yes | | | `health` | object | yes | | | `health.consecutive_failures` | integer | no | | | `health.disabled_at` | date-time (RFC 3339, UTC) \| null | no | | | `health.disabled_reason` | string \| null | no | | | `health.failing_since` | date-time (RFC 3339, UTC) \| null | no | | | `health.last_success_at` | date-time (RFC 3339, UTC) \| null | no | | | `health.state` | string | yes | One of: `unverified`, `active`, `failing`, `disabled`. | | `health.verified_at` | date-time (RFC 3339, UTC) \| null | no | | | `id` | string | yes | cbe_ and 24 hex digits. | | `last_24h` | object | yes | Deliveries of the last 24 hours by state. | | `last_24h.delivered` | integer | no | | | `last_24h.dropped` | integer | no | | | `last_24h.failed` | integer | no | | | `last_24h.held` | integer | no | | | `updated_at` | date-time (RFC 3339, UTC) | yes | | | `url` | string | yes | As stored: https, the host in lower case, no :443, / for an empty path. | | `secret` | string | yes | whsec_ and the standard base64 (with padding) of 32 random bytes: the Standard Webhooks signing secret. Shown only in this answer. | ## Example request ```bash curl -sS -X POST -H "Authorization: Bearer $SECBLAST_API_KEY" \ -H "Content-Type: application/json" -d @body.json \ 'https://api.secblast.com/v3/callbacks/endpoints' ``` ## More in Webhooks (API: callbacks) Previous: [`GET /v3/callbacks/endpoints`](https://www.secblast.com/docs/reference/get-callbacks-endpoints) · Next: [`GET /v3/callbacks/endpoints/{id}`](https://www.secblast.com/docs/reference/get-callbacks-endpoints-id) --- # GET /v3/callbacks/endpoints/{id} One webhook endpoint of the organization. Another organization's endpoint is 404. 503 callbacks_unavailable while this server has no callback key file or its database lacks the callback tables. **API key:** required. See [Authentication](https://www.secblast.com/docs/authentication). **Group:** [Webhooks (API: callbacks)](https://www.secblast.com/docs/reference#webhooks-api-callbacks) ## Parameters | Name | In | Type | Required | Default | Description | |---|---|---|---|---|---| | `id` | path | string | yes | | The endpoint's id (cbe_ and 24 hex digits). | ## Responses | Status | Body | Description | |---|---|---| | `200` | [CallbackEndpoint](https://www.secblast.com/docs/reference/schemas#schema-callbackendpoint) (`application/json`) | OK | | `400` | [Problem](https://www.secblast.com/docs/reference/schemas#schema-problem) (`application/problem+json`) | Invalid or unknown parameter. | | `401` | [Problem](https://www.secblast.com/docs/reference/schemas#schema-problem) (`application/problem+json`) | Missing, invalid or inactive API key (code unauthorized), or a refused access token (code invalid_token: malformed, unknown key, bad signature, expired, wrong issuer or audience, revoked grant). WWW-Authenticate names the protected-resource metadata (RFC 9728). | | `403` | [Problem](https://www.secblast.com/docs/reference/schemas#schema-problem) (`application/problem+json`) | The credential's scope does not cover this route (code forbidden), or the organization's plan has no callbacks (code plan_required). | | `404` | [Problem](https://www.secblast.com/docs/reference/schemas#schema-problem) (`application/problem+json`) | Not found. | | `409` | [Problem](https://www.secblast.com/docs/reference/schemas#schema-problem) (`application/problem+json`) | The plan's limit of active endpoints is reached (code limit_reached, with members kind, limit and used); or the endpoint changed while a PATCH was being checked (code conflict: retry). | | `503` | [Problem](https://www.secblast.com/docs/reference/schemas#schema-problem) (`application/problem+json`) | Callbacks are not available: this server has no callback key file or its database lacks the callback tables (code callbacks_unavailable); too many callback URLs are being checked at once (code db_unavailable, reason resolver_busy, Retry-After 1); or the database is unavailable (code db_unavailable). | | `default` | [Problem](https://www.secblast.com/docs/reference/schemas#schema-problem) (`application/problem+json`) | Any other error (405, 500, 504). | ## Response body A `200` carries a [CallbackEndpoint](https://www.secblast.com/docs/reference/schemas#schema-callbackendpoint) object. | Field | Type | Required | Description | |---|---|---|---| | `active` | boolean | yes | | | `created_at` | date-time (RFC 3339, UTC) | yes | | | `description` | string \| null | yes | | | `event_types` | array of string | yes | | | `health` | object | yes | | | `health.consecutive_failures` | integer | no | | | `health.disabled_at` | date-time (RFC 3339, UTC) \| null | no | | | `health.disabled_reason` | string \| null | no | | | `health.failing_since` | date-time (RFC 3339, UTC) \| null | no | | | `health.last_success_at` | date-time (RFC 3339, UTC) \| null | no | | | `health.state` | string | yes | One of: `unverified`, `active`, `failing`, `disabled`. | | `health.verified_at` | date-time (RFC 3339, UTC) \| null | no | | | `id` | string | yes | cbe_ and 24 hex digits. | | `last_24h` | object | yes | Deliveries of the last 24 hours by state. | | `last_24h.delivered` | integer | no | | | `last_24h.dropped` | integer | no | | | `last_24h.failed` | integer | no | | | `last_24h.held` | integer | no | | | `updated_at` | date-time (RFC 3339, UTC) | yes | | | `url` | string | yes | As stored: https, the host in lower case, no :443, / for an empty path. | ## Example request ```bash curl -sS -H "Authorization: Bearer $SECBLAST_API_KEY" \ 'https://api.secblast.com/v3/callbacks/endpoints/cbe_0123456789abcdef01234567' ``` [Open this route in the console](https://www.secblast.com/console#get-v3-callbacks-endpoints-id) ## More in Webhooks (API: callbacks) Previous: [`POST /v3/callbacks/endpoints`](https://www.secblast.com/docs/reference/post-callbacks-endpoints) · Next: [`PATCH /v3/callbacks/endpoints/{id}`](https://www.secblast.com/docs/reference/patch-callbacks-endpoints-id) --- # PATCH /v3/callbacks/endpoints/{id} Change a webhook endpoint. **API key:** required. See [Authentication](https://www.secblast.com/docs/authentication). **Group:** [Webhooks (API: callbacks)](https://www.secblast.com/docs/reference#webhooks-api-callbacks) ## Parameters | Name | In | Type | Required | Default | Description | |---|---|---|---|---|---| | `id` | path | string | yes | | The endpoint's id (cbe_ and 24 hex digits). | ## Request body A [CallbackEndpointPatch](https://www.secblast.com/docs/reference/schemas#schema-callbackendpointpatch) object, as JSON. | Field | Type | Required | Description | |---|---|---|---| | `active` | boolean | no | true on an inactive endpoint counts against the plan's limit. | | `description` | string \| null | no | null clears it. | | `event_types` | array of string | no | | | `url` | string | no | | ## Responses | Status | Body | Description | |---|---|---| | `200` | [CallbackEndpoint](https://www.secblast.com/docs/reference/schemas#schema-callbackendpoint) (`application/json`) | OK | | `400` | [Problem](https://www.secblast.com/docs/reference/schemas#schema-problem) (`application/problem+json`) | Invalid or unknown parameter, or a body that is not one JSON document (code invalid_body). | | `401` | [Problem](https://www.secblast.com/docs/reference/schemas#schema-problem) (`application/problem+json`) | Missing, invalid or inactive API key (code unauthorized), or a refused access token (code invalid_token: malformed, unknown key, bad signature, expired, wrong issuer or audience, revoked grant). WWW-Authenticate names the protected-resource metadata (RFC 9728). | | `403` | [Problem](https://www.secblast.com/docs/reference/schemas#schema-problem) (`application/problem+json`) | The credential's scope does not cover this route (code forbidden), or the organization's plan has no callbacks (code plan_required). | | `404` | [Problem](https://www.secblast.com/docs/reference/schemas#schema-problem) (`application/problem+json`) | Not found. | | `409` | [Problem](https://www.secblast.com/docs/reference/schemas#schema-problem) (`application/problem+json`) | The plan's limit of active endpoints is reached (code limit_reached, with members kind, limit and used); or the endpoint changed while a PATCH was being checked (code conflict: retry). | | `415` | [Problem](https://www.secblast.com/docs/reference/schemas#schema-problem) (`application/problem+json`) | The body is not sent as Content-Type: application/json (code unsupported_media_type). | | `503` | [Problem](https://www.secblast.com/docs/reference/schemas#schema-problem) (`application/problem+json`) | Callbacks are not available: this server has no callback key file or its database lacks the callback tables (code callbacks_unavailable); too many callback URLs are being checked at once (code db_unavailable, reason resolver_busy, Retry-After 1); or the database is unavailable (code db_unavailable). | | `default` | [Problem](https://www.secblast.com/docs/reference/schemas#schema-problem) (`application/problem+json`) | Any other error (405, 500, 504). | ## Response body A `200` carries a [CallbackEndpoint](https://www.secblast.com/docs/reference/schemas#schema-callbackendpoint) object. | Field | Type | Required | Description | |---|---|---|---| | `active` | boolean | yes | | | `created_at` | date-time (RFC 3339, UTC) | yes | | | `description` | string \| null | yes | | | `event_types` | array of string | yes | | | `health` | object | yes | | | `health.consecutive_failures` | integer | no | | | `health.disabled_at` | date-time (RFC 3339, UTC) \| null | no | | | `health.disabled_reason` | string \| null | no | | | `health.failing_since` | date-time (RFC 3339, UTC) \| null | no | | | `health.last_success_at` | date-time (RFC 3339, UTC) \| null | no | | | `health.state` | string | yes | One of: `unverified`, `active`, `failing`, `disabled`. | | `health.verified_at` | date-time (RFC 3339, UTC) \| null | no | | | `id` | string | yes | cbe_ and 24 hex digits. | | `last_24h` | object | yes | Deliveries of the last 24 hours by state. | | `last_24h.delivered` | integer | no | | | `last_24h.dropped` | integer | no | | | `last_24h.failed` | integer | no | | | `last_24h.held` | integer | no | | | `updated_at` | date-time (RFC 3339, UTC) | yes | | | `url` | string | yes | As stored: https, the host in lower case, no :443, / for an empty path. | ## Example request ```bash curl -sS -X PATCH -H "Authorization: Bearer $SECBLAST_API_KEY" \ -H "Content-Type: application/json" -d @body.json \ 'https://api.secblast.com/v3/callbacks/endpoints/cbe_0123456789abcdef01234567' ``` ## More in Webhooks (API: callbacks) Previous: [`GET /v3/callbacks/endpoints/{id}`](https://www.secblast.com/docs/reference/get-callbacks-endpoints-id) · Next: [`DELETE /v3/callbacks/endpoints/{id}`](https://www.secblast.com/docs/reference/delete-callbacks-endpoints-id) --- # DELETE /v3/callbacks/endpoints/{id} Delete a webhook endpoint. **API key:** required. See [Authentication](https://www.secblast.com/docs/authentication). **Group:** [Webhooks (API: callbacks)](https://www.secblast.com/docs/reference#webhooks-api-callbacks) ## Parameters | Name | In | Type | Required | Default | Description | |---|---|---|---|---|---| | `id` | path | string | yes | | The endpoint's id (cbe_ and 24 hex digits). | ## Responses | Status | Body | Description | |---|---|---| | `204` | none | Done; no body. | | `400` | [Problem](https://www.secblast.com/docs/reference/schemas#schema-problem) (`application/problem+json`) | Invalid or unknown parameter. | | `401` | [Problem](https://www.secblast.com/docs/reference/schemas#schema-problem) (`application/problem+json`) | Missing, invalid or inactive API key (code unauthorized), or a refused access token (code invalid_token: malformed, unknown key, bad signature, expired, wrong issuer or audience, revoked grant). WWW-Authenticate names the protected-resource metadata (RFC 9728). | | `403` | [Problem](https://www.secblast.com/docs/reference/schemas#schema-problem) (`application/problem+json`) | The credential's scope does not cover this route (code forbidden), or the organization's plan has no callbacks (code plan_required). | | `404` | [Problem](https://www.secblast.com/docs/reference/schemas#schema-problem) (`application/problem+json`) | Not found. | | `409` | [Problem](https://www.secblast.com/docs/reference/schemas#schema-problem) (`application/problem+json`) | The plan's limit of active endpoints is reached (code limit_reached, with members kind, limit and used); or the endpoint changed while a PATCH was being checked (code conflict: retry). | | `503` | [Problem](https://www.secblast.com/docs/reference/schemas#schema-problem) (`application/problem+json`) | Callbacks are not available: this server has no callback key file or its database lacks the callback tables (code callbacks_unavailable); too many callback URLs are being checked at once (code db_unavailable, reason resolver_busy, Retry-After 1); or the database is unavailable (code db_unavailable). | | `default` | [Problem](https://www.secblast.com/docs/reference/schemas#schema-problem) (`application/problem+json`) | Any other error (405, 500, 504). | ## Response body A `204` carries no body. ## Example request ```bash curl -sS -X DELETE -H "Authorization: Bearer $SECBLAST_API_KEY" \ 'https://api.secblast.com/v3/callbacks/endpoints/cbe_0123456789abcdef01234567' ``` ## More in Webhooks (API: callbacks) Previous: [`PATCH /v3/callbacks/endpoints/{id}`](https://www.secblast.com/docs/reference/patch-callbacks-endpoints-id) · Next: [`POST /v3/callbacks/endpoints/{id}/replay`](https://www.secblast.com/docs/reference/post-callbacks-endpoints-id-replay) --- # POST /v3/callbacks/endpoints/{id}/replay Queues again the failed and dropped deliveries of one endpoint created in a window (202 {replayed, truncated, last_created_at}): oldest first, at most 10,000 a call (truncated; continue with from = last_created_at). The window is at most 30 days. Deliveries that were billed, test deliveries and endpoint verifications are never requeued; held and pending ones are left to the deliverer. 409 replay_running while a replay of this endpoint is less than 60 seconds old (Retry-After). 403 plan_required, 409 endpoint_unverified or endpoint_disabled as for a retry; a deleted endpoint is 404. 503 callbacks_unavailable while this server has no callback key file or its database lacks the callback tables. **API key:** required. See [Authentication](https://www.secblast.com/docs/authentication). **Group:** [Webhooks (API: callbacks)](https://www.secblast.com/docs/reference#webhooks-api-callbacks) ## Parameters | Name | In | Type | Required | Default | Description | |---|---|---|---|---|---| | `id` | path | string | yes | | The endpoint's id (cbe_ and 24 hex digits). | ## Request body A [CallbackReplayRequest](https://www.secblast.com/docs/reference/schemas#schema-callbackreplayrequest) object, as JSON. | Field | Type | Required | Description | |---|---|---|---| | `from` | string | yes | Start of the window of created_at, inclusive: YYYY-MM-DDTHH:MM:SSZ, or YYYY-MM-DD for midnight UTC. | | `states` | array of string | no | Default both. | | `to` | string | no | End of the window, exclusive, same forms; default now. The window is at most 30 days. | | `types` | array of string | no | Only deliveries of these event types; default every type. | ## Responses | Status | Body | Description | |---|---|---| | `202` | [CallbackReplayResult](https://www.secblast.com/docs/reference/schemas#schema-callbackreplayresult) (`application/json`) | OK | | `400` | [Problem](https://www.secblast.com/docs/reference/schemas#schema-problem) (`application/problem+json`) | Invalid or unknown parameter, or a body that is not one JSON document (code invalid_body). | | `401` | [Problem](https://www.secblast.com/docs/reference/schemas#schema-problem) (`application/problem+json`) | Missing, invalid or inactive API key (code unauthorized), or a refused access token (code invalid_token: malformed, unknown key, bad signature, expired, wrong issuer or audience, revoked grant). WWW-Authenticate names the protected-resource metadata (RFC 9728). | | `403` | [Problem](https://www.secblast.com/docs/reference/schemas#schema-problem) (`application/problem+json`) | The credential's scope does not cover this route (code forbidden), or the organization's plan has no webhook deliveries (code plan_required). | | `404` | [Problem](https://www.secblast.com/docs/reference/schemas#schema-problem) (`application/problem+json`) | Not found. | | `409` | [Problem](https://www.secblast.com/docs/reference/schemas#schema-problem) (`application/problem+json`) | invalid_state: the delivery is not failed, or it was billed, or it is a test delivery or an endpoint verification; limit_reached (kind manual_retries, limit, used): the delivery was retried by hand twice already; replay_running (Retry-After): a replay of this endpoint started less than 60 seconds ago; endpoint_unverified or endpoint_disabled: the endpoint cannot be sent to now. | | `415` | [Problem](https://www.secblast.com/docs/reference/schemas#schema-problem) (`application/problem+json`) | The body is not sent as Content-Type: application/json (code unsupported_media_type). | | `503` | [Problem](https://www.secblast.com/docs/reference/schemas#schema-problem) (`application/problem+json`) | Callbacks are not available: this server has no callback key file or its database lacks the callback tables (code callbacks_unavailable); too many callback URLs are being checked at once (code db_unavailable, reason resolver_busy, Retry-After 1); or the database is unavailable (code db_unavailable). | | `default` | [Problem](https://www.secblast.com/docs/reference/schemas#schema-problem) (`application/problem+json`) | Any other error (405, 500, 504). | ## Response body A `202` carries a [CallbackReplayResult](https://www.secblast.com/docs/reference/schemas#schema-callbackreplayresult) object. | Field | Type | Required | Description | |---|---|---|---| | `last_created_at` | date-time (RFC 3339, UTC) \| null | yes | When truncated: the created_at (whole seconds) of the last delivery requeued; replay again with the same to, states and types and from set to it. | | `replayed` | integer | yes | Deliveries requeued. | | `truncated` | boolean | yes | true when more than 10,000 deliveries matched; the oldest 10,000 were requeued. | ## Example request ```bash curl -sS -X POST -H "Authorization: Bearer $SECBLAST_API_KEY" \ -H "Content-Type: application/json" -d @body.json \ 'https://api.secblast.com/v3/callbacks/endpoints/cbe_0123456789abcdef01234567/replay' ``` ## More in Webhooks (API: callbacks) Previous: [`DELETE /v3/callbacks/endpoints/{id}`](https://www.secblast.com/docs/reference/delete-callbacks-endpoints-id) · Next: [`POST /v3/callbacks/endpoints/{id}/rotate-secret`](https://www.secblast.com/docs/reference/post-callbacks-endpoints-id-rotate-secret) --- # POST /v3/callbacks/endpoints/{id}/rotate-secret Rotate the endpoint's signing secret. A new signing secret for the endpoint, answered once with the endpoint. The previous secret still signs beside it for expire_previous_in_s seconds (default 86400; 0: not at all). The body is optional. 503 callbacks_unavailable while this server has no callback key file or its database lacks the callback tables. **API key:** required. See [Authentication](https://www.secblast.com/docs/authentication). **Group:** [Webhooks (API: callbacks)](https://www.secblast.com/docs/reference#webhooks-api-callbacks) ## Parameters | Name | In | Type | Required | Default | Description | |---|---|---|---|---|---| | `id` | path | string | yes | | The endpoint's id (cbe_ and 24 hex digits). | ## Request body A [CallbackRotateSecret](https://www.secblast.com/docs/reference/schemas#schema-callbackrotatesecret) object, as JSON. | Field | Type | Required | Description | |---|---|---|---| | `expire_previous_in_s` | integer | no | How long the previous secret still signs beside the new one; 0: not at all. | ## Responses | Status | Body | Description | |---|---|---| | `200` | [CallbackEndpointCreated](https://www.secblast.com/docs/reference/schemas#schema-callbackendpointcreated) (`application/json`) | OK | | `400` | [Problem](https://www.secblast.com/docs/reference/schemas#schema-problem) (`application/problem+json`) | Invalid or unknown parameter, or a body that is not one JSON document (code invalid_body). | | `401` | [Problem](https://www.secblast.com/docs/reference/schemas#schema-problem) (`application/problem+json`) | Missing, invalid or inactive API key (code unauthorized), or a refused access token (code invalid_token: malformed, unknown key, bad signature, expired, wrong issuer or audience, revoked grant). WWW-Authenticate names the protected-resource metadata (RFC 9728). | | `403` | [Problem](https://www.secblast.com/docs/reference/schemas#schema-problem) (`application/problem+json`) | The credential's scope does not cover this route (code forbidden), or the organization's plan has no callbacks (code plan_required). | | `404` | [Problem](https://www.secblast.com/docs/reference/schemas#schema-problem) (`application/problem+json`) | Not found. | | `415` | [Problem](https://www.secblast.com/docs/reference/schemas#schema-problem) (`application/problem+json`) | The body is not sent as Content-Type: application/json (code unsupported_media_type). | | `503` | [Problem](https://www.secblast.com/docs/reference/schemas#schema-problem) (`application/problem+json`) | Callbacks are not available: this server has no callback key file or its database lacks the callback tables (code callbacks_unavailable); too many callback URLs are being checked at once (code db_unavailable, reason resolver_busy, Retry-After 1); or the database is unavailable (code db_unavailable). | | `default` | [Problem](https://www.secblast.com/docs/reference/schemas#schema-problem) (`application/problem+json`) | Any other error (405, 500, 504). | ## Response body A `200` carries a [CallbackEndpointCreated](https://www.secblast.com/docs/reference/schemas#schema-callbackendpointcreated) object. | Field | Type | Required | Description | |---|---|---|---| | `active` | boolean | yes | | | `created_at` | date-time (RFC 3339, UTC) | yes | | | `description` | string \| null | yes | | | `event_types` | array of string | yes | | | `health` | object | yes | | | `health.consecutive_failures` | integer | no | | | `health.disabled_at` | date-time (RFC 3339, UTC) \| null | no | | | `health.disabled_reason` | string \| null | no | | | `health.failing_since` | date-time (RFC 3339, UTC) \| null | no | | | `health.last_success_at` | date-time (RFC 3339, UTC) \| null | no | | | `health.state` | string | yes | One of: `unverified`, `active`, `failing`, `disabled`. | | `health.verified_at` | date-time (RFC 3339, UTC) \| null | no | | | `id` | string | yes | cbe_ and 24 hex digits. | | `last_24h` | object | yes | Deliveries of the last 24 hours by state. | | `last_24h.delivered` | integer | no | | | `last_24h.dropped` | integer | no | | | `last_24h.failed` | integer | no | | | `last_24h.held` | integer | no | | | `updated_at` | date-time (RFC 3339, UTC) | yes | | | `url` | string | yes | As stored: https, the host in lower case, no :443, / for an empty path. | | `secret` | string | yes | whsec_ and the standard base64 (with padding) of 32 random bytes: the Standard Webhooks signing secret. Shown only in this answer. | ## Example request ```bash curl -sS -X POST -H "Authorization: Bearer $SECBLAST_API_KEY" \ -H "Content-Type: application/json" -d @body.json \ 'https://api.secblast.com/v3/callbacks/endpoints/cbe_0123456789abcdef01234567/rotate-secret' ``` ## More in Webhooks (API: callbacks) Previous: [`POST /v3/callbacks/endpoints/{id}/replay`](https://www.secblast.com/docs/reference/post-callbacks-endpoints-id-replay) · Next: [`POST /v3/callbacks/endpoints/{id}/test`](https://www.secblast.com/docs/reference/post-callbacks-endpoints-id-test) --- # POST /v3/callbacks/endpoints/{id}/test Sends the endpoint one sample event of a type it takes, signed like any event, with test: true in its envelope and sample data (accession 0000000000-26-000001), and answers with the attempt's outcome: 200 {id, state, delivered, http_status, error_class, duration_ms} once the one attempt is made (a test send is not retried and not billed), or 202 {id, state} when no attempt was made within 12 seconds (it is still sent; see the delivery log). 409 endpoint_unverified or endpoint_disabled while the endpoint cannot be sent to, test_running while another test of the organization runs; 403 plan_required for a plan without deliveries. /verify and /test share a limit of 6 a minute per organization (burst 3): beyond it 429 rate_limited (reason verify_test, Retry-After). 429 rate_limited (reason test_capacity) while the server runs its most test sends at once. 503 callbacks_unavailable while this server has no callback key file or its database lacks the callback tables. **API key:** required. See [Authentication](https://www.secblast.com/docs/authentication). **Group:** [Webhooks (API: callbacks)](https://www.secblast.com/docs/reference#webhooks-api-callbacks) ## Parameters | Name | In | Type | Required | Default | Description | |---|---|---|---|---|---| | `id` | path | string | yes | | The endpoint's id (cbe_ and 24 hex digits). | ## Request body A [CallbackEndpointTestRequest](https://www.secblast.com/docs/reference/schemas#schema-callbackendpointtestrequest) object, as JSON. | Field | Type | Required | Description | |---|---|---|---| | `type` | string | yes | One of the endpoint's event_types. The sample event has this type and test: true in its envelope; there is no separate test type. One of: `filing.new`, `filing.updated`, `filing.corrected`, `filing.deleted`, `search.match`, `search.digest`, `filing.digest`, `search.export.completed`. | ## Responses | Status | Body | Description | |---|---|---| | `200` | [CallbackEndpointTestResult](https://www.secblast.com/docs/reference/schemas#schema-callbackendpointtestresult) (`application/json`) | OK | | `202` | [CallbackEndpointTestResult](https://www.secblast.com/docs/reference/schemas#schema-callbackendpointtestresult) (`application/json`) | No attempt was made within 12 seconds: {id, state} (pending, delivering or held). The delivery is still made. | | `400` | [Problem](https://www.secblast.com/docs/reference/schemas#schema-problem) (`application/problem+json`) | Invalid or unknown parameter, or a body that is not one JSON document (code invalid_body). | | `401` | [Problem](https://www.secblast.com/docs/reference/schemas#schema-problem) (`application/problem+json`) | Missing, invalid or inactive API key (code unauthorized), or a refused access token (code invalid_token: malformed, unknown key, bad signature, expired, wrong issuer or audience, revoked grant). WWW-Authenticate names the protected-resource metadata (RFC 9728). | | `403` | [Problem](https://www.secblast.com/docs/reference/schemas#schema-problem) (`application/problem+json`) | The credential's scope does not cover this route (code forbidden), or the organization's plan has no webhook deliveries (code plan_required). | | `404` | [Problem](https://www.secblast.com/docs/reference/schemas#schema-problem) (`application/problem+json`) | Not found. | | `409` | [Problem](https://www.secblast.com/docs/reference/schemas#schema-problem) (`application/problem+json`) | endpoint_unverified: the endpoint is not verified yet; endpoint_disabled: it is inactive or disabled; test_running: another test send of the organization has not answered yet. | | `415` | [Problem](https://www.secblast.com/docs/reference/schemas#schema-problem) (`application/problem+json`) | The body is not sent as Content-Type: application/json (code unsupported_media_type). | | `429` | [Problem](https://www.secblast.com/docs/reference/schemas#schema-problem) (`application/problem+json`) | rate_limited, reason verify_test: the organization's limit of verifications and test sends (the configured rate and burst) is used up, retry after Retry-After; reason test_capacity (/test only): the server runs its most test sends at once, retry after Retry-After. | | `503` | [Problem](https://www.secblast.com/docs/reference/schemas#schema-problem) (`application/problem+json`) | Callbacks are not available: this server has no callback key file or its database lacks the callback tables (code callbacks_unavailable); too many callback URLs are being checked at once (code db_unavailable, reason resolver_busy, Retry-After 1); or the database is unavailable (code db_unavailable). | | `default` | [Problem](https://www.secblast.com/docs/reference/schemas#schema-problem) (`application/problem+json`) | Any other error (405, 500, 504). | ## Response body A `200` carries a [CallbackEndpointTestResult](https://www.secblast.com/docs/reference/schemas#schema-callbackendpointtestresult) object. | Field | Type | Required | Description | |---|---|---|---| | `delivered` | boolean | no | 200 only: the endpoint answered 2xx. | | `duration_ms` | integer \| null | no | 200 only: the attempt's duration. | | `error_class` | string \| null | no | 200 only. One of: `timeout`, `connect`, `tls`, `dns`, `blocked_address`, `redirect`, `http`, `too_large`, `null`. | | `http_status` | integer \| null | no | 200 only: the endpoint's status; null when no HTTP answer came. | | `id` | string | yes | The test delivery's id (dlv_ and 24 hex digits), in the delivery log. | | `state` | string | yes | 200: delivered, failed or dropped (the attempt's outcome is final: a test send is attempted once). 202: still pending, delivering or held when the 12 seconds ran out; the delivery is still made, and its outcome is in the delivery log. One of: `pending`, `delivering`, `held`, `delivered`, `failed`, `dropped`. | ## Example request ```bash curl -sS -X POST -H "Authorization: Bearer $SECBLAST_API_KEY" \ -H "Content-Type: application/json" -d @body.json \ 'https://api.secblast.com/v3/callbacks/endpoints/cbe_0123456789abcdef01234567/test' ``` ## More in Webhooks (API: callbacks) Previous: [`POST /v3/callbacks/endpoints/{id}/rotate-secret`](https://www.secblast.com/docs/reference/post-callbacks-endpoints-id-rotate-secret) · Next: [`POST /v3/callbacks/endpoints/{id}/verify`](https://www.secblast.com/docs/reference/post-callbacks-endpoints-id-verify) --- # POST /v3/callbacks/endpoints/{id}/verify Sends the endpoint a new verification challenge (202, the endpoint): it is unverified, and its deliveries are held, until it answers 2xx with exactly the challenge. An earlier challenge not yet sent is dropped; an answer to it no longer verifies. The challenge goes to the endpoint's stored url; the body is optional and has no members. 409 endpoint_disabled for an inactive endpoint (PATCH active: true verifies it again). /verify and /test share a limit of 6 a minute per organization (burst 3): beyond it 429 rate_limited (reason verify_test, Retry-After). 503 callbacks_unavailable while this server has no callback key file or its database lacks the callback tables. **API key:** required. See [Authentication](https://www.secblast.com/docs/authentication). **Group:** [Webhooks (API: callbacks)](https://www.secblast.com/docs/reference#webhooks-api-callbacks) ## Parameters | Name | In | Type | Required | Default | Description | |---|---|---|---|---|---| | `id` | path | string | yes | | The endpoint's id (cbe_ and 24 hex digits). | ## Request body A [CallbackVerifyRequest](https://www.secblast.com/docs/reference/schemas#schema-callbackverifyrequest) object, as JSON. ## Responses | Status | Body | Description | |---|---|---| | `202` | [CallbackEndpoint](https://www.secblast.com/docs/reference/schemas#schema-callbackendpoint) (`application/json`) | OK | | `400` | [Problem](https://www.secblast.com/docs/reference/schemas#schema-problem) (`application/problem+json`) | Invalid or unknown parameter, or a body that is not one JSON document (code invalid_body). | | `401` | [Problem](https://www.secblast.com/docs/reference/schemas#schema-problem) (`application/problem+json`) | Missing, invalid or inactive API key (code unauthorized), or a refused access token (code invalid_token: malformed, unknown key, bad signature, expired, wrong issuer or audience, revoked grant). WWW-Authenticate names the protected-resource metadata (RFC 9728). | | `403` | [Problem](https://www.secblast.com/docs/reference/schemas#schema-problem) (`application/problem+json`) | The credential's scope does not cover this route (code forbidden). | | `404` | [Problem](https://www.secblast.com/docs/reference/schemas#schema-problem) (`application/problem+json`) | Not found. | | `409` | [Problem](https://www.secblast.com/docs/reference/schemas#schema-problem) (`application/problem+json`) | endpoint_disabled: the endpoint is inactive; PATCH active: true verifies it again. | | `415` | [Problem](https://www.secblast.com/docs/reference/schemas#schema-problem) (`application/problem+json`) | The body is not sent as Content-Type: application/json (code unsupported_media_type). | | `429` | [Problem](https://www.secblast.com/docs/reference/schemas#schema-problem) (`application/problem+json`) | rate_limited, reason verify_test: the organization's limit of verifications and test sends (the configured rate and burst) is used up, retry after Retry-After; reason test_capacity (/test only): the server runs its most test sends at once, retry after Retry-After. | | `503` | [Problem](https://www.secblast.com/docs/reference/schemas#schema-problem) (`application/problem+json`) | Callbacks are not available: this server has no callback key file or its database lacks the callback tables (code callbacks_unavailable); too many callback URLs are being checked at once (code db_unavailable, reason resolver_busy, Retry-After 1); or the database is unavailable (code db_unavailable). | | `default` | [Problem](https://www.secblast.com/docs/reference/schemas#schema-problem) (`application/problem+json`) | Any other error (405, 500, 504). | ## Response body A `202` carries a [CallbackEndpoint](https://www.secblast.com/docs/reference/schemas#schema-callbackendpoint) object. | Field | Type | Required | Description | |---|---|---|---| | `active` | boolean | yes | | | `created_at` | date-time (RFC 3339, UTC) | yes | | | `description` | string \| null | yes | | | `event_types` | array of string | yes | | | `health` | object | yes | | | `health.consecutive_failures` | integer | no | | | `health.disabled_at` | date-time (RFC 3339, UTC) \| null | no | | | `health.disabled_reason` | string \| null | no | | | `health.failing_since` | date-time (RFC 3339, UTC) \| null | no | | | `health.last_success_at` | date-time (RFC 3339, UTC) \| null | no | | | `health.state` | string | yes | One of: `unverified`, `active`, `failing`, `disabled`. | | `health.verified_at` | date-time (RFC 3339, UTC) \| null | no | | | `id` | string | yes | cbe_ and 24 hex digits. | | `last_24h` | object | yes | Deliveries of the last 24 hours by state. | | `last_24h.delivered` | integer | no | | | `last_24h.dropped` | integer | no | | | `last_24h.failed` | integer | no | | | `last_24h.held` | integer | no | | | `updated_at` | date-time (RFC 3339, UTC) | yes | | | `url` | string | yes | As stored: https, the host in lower case, no :443, / for an empty path. | ## Example request ```bash curl -sS -X POST -H "Authorization: Bearer $SECBLAST_API_KEY" \ -H "Content-Type: application/json" -d @body.json \ 'https://api.secblast.com/v3/callbacks/endpoints/cbe_0123456789abcdef01234567/verify' ``` ## More in Webhooks (API: callbacks) Previous: [`POST /v3/callbacks/endpoints/{id}/test`](https://www.secblast.com/docs/reference/post-callbacks-endpoints-id-test) · Next: [`GET /v3/search/subscriptions`](https://www.secblast.com/docs/reference/get-search-subscriptions) --- # GET /v3/search/subscriptions The organization's subscriptions, newest first, with limits by kind: filter (stored kind filing), firehose and search, each the plan's limit and the active subscriptions. 503 callbacks_unavailable while this server has no callback key file or its database lacks the callback tables. **API key:** required. See [Authentication](https://www.secblast.com/docs/authentication). **Group:** [Webhooks (API: callbacks)](https://www.secblast.com/docs/reference#webhooks-api-callbacks) ## Parameters | Name | In | Type | Required | Default | Description | |---|---|---|---|---|---| | `limit` | query | integer | no | `50` | Page size, 1..100 (GET). | | `cursor` | query | string | no | | Opaque cursor from a previous page's next_cursor (GET). | ## Responses | Status | Body | Description | |---|---|---| | `200` | [SearchSubscriptionList](https://www.secblast.com/docs/reference/schemas#schema-searchsubscriptionlist) (`application/json`) | OK | | `400` | [Problem](https://www.secblast.com/docs/reference/schemas#schema-problem) (`application/problem+json`) | Invalid or unknown parameter, or a query error (invalid_query, query_too_complex, prefix_too_broad, negative_only_query, unsupported_operator, invalid_cursor); query errors carry position and length (characters of q). | | `401` | [Problem](https://www.secblast.com/docs/reference/schemas#schema-problem) (`application/problem+json`) | Missing, invalid or inactive API key (code unauthorized), or a refused access token (code invalid_token: malformed, unknown key, bad signature, expired, wrong issuer or audience, revoked grant). WWW-Authenticate names the protected-resource metadata (RFC 9728). | | `403` | [Problem](https://www.secblast.com/docs/reference/schemas#schema-problem) (`application/problem+json`) | The credential's scope does not cover this route (code forbidden). | | `409` | [Problem](https://www.secblast.com/docs/reference/schemas#schema-problem) (`application/problem+json`) | Conflict with the current state. | | `503` | [Problem](https://www.secblast.com/docs/reference/schemas#schema-problem) (`application/problem+json`) | Full-text search cannot answer now: search_unavailable (sb_search unreachable or not configured), search_busy (its queue is full), search_timeout (the query hit its time budget), ticker_resolution_unavailable; or the database is unavailable. Retry after the Retry-After delay when one is given. | | `default` | [Problem](https://www.secblast.com/docs/reference/schemas#schema-problem) (`application/problem+json`) | Any other error (405, 500, 504). | ## Response body A `200` carries a [SearchSubscriptionList](https://www.secblast.com/docs/reference/schemas#schema-searchsubscriptionlist) object. | Field | Type | Required | Description | |---|---|---|---| | `data` | array of [SearchSubscription](https://www.secblast.com/docs/reference/schemas#schema-searchsubscription) | yes | | | `has_more` | boolean | yes | | | `limits` | object | yes | By kind: filter (stored kind filing), firehose, search. limit: the plan's (0 without); used: active subscriptions of that kind. | | `limits.filter` | object | no | | | `limits.filter.limit` | integer | no | | | `limits.filter.used` | integer | no | | | `limits.firehose` | object | no | | | `limits.firehose.limit` | integer | no | | | `limits.firehose.used` | integer | no | | | `limits.search` | object | no | | | `limits.search.limit` | integer | no | | | `limits.search.used` | integer | no | | | `next_cursor` | string \| null | yes | | ## Example request ```bash curl -sS -H "Authorization: Bearer $SECBLAST_API_KEY" \ 'https://api.secblast.com/v3/search/subscriptions' ``` [Open this route in the console](https://www.secblast.com/console#get-v3-search-subscriptions) ## More in Webhooks (API: callbacks) Previous: [`POST /v3/callbacks/endpoints/{id}/verify`](https://www.secblast.com/docs/reference/post-callbacks-endpoints-id-verify) · Next: [`POST /v3/search/subscriptions`](https://www.secblast.com/docs/reference/post-search-subscriptions) --- # POST /v3/search/subscriptions Create a search subscription. **API key:** required. See [Authentication](https://www.secblast.com/docs/authentication). **Group:** [Webhooks (API: callbacks)](https://www.secblast.com/docs/reference#webhooks-api-callbacks) ## Parameters This route takes no parameters. ## Request body A [SearchSubscriptionCreate](https://www.secblast.com/docs/reference/schemas#schema-searchsubscriptioncreate) object, as JSON. | Field | Type | Required | Description | |---|---|---|---| | `endpoint_id` | string | yes | One of the organization's endpoints; it must list filing.new (filing, firehose) or search.match (search). | | `include_corrections` | boolean | no | | | `min_interval_s` | integer \| null | no | | | `name` | string | yes | 1 to 800 bytes. | | `query` | object | yes | The query and filter parameters of /v3/search (q, syntax, match, forms, form_types, form_families, doctypes, ciks, tickers, sics, states, inc_states, primary_only, entityName, locationCode, ...) as JSON members (a list as a comma string or an array), plus items (8-K item codes). A filing-date window (filed_from, filed_to, startdt, enddt, or a dateRange preset) is a 400 naming it, and so is status (a subscription receives new filings); an acceptance window is not stored. An unknown ticker is a 400 naming tickers (q for a ticker: term in q). | ## Responses | Status | Body | Description | |---|---|---| | `201` | [SearchSubscriptionCreated](https://www.secblast.com/docs/reference/schemas#schema-searchsubscriptioncreated) (`application/json`) | Created | | `400` | [Problem](https://www.secblast.com/docs/reference/schemas#schema-problem) (`application/problem+json`) | Invalid or unknown parameter, or a body that is not one JSON document (code invalid_body). | | `401` | [Problem](https://www.secblast.com/docs/reference/schemas#schema-problem) (`application/problem+json`) | Missing, invalid or inactive API key (code unauthorized), or a refused access token (code invalid_token: malformed, unknown key, bad signature, expired, wrong issuer or audience, revoked grant). WWW-Authenticate names the protected-resource metadata (RFC 9728). | | `403` | [Problem](https://www.secblast.com/docs/reference/schemas#schema-problem) (`application/problem+json`) | The credential's scope does not cover this route (code forbidden). | | `409` | [Problem](https://www.secblast.com/docs/reference/schemas#schema-problem) (`application/problem+json`) | Conflict with the current state. | | `415` | [Problem](https://www.secblast.com/docs/reference/schemas#schema-problem) (`application/problem+json`) | The body is not sent as Content-Type: application/json (code unsupported_media_type). | | `503` | [Problem](https://www.secblast.com/docs/reference/schemas#schema-problem) (`application/problem+json`) | Full-text search cannot answer now: search_unavailable (sb_search unreachable or not configured), search_busy (its queue is full), search_timeout (the query hit its time budget), ticker_resolution_unavailable; or the database is unavailable. Retry after the Retry-After delay when one is given. | | `default` | [Problem](https://www.secblast.com/docs/reference/schemas#schema-problem) (`application/problem+json`) | Any other error (405, 500, 504). | ## Response body A `201` carries a [SearchSubscriptionCreated](https://www.secblast.com/docs/reference/schemas#schema-searchsubscriptioncreated) object. | Field | Type | Required | Description | |---|---|---|---| | `active` | boolean | yes | | | `created_at` | date-time (RFC 3339, UTC) | yes | | | `endpoint_id` | string | yes | cbe_ and 24 hex digits. | | `id` | string | yes | sub_ and 24 hex digits. | | `include_corrections` | boolean | yes | | | `kind` | string | yes | From the query: search when q is not empty, or doctypes, primary_only=true or entityName is given; else filing when a filing-level filter is given (forms, form_types, form_families and their exclusions, ciks, tickers, sics, states, inc_states, locationCode, items); else firehose. filing and firehose deliver filing.new, search delivers search.match. A filing subscription counts against limits.filter. Text subscriptions (kind search) are not offered: a create or PATCH whose query has q, doctypes, primary_only=true or entityName is a 400 invalid_parameter naming that parameter. One of: `filing`, `firehose`, `search`. | | `min_interval_s` | integer \| null | yes | Digest interval; null: every event is delivered alone. | | `name` | string | yes | | | `query` | object | yes | As stored: q, syntax, match and the structured filters as /v3/search/parse normalises them, tickers resolved into ciks at save time (no tickers member), items as given, accepted_from and accepted_to always null. | | `query.filters` | object | yes | | | `query.match` | string | yes | One of: `exact`, `stem`. | | `query.q` | string | yes | | | `query.syntax` | string | yes | One of: `sb`, `edgar`. | | `updated_at` | date-time (RFC 3339, UTC) | yes | | | `resolved` | object | yes | The tickers of the query and the CIKs they were resolved to at save time; in the answers of POST and of a PATCH with a query. | | `resolved.tickers` | object | no | | ## Example request ```bash curl -sS -X POST -H "Authorization: Bearer $SECBLAST_API_KEY" \ -H "Content-Type: application/json" -d @body.json \ 'https://api.secblast.com/v3/search/subscriptions' ``` ## More in Webhooks (API: callbacks) Previous: [`GET /v3/search/subscriptions`](https://www.secblast.com/docs/reference/get-search-subscriptions) · Next: [`GET /v3/search/subscriptions/{id}`](https://www.secblast.com/docs/reference/get-search-subscriptions-id) --- # GET /v3/search/subscriptions/{id} One subscription of the organization. Another organization's subscription is 404. 503 callbacks_unavailable while this server has no callback key file or its database lacks the callback tables. **API key:** required. See [Authentication](https://www.secblast.com/docs/authentication). **Group:** [Webhooks (API: callbacks)](https://www.secblast.com/docs/reference#webhooks-api-callbacks) ## Parameters | Name | In | Type | Required | Default | Description | |---|---|---|---|---|---| | `id` | path | string | yes | | The subscription's id (sub_ and 24 hex digits). | ## Responses | Status | Body | Description | |---|---|---| | `200` | [SearchSubscription](https://www.secblast.com/docs/reference/schemas#schema-searchsubscription) (`application/json`) | OK | | `400` | [Problem](https://www.secblast.com/docs/reference/schemas#schema-problem) (`application/problem+json`) | Invalid or unknown parameter, or a query error (invalid_query, query_too_complex, prefix_too_broad, negative_only_query, unsupported_operator, invalid_cursor); query errors carry position and length (characters of q). | | `401` | [Problem](https://www.secblast.com/docs/reference/schemas#schema-problem) (`application/problem+json`) | Missing, invalid or inactive API key (code unauthorized), or a refused access token (code invalid_token: malformed, unknown key, bad signature, expired, wrong issuer or audience, revoked grant). WWW-Authenticate names the protected-resource metadata (RFC 9728). | | `403` | [Problem](https://www.secblast.com/docs/reference/schemas#schema-problem) (`application/problem+json`) | The credential's scope does not cover this route (code forbidden). | | `404` | [Problem](https://www.secblast.com/docs/reference/schemas#schema-problem) (`application/problem+json`) | Not found. | | `409` | [Problem](https://www.secblast.com/docs/reference/schemas#schema-problem) (`application/problem+json`) | Conflict with the current state. | | `503` | [Problem](https://www.secblast.com/docs/reference/schemas#schema-problem) (`application/problem+json`) | Full-text search cannot answer now: search_unavailable (sb_search unreachable or not configured), search_busy (its queue is full), search_timeout (the query hit its time budget), ticker_resolution_unavailable; or the database is unavailable. Retry after the Retry-After delay when one is given. | | `default` | [Problem](https://www.secblast.com/docs/reference/schemas#schema-problem) (`application/problem+json`) | Any other error (405, 500, 504). | ## Response body A `200` carries a [SearchSubscription](https://www.secblast.com/docs/reference/schemas#schema-searchsubscription) object. | Field | Type | Required | Description | |---|---|---|---| | `active` | boolean | yes | | | `created_at` | date-time (RFC 3339, UTC) | yes | | | `endpoint_id` | string | yes | cbe_ and 24 hex digits. | | `id` | string | yes | sub_ and 24 hex digits. | | `include_corrections` | boolean | yes | | | `kind` | string | yes | From the query: search when q is not empty, or doctypes, primary_only=true or entityName is given; else filing when a filing-level filter is given (forms, form_types, form_families and their exclusions, ciks, tickers, sics, states, inc_states, locationCode, items); else firehose. filing and firehose deliver filing.new, search delivers search.match. A filing subscription counts against limits.filter. Text subscriptions (kind search) are not offered: a create or PATCH whose query has q, doctypes, primary_only=true or entityName is a 400 invalid_parameter naming that parameter. One of: `filing`, `firehose`, `search`. | | `min_interval_s` | integer \| null | yes | Digest interval; null: every event is delivered alone. | | `name` | string | yes | | | `query` | object | yes | As stored: q, syntax, match and the structured filters as /v3/search/parse normalises them, tickers resolved into ciks at save time (no tickers member), items as given, accepted_from and accepted_to always null. | | `query.filters` | object | yes | | | `query.match` | string | yes | One of: `exact`, `stem`. | | `query.q` | string | yes | | | `query.syntax` | string | yes | One of: `sb`, `edgar`. | | `updated_at` | date-time (RFC 3339, UTC) | yes | | ## Example request ```bash curl -sS -H "Authorization: Bearer $SECBLAST_API_KEY" \ 'https://api.secblast.com/v3/search/subscriptions/sub_0123456789abcdef01234567' ``` [Open this route in the console](https://www.secblast.com/console#get-v3-search-subscriptions-id) ## More in Webhooks (API: callbacks) Previous: [`POST /v3/search/subscriptions`](https://www.secblast.com/docs/reference/post-search-subscriptions) · Next: [`PATCH /v3/search/subscriptions/{id}`](https://www.secblast.com/docs/reference/patch-search-subscriptions-id) --- # PATCH /v3/search/subscriptions/{id} Change a search subscription. **API key:** required. See [Authentication](https://www.secblast.com/docs/authentication). **Group:** [Webhooks (API: callbacks)](https://www.secblast.com/docs/reference#webhooks-api-callbacks) ## Parameters | Name | In | Type | Required | Default | Description | |---|---|---|---|---|---| | `id` | path | string | yes | | The subscription's id (sub_ and 24 hex digits). | ## Request body A [SearchSubscriptionPatch](https://www.secblast.com/docs/reference/schemas#schema-searchsubscriptionpatch) object, as JSON. | Field | Type | Required | Description | |---|---|---|---| | `active` | boolean | no | true on an inactive subscription counts against its kind's limit. | | `endpoint_id` | string | no | | | `include_corrections` | boolean | no | | | `min_interval_s` | integer \| null | no | null clears it. | | `name` | string | no | | | `query` | object | no | Replaces the stored query whole. | ## Responses | Status | Body | Description | |---|---|---| | `200` | [SearchSubscription](https://www.secblast.com/docs/reference/schemas#schema-searchsubscription) (`application/json`) | OK | | `400` | [Problem](https://www.secblast.com/docs/reference/schemas#schema-problem) (`application/problem+json`) | Invalid or unknown parameter, or a body that is not one JSON document (code invalid_body). | | `401` | [Problem](https://www.secblast.com/docs/reference/schemas#schema-problem) (`application/problem+json`) | Missing, invalid or inactive API key (code unauthorized), or a refused access token (code invalid_token: malformed, unknown key, bad signature, expired, wrong issuer or audience, revoked grant). WWW-Authenticate names the protected-resource metadata (RFC 9728). | | `403` | [Problem](https://www.secblast.com/docs/reference/schemas#schema-problem) (`application/problem+json`) | The credential's scope does not cover this route (code forbidden). | | `404` | [Problem](https://www.secblast.com/docs/reference/schemas#schema-problem) (`application/problem+json`) | Not found. | | `409` | [Problem](https://www.secblast.com/docs/reference/schemas#schema-problem) (`application/problem+json`) | Conflict with the current state. | | `415` | [Problem](https://www.secblast.com/docs/reference/schemas#schema-problem) (`application/problem+json`) | The body is not sent as Content-Type: application/json (code unsupported_media_type). | | `503` | [Problem](https://www.secblast.com/docs/reference/schemas#schema-problem) (`application/problem+json`) | Full-text search cannot answer now: search_unavailable (sb_search unreachable or not configured), search_busy (its queue is full), search_timeout (the query hit its time budget), ticker_resolution_unavailable; or the database is unavailable. Retry after the Retry-After delay when one is given. | | `default` | [Problem](https://www.secblast.com/docs/reference/schemas#schema-problem) (`application/problem+json`) | Any other error (405, 500, 504). | ## Response body A `200` carries a [SearchSubscription](https://www.secblast.com/docs/reference/schemas#schema-searchsubscription) object. | Field | Type | Required | Description | |---|---|---|---| | `active` | boolean | yes | | | `created_at` | date-time (RFC 3339, UTC) | yes | | | `endpoint_id` | string | yes | cbe_ and 24 hex digits. | | `id` | string | yes | sub_ and 24 hex digits. | | `include_corrections` | boolean | yes | | | `kind` | string | yes | From the query: search when q is not empty, or doctypes, primary_only=true or entityName is given; else filing when a filing-level filter is given (forms, form_types, form_families and their exclusions, ciks, tickers, sics, states, inc_states, locationCode, items); else firehose. filing and firehose deliver filing.new, search delivers search.match. A filing subscription counts against limits.filter. Text subscriptions (kind search) are not offered: a create or PATCH whose query has q, doctypes, primary_only=true or entityName is a 400 invalid_parameter naming that parameter. One of: `filing`, `firehose`, `search`. | | `min_interval_s` | integer \| null | yes | Digest interval; null: every event is delivered alone. | | `name` | string | yes | | | `query` | object | yes | As stored: q, syntax, match and the structured filters as /v3/search/parse normalises them, tickers resolved into ciks at save time (no tickers member), items as given, accepted_from and accepted_to always null. | | `query.filters` | object | yes | | | `query.match` | string | yes | One of: `exact`, `stem`. | | `query.q` | string | yes | | | `query.syntax` | string | yes | One of: `sb`, `edgar`. | | `updated_at` | date-time (RFC 3339, UTC) | yes | | ## Example request ```bash curl -sS -X PATCH -H "Authorization: Bearer $SECBLAST_API_KEY" \ -H "Content-Type: application/json" -d @body.json \ 'https://api.secblast.com/v3/search/subscriptions/sub_0123456789abcdef01234567' ``` ## More in Webhooks (API: callbacks) Previous: [`GET /v3/search/subscriptions/{id}`](https://www.secblast.com/docs/reference/get-search-subscriptions-id) · Next: [`DELETE /v3/search/subscriptions/{id}`](https://www.secblast.com/docs/reference/delete-search-subscriptions-id) --- # DELETE /v3/search/subscriptions/{id} Delete a search subscription. **API key:** required. See [Authentication](https://www.secblast.com/docs/authentication). **Group:** [Webhooks (API: callbacks)](https://www.secblast.com/docs/reference#webhooks-api-callbacks) ## Parameters | Name | In | Type | Required | Default | Description | |---|---|---|---|---|---| | `id` | path | string | yes | | The subscription's id (sub_ and 24 hex digits). | ## Responses | Status | Body | Description | |---|---|---| | `204` | none | Done; no body. | | `400` | [Problem](https://www.secblast.com/docs/reference/schemas#schema-problem) (`application/problem+json`) | Invalid or unknown parameter, or a query error (invalid_query, query_too_complex, prefix_too_broad, negative_only_query, unsupported_operator, invalid_cursor); query errors carry position and length (characters of q). | | `401` | [Problem](https://www.secblast.com/docs/reference/schemas#schema-problem) (`application/problem+json`) | Missing, invalid or inactive API key (code unauthorized), or a refused access token (code invalid_token: malformed, unknown key, bad signature, expired, wrong issuer or audience, revoked grant). WWW-Authenticate names the protected-resource metadata (RFC 9728). | | `403` | [Problem](https://www.secblast.com/docs/reference/schemas#schema-problem) (`application/problem+json`) | The credential's scope does not cover this route (code forbidden). | | `404` | [Problem](https://www.secblast.com/docs/reference/schemas#schema-problem) (`application/problem+json`) | Not found. | | `409` | [Problem](https://www.secblast.com/docs/reference/schemas#schema-problem) (`application/problem+json`) | Conflict with the current state. | | `503` | [Problem](https://www.secblast.com/docs/reference/schemas#schema-problem) (`application/problem+json`) | Full-text search cannot answer now: search_unavailable (sb_search unreachable or not configured), search_busy (its queue is full), search_timeout (the query hit its time budget), ticker_resolution_unavailable; or the database is unavailable. Retry after the Retry-After delay when one is given. | | `default` | [Problem](https://www.secblast.com/docs/reference/schemas#schema-problem) (`application/problem+json`) | Any other error (405, 500, 504). | ## Response body A `204` carries no body. ## Example request ```bash curl -sS -X DELETE -H "Authorization: Bearer $SECBLAST_API_KEY" \ 'https://api.secblast.com/v3/search/subscriptions/sub_0123456789abcdef01234567' ``` ## More in Webhooks (API: callbacks) Previous: [`PATCH /v3/search/subscriptions/{id}`](https://www.secblast.com/docs/reference/patch-search-subscriptions-id) · Next: [`POST /v3/search/subscriptions/{id}/test`](https://www.secblast.com/docs/reference/post-search-subscriptions-id-test) --- # POST /v3/search/subscriptions/{id}/test Preview a search subscription: the payloads the subscription would have produced for filings accepted in the last 7 days (at most 5, newest first), as webhook envelopes with test: true; nothing is delivered or recorded. 503 callbacks_unavailable while this server has no callback key file or its database lacks the callback tables. 503 search_unavailable without full-text search. **API key:** required. See [Authentication](https://www.secblast.com/docs/authentication). **Group:** [Webhooks (API: callbacks)](https://www.secblast.com/docs/reference#webhooks-api-callbacks) ## Parameters | Name | In | Type | Required | Default | Description | |---|---|---|---|---|---| | `id` | path | string | yes | | The subscription's id (sub_ and 24 hex digits). | ## Request body A [SearchSubscriptionTestRequest](https://www.secblast.com/docs/reference/schemas#schema-searchsubscriptiontestrequest) object, as JSON. ## Responses | Status | Body | Description | |---|---|---| | `200` | [SearchSubscriptionTest](https://www.secblast.com/docs/reference/schemas#schema-searchsubscriptiontest) (`application/json`) | OK | | `400` | [Problem](https://www.secblast.com/docs/reference/schemas#schema-problem) (`application/problem+json`) | Invalid or unknown parameter, or a body that is not one JSON document (code invalid_body). | | `401` | [Problem](https://www.secblast.com/docs/reference/schemas#schema-problem) (`application/problem+json`) | Missing, invalid or inactive API key (code unauthorized), or a refused access token (code invalid_token: malformed, unknown key, bad signature, expired, wrong issuer or audience, revoked grant). WWW-Authenticate names the protected-resource metadata (RFC 9728). | | `403` | [Problem](https://www.secblast.com/docs/reference/schemas#schema-problem) (`application/problem+json`) | The credential's scope does not cover this route (code forbidden). | | `404` | [Problem](https://www.secblast.com/docs/reference/schemas#schema-problem) (`application/problem+json`) | Not found. | | `415` | [Problem](https://www.secblast.com/docs/reference/schemas#schema-problem) (`application/problem+json`) | The body is not sent as Content-Type: application/json (code unsupported_media_type). | | `503` | [Problem](https://www.secblast.com/docs/reference/schemas#schema-problem) (`application/problem+json`) | Full-text search cannot answer now: search_unavailable (sb_search unreachable or not configured), search_busy (its queue is full), search_timeout (the query hit its time budget), ticker_resolution_unavailable; or the database is unavailable. Retry after the Retry-After delay when one is given. | | `default` | [Problem](https://www.secblast.com/docs/reference/schemas#schema-problem) (`application/problem+json`) | Any other error (405, 500, 504). | ## Response body A `200` carries a [SearchSubscriptionTest](https://www.secblast.com/docs/reference/schemas#schema-searchsubscriptiontest) object. | Field | Type | Required | Description | |---|---|---|---| | `data` | array of object | yes | The payloads the subscription would have produced for filings accepted in the last 7 days, newest first, each the webhook envelope with test: true: filing.new (filing, firehose; id new:\:\) or search.match (search; id match:\:\). Nothing is delivered. | ## Example request ```bash curl -sS -X POST -H "Authorization: Bearer $SECBLAST_API_KEY" \ -H "Content-Type: application/json" -d @body.json \ 'https://api.secblast.com/v3/search/subscriptions/sub_0123456789abcdef01234567/test' ``` ## More in Webhooks (API: callbacks) Previous: [`DELETE /v3/search/subscriptions/{id}`](https://www.secblast.com/docs/reference/delete-search-subscriptions-id) --- # POST /v3/feedback Send feedback to SEC Blast. **API key:** required. See [Authentication](https://www.secblast.com/docs/authentication). **Group:** [Feedback](https://www.secblast.com/docs/reference#feedback) ## Parameters This route takes no parameters. ## Request body A [FeedbackCreate](https://www.secblast.com/docs/reference/schemas#schema-feedbackcreate) object, as JSON. | Field | Type | Required | Description | |---|---|---|---| | `category` | string | yes | bug: something failed or misbehaved; missing_data: SEC data expected but not there; missing_tool: no route or tool does what was needed; wrong_answer: a value or text is wrong; docs: a description or error message is unclear; other. One of: `bug`, `missing_data`, `missing_tool`, `wrong_answer`, `docs`, `other`. | | `client` | object \| null | no | The client program, e.g. the MCP client's name and version from its initialize request. | | `client.name` | string | yes | | | `client.version` | string \| null | no | | | `context` | object \| null | no | Details such as accession, query and request_id: a JSON object of at most 16 KB as compact JSON. | | `message` | string | yes | What happened and what was expected: 1 to 4,000 characters after trimming, no NUL. | | `source` | string | no | Where the feedback comes from; the MCP server sends mcp. One of: `api`, `mcp`. | | `tool` | string \| null | no | The MCP tool or API route the feedback is about (at most 100 bytes). | ## Responses | Status | Body | Description | |---|---|---| | `201` | [FeedbackCreated](https://www.secblast.com/docs/reference/schemas#schema-feedbackcreated) (`application/json`) | Created | | `400` | [Problem](https://www.secblast.com/docs/reference/schemas#schema-problem) (`application/problem+json`) | Invalid or unknown parameter, or a body that is not one JSON document (code invalid_body). | | `401` | [Problem](https://www.secblast.com/docs/reference/schemas#schema-problem) (`application/problem+json`) | Missing, invalid or inactive API key (code unauthorized), or a refused access token (code invalid_token: malformed, unknown key, bad signature, expired, wrong issuer or audience, revoked grant). WWW-Authenticate names the protected-resource metadata (RFC 9728). | | `403` | [Problem](https://www.secblast.com/docs/reference/schemas#schema-problem) (`application/problem+json`) | The credential belongs to no organization, or its scope does not cover this route (code forbidden). | | `415` | [Problem](https://www.secblast.com/docs/reference/schemas#schema-problem) (`application/problem+json`) | The body is not sent as Content-Type: application/json (code unsupported_media_type). | | `429` | [Problem](https://www.secblast.com/docs/reference/schemas#schema-problem) (`application/problem+json`) | The organization sent its most feedback messages of the last hour (code rate_limited, reason feedback, with retry_after_ms and Retry-After: when the oldest of them is an hour old), or the per-second rate limit (code rate_limited). | | `503` | [Problem](https://www.secblast.com/docs/reference/schemas#schema-problem) (`application/problem+json`) | The database is unavailable, or this server cannot store feedback yet (code db_unavailable, Retry-After). | | `default` | [Problem](https://www.secblast.com/docs/reference/schemas#schema-problem) (`application/problem+json`) | Any other error (405, 500, 504). | ## Response body A `201` carries a [FeedbackCreated](https://www.secblast.com/docs/reference/schemas#schema-feedbackcreated) object. | Field | Type | Required | Description | |---|---|---|---| | `id` | integer (int64) | yes | The feedback's id. | ## Example request ```bash curl -sS -X POST -H "Authorization: Bearer $SECBLAST_API_KEY" \ -H "Content-Type: application/json" -d @body.json \ 'https://api.secblast.com/v3/feedback' ``` --- # GET /v3/coverage Ingest coverage: per feed day the latest non-superseded ingest run and the newest complete reconcile run, overall totals, and the snapshot store. Without from and to the last 90 feed days are listed, leaving out a day whose latest run is source_invalid and that is older than the oldest feed day with filings (a trial run outside the covered days; an explicit window lists it, and such a day inside or after the covered days is always listed); with either, the newest 366 feed days of that window at most (truncated says when days were left out, window what was used). The totals and the default window (neither from nor to) are computed in the background, never by a request: once at start and then every few minutes (5 by default; less often when a computation is slow). Each says when it was computed (computed_at, totals.computed_at) and is served until the next computation replaces it. Until the first computation after a start has finished the answer is 503 with code warming_up and Retry-After. An explicit window is computed by its request, at most once a minute per window. **API key:** required. See [Authentication](https://www.secblast.com/docs/authentication). **Group:** [Coverage, usage and service](https://www.secblast.com/docs/reference#coverage-usage-and-service) ## Parameters | Name | In | Type | Required | Default | Description | |---|---|---|---|---|---| | `from` | query | date (YYYY-MM-DD) | no | | First feed day (inclusive), YYYY-MM-DD. Default: see the description. | | `to` | query | date (YYYY-MM-DD) | no | | Last feed day (inclusive), YYYY-MM-DD. | ## Responses | Status | Body | Description | |---|---|---| | `200` | [Coverage](https://www.secblast.com/docs/reference/schemas#schema-coverage) (`application/json`) | OK | | `400` | [Problem](https://www.secblast.com/docs/reference/schemas#schema-problem) (`application/problem+json`) | Invalid or unknown parameter. | | `401` | [Problem](https://www.secblast.com/docs/reference/schemas#schema-problem) (`application/problem+json`) | Missing, invalid or inactive API key (code unauthorized), or a refused access token (code invalid_token: malformed, unknown key, bad signature, expired, wrong issuer or audience, revoked grant). WWW-Authenticate names the protected-resource metadata (RFC 9728). | | `503` | [Problem](https://www.secblast.com/docs/reference/schemas#schema-problem) (`application/problem+json`) | Database unavailable (code db_unavailable); or the answer, which the server computes in the background, has not been computed yet since it started (code warming_up). Retry the same request after the Retry-After delay. | | `default` | [Problem](https://www.secblast.com/docs/reference/schemas#schema-problem) (`application/problem+json`) | Any other error (405, 500, 504). | ## Response body A `200` carries a [Coverage](https://www.secblast.com/docs/reference/schemas#schema-coverage) object. | Field | Type | Required | Description | |---|---|---|---| | `computed_at` | date-time (RFC 3339, UTC) | no | When data (the per-day part) was computed, UTC. The value is served until a later computation replaces it. | | `data` | array of [CoverageDay](https://www.secblast.com/docs/reference/schemas#schema-coverageday) | yes | Per feed day, the latest non-superseded ingest run; newest day first. At most window.max_days days: the newest ones of the window. The default window is recomputed in the background every few minutes, an explicit one by a request at most once a minute; computed_at says when. | | `live` | object \| null | no | Live ingest: the daemon's last heartbeat (it writes one every 10 s). Null when there is none or live ingest is not enabled. It can be old: live_check says what to make of it. Only the members listed here are given, each checked: a number outside 0..10^15, a time that is not one, or a word outside its list is null, and no free text of the daemon is passed on. | | `live.covered_until` | date-time (RFC 3339, UTC) \| null | no | SEC's list of new filings has been read without a gap up to here. | | `live.ended` | string \| null | no | How the session ended; null while it runs. The reason is in the daemon's log, not here. One of: `clean`, `failed`, `null`. | | `live.fetch` | object | no | requests, http_404, http_429, http_5xx, network, integrity, too_large, bytes, and recent {requests, failed}. | | `live.filings` | object | no | Counts since the session started: seen, listed, documents, failed, skipped_known, and per_min_1, per_min_5, per_min_peak. | | `live.heartbeat_at` | date-time (RFC 3339, UTC) \| null | no | | | `live.items_unmapped` | number \| null | no | 8-K item descriptions seen without an item code. | | `live.last_new_accession` | string \| null | no | | | `live.last_new_filing_at` | date-time (RFC 3339, UTC) \| null | no | | | `live.latency_ms` | object | no | recent (the last window_s seconds) and day: n, and p50 / p95 of accept_to_seen, seen_to_listed, seen_to_documents. | | `live.limiter` | object | no | The shared SEC request limiter as the daemon sees it: priority (on, off, unavailable), wait_ms {p50, p95}, waits_over_1s, refused. | | `live.mode` | string \| null | no | One of: `live`, `dry_run`, `null`. | | `live.paused_until` | date-time (RFC 3339, UTC) \| null | no | | | `live.pauses_24h` | number \| null | no | | | `live.poll` | object | no | Counts of polls and sweeps of SEC's list; rtt_ms and skew_ms in milliseconds. | | `live.poll.below_page0` | number \| null | no | | | `live.poll.failed` | number \| null | no | | | `live.poll.last_ok_at` | date-time (RFC 3339, UTC) \| null | no | | | `live.poll.last_poll_failed` | boolean | no | Whether the last poll failed. The error text stays in the daemon's log. | | `live.poll.ok` | number \| null | no | | | `live.poll.out_of_order` | number \| null | no | | | `live.poll.overflows` | number \| null | no | | | `live.poll.pages_swept` | number \| null | no | | | `live.poll.rtt_ms` | object | no | | | `live.poll.skew_ms` | number \| null | no | | | `live.poll.sweeps` | object | no | | | `live.poll.sweeps_abandoned` | number \| null | no | | | `live.poll.sweeps_exhausted` | number \| null | no | | | `live.poll.uncovered` | array of object | no | Spans of SEC's list a sweep could not cover (the nightly feed covers those filings); at most 50. | | `live.poll.uncovered[].at` | date-time (RFC 3339, UTC) \| null | no | | | `live.poll.uncovered[].from` | date-time (RFC 3339, UTC) \| null | no | | | `live.poll.uncovered[].reason` | string \| null | no | One of: `max_start`, `page_unanswered`, `null`. | | `live.poll.uncovered[].until` | date-time (RFC 3339, UTC) \| null | no | | | `live.poll_interval_ms` | number \| null | no | | | `live.queue` | object | no | fetch_fresh, fetch_backlog, build, retry, oldest_age_s, behind_since. | | `live.roles_unmapped` | integer | no | Role strings of SEC's list that have no v3 role (how many, not which). | | `live.schema` | number \| null | no | | | `live.started_at` | date-time (RFC 3339, UTC) \| null | no | | | `live.state` | string \| null | no | One of: `ok`, `idle`, `catching_up`, `paused`, `cautious`, `sec_unreachable`, `db_down`, `disk_low`, `halted`, `stopping`, `stopped`, `failed`, `null`. | | `live.window_open` | boolean \| null | no | | | `live_check` | string | no | As checks.live of /v3/health. One of: `ok`, `paused`, `degraded`, `down`, `disabled`. | | `snapshot` | object | yes | The snapshot store and the snapshot it serves. | | `snapshot.accessions` | integer \| null | no | Distinct filings in the snapshot. | | `snapshot.age_days` | integer \| null | no | | | `snapshot.available` | boolean | no | | | `snapshot.date` | date (YYYY-MM-DD) \| null | no | | | `snapshot.fallback` | boolean \| null | no | A newer snapshot exists but could not be loaded. | | `snapshot.filers` | integer \| null | no | | | `snapshot.filings` | integer \| null | no | Filing listings in the snapshot (a filing listed by two filers counts twice). | | `snapshot.loaded_at` | date-time (RFC 3339, UTC) \| null | no | | | `snapshot.reloading` | boolean \| null | no | A newer snapshot is being loaded; the current one keeps serving. | | `snapshot.stale` | boolean \| null | no | The snapshot is more than 3 days old. | | `snapshot.state` | string | no | One of: `ok`, `stale`, `loading`, `unavailable`, `disabled`. | | `snapshot.tickers_date` | date (YYYY-MM-DD) \| null | no | Newest copy of SEC's ticker file. | | `snapshot.tickers_from` | date (YYYY-MM-DD) \| null | no | Oldest copy kept. | | `totals` | object | yes | Table-wide totals, whatever the window; recomputed in the background every few minutes (5 by default). They are served until a later computation replaces them: when one fails, the previous totals stay, and computed_at shows their age. | | `totals.accepted_at_stored` | integer | no | Filings with an acceptance time stored in v3 (any source: a header time, or SEC's from the snapshot sync). | | `totals.amendments` | integer | no | Amendments, deleted ones excluded. | | `totals.amendments_resolved` | integer | no | Of those amendments, the ones linked to their original. | | `totals.computed_at` | date-time (RFC 3339, UTC) | no | When the totals were computed, UTC. | | `totals.deleted_filings` | integer | no | | | `totals.documents` | integer | no | | | `totals.filings` | integer | no | | | `totals.max_feed_date` | date (YYYY-MM-DD) \| null | no | | | `totals.max_filing_date` | date (YYYY-MM-DD) \| null | no | | | `totals.min_feed_date` | date (YYYY-MM-DD) \| null | no | | | `totals.min_filing_date` | date (YYYY-MM-DD) \| null | no | | | `truncated` | boolean | yes | True when the window holds more feed days than max_days: the older ones are left out. Ask for them with from / to. | | `window` | object | yes | The window of feed days this answer covers. | | `window.default` | boolean | no | True when neither from nor to was given: the last 90 feed days. | | `window.from` | date (YYYY-MM-DD) \| null | no | The from that was asked for; without one, the oldest day listed (null when no day is listed). | | `window.max_days` | integer | no | The most days one answer lists: 90 for the default window, 366 when from or to is given. | | `window.to` | date (YYYY-MM-DD) \| null | no | The to that was asked for; without one, the newest day listed (null when no day is listed). | ## Example request ```bash curl -sS -H "Authorization: Bearer $SECBLAST_API_KEY" \ 'https://api.secblast.com/v3/coverage' ``` [Open this route in the console](https://www.secblast.com/console#get-v3-coverage) ## More in Coverage, usage and service Next: [`GET /v3/coverage/count`](https://www.secblast.com/docs/reference/get-coverage-count) --- # GET /v3/coverage/count The live filing count, in one small answer that needs no key, for polling: filings (final and provisional; deleted filings are not counted), provisional, deleted, documents, the newest acceptance time and, when this deployment has live ingest, the live daemon's latency over its day. The answer comes from memory, never from a database query of its own: the server adds what was registered since the counts of /v3/coverage/summary (computed every 15 minutes) to them every few seconds (5 by default); as_of says when. filings never goes down between two answers of a running server except after a deletion; filings registered with an old acceptance time (backfills) are added at the next summary computation. Right after one, filings equals final + provisional of /v3/coverage/summary. ETag (weak, over everything but as_of): If-None-Match answers 304 while nothing changed. Until the first computation after a start has finished the answer is 503 with code warming_up and Retry-After. Cache-Control: public, max-age=5. **API key:** not needed. **Group:** [Coverage, usage and service](https://www.secblast.com/docs/reference#coverage-usage-and-service) ## Parameters This route takes no parameters. ## Responses | Status | Body | Description | |---|---|---| | `200` | [CoverageCount](https://www.secblast.com/docs/reference/schemas#schema-coveragecount) (`application/json`) | OK | | `503` | [Problem](https://www.secblast.com/docs/reference/schemas#schema-problem) (`application/problem+json`) | Database unavailable (code db_unavailable); or the answer, which the server computes in the background, has not been computed yet since it started (code warming_up). Retry the same request after the Retry-After delay. | | `default` | [Problem](https://www.secblast.com/docs/reference/schemas#schema-problem) (`application/problem+json`) | Any other error (405, 500, 504). | ## Response body A `200` carries a [CoverageCount](https://www.secblast.com/docs/reference/schemas#schema-coveragecount) object. | Field | Type | Required | Description | |---|---|---|---| | `as_of` | date-time (RFC 3339, UTC) | yes | When these figures were read, UTC (every few seconds; 5 by default). | | `deleted` | integer | yes | Filings SEC deleted (status deleted), now. Not counted in filings; they are still served. | | `documents` | integer | yes | Current documents, counted as documents of /v3/coverage/summary (one per document of each filing, deleted filings included) plus those of filings registered since. Never goes down within a running server. | | `filings` | integer | yes | Filings in v3 that are not deleted: final and provisional (filings_basis). Never goes down between two answers of a running server except after a deletion. A filing registered with an old acceptance time (a backfill) is added at the next computation of /v3/coverage/summary, at most about 20 minutes later; right after that computation filings equals its filings.final + filings.provisional. | | `filings_basis` | string | yes | What filings counts: final and provisional filings; deleted filings are not counted. One of: `final_and_provisional`. | | `latest_accepted_at` | date-time (RFC 3339, UTC) \| null | yes | The newest SEC acceptance time of a filing that is not deleted. | | `live` | object \| null | yes | Live ingest latency over the daemon's current New York day, from its own status, read with the counts. "seen" is when SEC Blast's poll of SEC's list of new filings first saw the filing. SEC publishes no time at which a filing appears in that list, so the time from SEC publishing a filing to it being seen is not measured; it is bounded by poll_interval_ms. Null when this deployment has no live ingest. | | `live.accept_to_seen_ms` | object | no | SEC's acceptance time to seen, milliseconds. | | `live.accept_to_seen_ms.p50` | number \| null | no | | | `live.accept_to_seen_ms.p95` | number \| null | no | | | `live.check` | string | no | As checks.live of /v3/health. One of: `ok`, `paused`, `degraded`, `down`. | | `live.n` | integer \| null | no | Filings whose documents live ingest stored that day. | | `live.poll_interval_ms` | number \| null | no | The daemon's current interval between two polls of SEC's list. | | `live.seen_to_documents_ms` | object | no | Seen to the filing's documents being stored and registered, milliseconds. | | `live.seen_to_documents_ms.p50` | number \| null | no | | | `live.seen_to_documents_ms.p95` | number \| null | no | | | `live.seen_to_stored_ms` | object | no | Seen to the filing being registered in the database (from then on the API lists it, provisional), milliseconds. | | `live.seen_to_stored_ms.p50` | number \| null | no | | | `live.seen_to_stored_ms.p95` | number \| null | no | | | `live.window` | string | no | The figures cover the daemon's current New York day. One of: `day`. | | `live.window_open` | boolean \| null | no | The daemon is in its business-hours window (fast polling). | | `provisional` | integer | yes | Filings registered by live ingest and not yet confirmed by SEC's nightly feed (status provisional), now. | | `summary_computed_at` | date-time (RFC 3339, UTC) \| null | yes | computed_at of the /v3/coverage/summary counts these figures add to. | ## Example request ```bash curl -sS 'https://api.secblast.com/v3/coverage/count' ``` [Open this route in the console](https://www.secblast.com/console#get-v3-coverage-count) ## More in Coverage, usage and service Previous: [`GET /v3/coverage`](https://www.secblast.com/docs/reference/get-coverage) · Next: [`GET /v3/coverage/summary`](https://www.secblast.com/docs/reference/get-coverage-summary) --- # GET /v3/coverage/summary What v3 holds, in one answer that needs no key: filings by status, documents, document versions, the feed days ingested (first, last, count), filings per filing-date year, amendment links by status, the known coverage gaps (a list maintained by hand) and, when this deployment has live ingest, the live daemon's state and lag. The counts are computed in the background, never by a request: once at start and then every 15 minutes by default (at the next background pass after that); computed_at says when, and they are served until the next computation replaces them. live is read per request. Until the first computation after a start has finished the answer is 503 with code warming_up and Retry-After. Cache-Control: public, max-age=300. **API key:** not needed. **Group:** [Coverage, usage and service](https://www.secblast.com/docs/reference#coverage-usage-and-service) ## Parameters This route takes no parameters. ## Responses | Status | Body | Description | |---|---|---| | `200` | [CoverageSummary](https://www.secblast.com/docs/reference/schemas#schema-coveragesummary) (`application/json`) | OK | | `503` | [Problem](https://www.secblast.com/docs/reference/schemas#schema-problem) (`application/problem+json`) | Database unavailable (code db_unavailable); or the answer, which the server computes in the background, has not been computed yet since it started (code warming_up). Retry the same request after the Retry-After delay. | | `default` | [Problem](https://www.secblast.com/docs/reference/schemas#schema-problem) (`application/problem+json`) | Any other error (405, 500, 504). | ## Response body A `200` carries a [CoverageSummary](https://www.secblast.com/docs/reference/schemas#schema-coveragesummary) object. | Field | Type | Required | Description | |---|---|---|---| | `amendments` | object | yes | Amendment links by link status; amendments of deleted filings are not counted. link_rate is resolved / total, rounded to 4 decimals; null when total is 0. | | `amendments.ambiguous` | integer | no | | | `amendments.link_rate` | number \| null | no | | | `amendments.resolved` | integer | no | | | `amendments.target_not_public` | integer | no | | | `amendments.target_not_yet_ingested` | integer | no | | | `amendments.total` | integer | no | | | `amendments.unresolved` | integer | no | | | `before_1993` | object | yes | Filings whose by_year_basis date is before 1993, deleted filings not counted: paper records keyed in later, and dates SEC mistyped. Not years of coverage, so not in by_year. | | `before_1993.filings` | integer | no | | | `before_1993.first_year` | integer \| null | no | The earliest year counted; null when filings is 0. | | `before_1993.paper` | integer | no | Paper filing records among filings (is_paper). | | `by_year` | array of object | yes | Filings per calendar year of by_year_basis from 1993 (EDGAR's first year), oldest year first; deleted filings are not counted. Filings dated earlier are counted in before_1993. | | `by_year[].filings` | integer | no | | | `by_year[].paper` | integer | no | Paper filing records among filings (is_paper). | | `by_year[].year` | integer | no | | | `by_year_basis` | string | yes | The date by_year groups by. One of: `filing_date`. | | `callbacks` | object \| null | yes | Webhook delivery, computed with the counts. Null when this deployment has no webhook delivery. | | `callbacks.computed_at` | date-time (RFC 3339, UTC) | no | When the callbacks block was computed, UTC. | | `callbacks.latency` | object | no | | | `callbacks.latency.first_attempt_from_accepted` | object | no | Seconds from SEC's acceptance to the first delivery attempt, over the first attempts of the last 24 hours of filing.new and search.match deliveries of live filings (test sends and filings first seen in the nightly feed are left out; nearest-rank percentiles; n is the number of first attempts). | | `callbacks.latency.first_attempt_from_accepted.n` | integer | no | | | `callbacks.latency.first_attempt_from_accepted.p50` | number \| null | no | Null when n is 0. | | `callbacks.latency.first_attempt_from_accepted.p95` | number \| null | no | Null when n is 0. | | `computed_at` | date-time (RFC 3339, UTC) | yes | When the counts were computed, UTC. They are served until a later computation replaces them. | | `document_versions` | integer | yes | Stored document versions, every delivery of every document. | | `documents` | integer | yes | Current documents (one per document of each filing). | | `feed_days` | object | yes | Feed days with a complete or partial ingest run (targeted repair runs not counted). | | `feed_days.count` | integer | no | | | `feed_days.first` | date (YYYY-MM-DD) \| null | no | | | `feed_days.last` | date (YYYY-MM-DD) \| null | no | | | `filings` | object | yes | Filings in v3 by status; total counts every status. | | `filings.deleted` | integer | no | | | `filings.final` | integer | no | | | `filings.provisional` | integer | no | | | `filings.total` | integer | no | | | `gaps` | object \| null | yes | Known coverage gaps, from a list maintained by hand and read when the server starts: feed days absent from the archive, feed days SEC delivered truncated, and filings no feed delivers. Null when this deployment has no list. | | `live` | object \| null | yes | Live ingest, read per request from the daemon's newest session (at most once every 2 s for the whole process). Null when this deployment has no live ingest. | | `live.check` | string | no | As checks.live of /v3/health. One of: `ok`, `paused`, `degraded`, `down`. | | `live.covered_until` | date-time (RFC 3339, UTC) \| null | no | SEC's list of new filings has been read without a gap up to here. | | `live.last_new_filing_at` | date-time (RFC 3339, UTC) \| null | no | When the newest filing was first seen. | | `live.median_lag_seconds` | integer \| null | no | Median seconds from SEC's acceptance to the filing being seen, over the daemon's current New York day; null with fewer than 5 filings that day, and when the figure is negative or absurd. | | `live.mode` | string \| null | no | One of: `live`, `dry_run`, `null`. | | `live.state` | string \| null | no | The daemon's own state in its last heartbeat, as live.state of /v3/health without the dry_run substitution. | | `stream` | object \| null | yes | The filing stream, computed with the counts. Null when this deployment has no stream. | | `stream.computed_at` | date-time (RFC 3339, UTC) | no | When the stream block was computed, UTC. | | `stream.head_seq` | integer \| null | no | The last stream seq the sequencer assigned; null before its first pass. | | `stream.latency` | object | no | | | `stream.latency.from_accepted` | object | no | Seconds from SEC's acceptance to the filing.new event, over live filings of the last 24 hours (nearest-rank percentiles; n is the number of filings, zeros when it is 0). | | `stream.latency.from_accepted.n` | integer | no | | | `stream.latency.from_accepted.p50` | number \| null | no | Null when n is 0. | | `stream.latency.from_accepted.p95` | number \| null | no | Null when n is 0. | ## Example request ```bash curl -sS 'https://api.secblast.com/v3/coverage/summary' ``` [Open this route in the console](https://www.secblast.com/console#get-v3-coverage-summary) ## More in Coverage, usage and service Previous: [`GET /v3/coverage/count`](https://www.secblast.com/docs/reference/get-coverage-count) · Next: [`GET /v3/forms`](https://www.secblast.com/docs/reference/get-forms) --- # GET /v3/forms Form types present (deleted filings excluded) with filing counts, most frequent first. Computed in the background, never by a request: once at start and then every few minutes (5 by default; less often when a computation is slow); computed_at says when, and the list is served until the next computation replaces it. Until the first computation after a start has finished the answer is 503 with code warming_up and Retry-After. **API key:** required. See [Authentication](https://www.secblast.com/docs/authentication). **Group:** [Coverage, usage and service](https://www.secblast.com/docs/reference#coverage-usage-and-service) ## Parameters This route takes no parameters. ## Responses | Status | Body | Description | |---|---|---| | `200` | [FormList](https://www.secblast.com/docs/reference/schemas#schema-formlist) (`application/json`) | OK | | `401` | [Problem](https://www.secblast.com/docs/reference/schemas#schema-problem) (`application/problem+json`) | Missing, invalid or inactive API key (code unauthorized), or a refused access token (code invalid_token: malformed, unknown key, bad signature, expired, wrong issuer or audience, revoked grant). WWW-Authenticate names the protected-resource metadata (RFC 9728). | | `503` | [Problem](https://www.secblast.com/docs/reference/schemas#schema-problem) (`application/problem+json`) | Database unavailable (code db_unavailable); or the answer, which the server computes in the background, has not been computed yet since it started (code warming_up). Retry the same request after the Retry-After delay. | | `default` | [Problem](https://www.secblast.com/docs/reference/schemas#schema-problem) (`application/problem+json`) | Any other error (405, 500, 504). | ## Response body A `200` carries a [FormList](https://www.secblast.com/docs/reference/schemas#schema-formlist) object. | Field | Type | Required | Description | |---|---|---|---| | `computed_at` | date-time (RFC 3339, UTC) | no | When the list was computed, UTC. It is served until a later computation replaces it. | | `data` | array of [FormCount](https://www.secblast.com/docs/reference/schemas#schema-formcount) | yes | | | `has_more` | boolean | no | | | `next_cursor` | string \| null | no | | ## Example request ```bash curl -sS -H "Authorization: Bearer $SECBLAST_API_KEY" \ 'https://api.secblast.com/v3/forms' ``` [Open this route in the console](https://www.secblast.com/console#get-v3-forms) ## More in Coverage, usage and service Previous: [`GET /v3/coverage/summary`](https://www.secblast.com/docs/reference/get-coverage-summary) · Next: [`GET /v3/health`](https://www.secblast.com/docs/reference/get-health) --- # GET /v3/health Liveness: one database round trip, the document root, and whether the snapshot store is usable. 200 unless the database is down. **API key:** not needed. **Group:** [Coverage, usage and service](https://www.secblast.com/docs/reference#coverage-usage-and-service) ## Parameters This route takes no parameters. ## Responses | Status | Body | Description | |---|---|---| | `200` | [Health](https://www.secblast.com/docs/reference/schemas#schema-health) (`application/json`) | OK | | `503` | [Health](https://www.secblast.com/docs/reference/schemas#schema-health) (`application/json`) | The database is down. | | `default` | [Problem](https://www.secblast.com/docs/reference/schemas#schema-problem) (`application/problem+json`) | Any other error (405, 500, 504). | ## Response body A `200` carries a [Health](https://www.secblast.com/docs/reference/schemas#schema-health) object. | Field | Type | Required | Description | |---|---|---|---| | `checks` | object | yes | | | `checks.callbacks` | string | no | Webhook delivery, judged per organization: the lateness of the least late organization among those with a first attempt due or one made in the last minute (one organization's own backlog does not count while others are served on time). ok: at most 60 s past due. degraded: up to 5 minutes. down: more, or the delivery table cannot be read (also while the database is down). degraded and down make the status degraded at any hour, never an outage. disabled: this deployment has no webhook delivery. One of: `ok`, `degraded`, `down`, `disabled`. | | `checks.db` | string | no | One of: `ok`, `fail`. | | `checks.docs_root` | string | no | One of: `ok`, `missing`. | | `checks.live` | string | no | Live ingest (the daemon that registers filings seconds after SEC accepts them). ok: its heartbeat is at most 45 s old and it is polling, idle outside the window, or catching up. paused: SEC refused a request; nothing is sent until live.paused_until, and the 30 careful minutes after. degraded: SEC unreachable, database down, disk low, or halted after repeated pauses. down: no heartbeat (not running, stopping, or its status could not be read). disabled: this deployment has no live ingest. One of: `ok`, `paused`, `degraded`, `down`, `disabled`. | | `checks.mcp` | string | no | The MCP server sb_mcp_v3 (its /healthz, probed at most every 5 s). disabled: this deployment does not name one. Informational: it never changes status. One of: `ok`, `down`, `disabled`. | | `checks.store` | string | no | The snapshot store. stale: its snapshot is more than 3 days old (still used). loading: no snapshot served yet. disabled: not configured. One of: `ok`, `stale`, `loading`, `unavailable`, `disabled`. | | `checks.stream` | string | no | The filing stream (the sequencer that writes the log behind /v3/stream). ok: it wrote its cursor at most 30 s ago. stale: the cursor is older, or there is none; the status is then degraded, never an outage. stale also when the database cannot be read. disabled: this deployment has no stream. One of: `ok`, `stale`, `disabled`. | | `live` | object | no | Present only when live ingest is enabled. Counts and the full heartbeat are on /v3/coverage, which needs a key. | | `live.lag_seconds` | integer \| null | no | Median seconds from SEC's acceptance to the filing being seen, over the last 15 minutes; null with fewer than 5 filings, and when the figure is negative or absurd. | | `live.last_new_filing_at` | date-time (RFC 3339, UTC) \| null | no | When the newest filing was first seen. | | `live.last_poll_at` | date-time (RFC 3339, UTC) \| null | no | The last successful poll of SEC's list of new filings. | | `live.paused_until` | date-time (RFC 3339, UTC) \| null | no | End of a pause in force; null otherwise. | | `live.state` | string \| null | no | The daemon's own state in its last heartbeat (ok, idle, catching_up, paused, cautious, sec_unreachable, db_down, disk_low, halted, stopping, stopped, failed), or dry_run when the daemon that answers is a dry run (it registers no filings; checks.live is then never ok); null without a heartbeat or when it is none of these. It is the daemon's last word, so a daemon that died still shows its last state: checks.live is the judgement, which also knows how old the heartbeat is and whether the session ended. | | `metering` | object | no | Only when the API runs with a metering switches file (one in force, or one that was refused): the mode of each feature; config (ok \| refused: the file cannot be read or is invalid, and the previous switches, or all off, stay), config_error and config_last_good (when a valid file was last taken); the usage flusher (last success, pending records, failures, events written and dropped, whether the month was read back); the age of the cached entitlements; entitlements_statement (unchecked \| ok \| insufficient_privilege \| failed: whether this role can run the entitlements statement, which reads v3_acct_entitlements and v3_usage_rollup_state; updated by every entitlements read, and checked actively while a feature is enforced) and entitlements_error; limits_unknown (requests served without limits because their org's limits could not be read); and the refusal counters. It makes status degraded, never an outage, while the file is refused, or while a feature is enforced and entitlements_statement is insufficient_privilege. | | `status` | string | yes | degraded unless every check is ok and the metering block (when present) is not degraded (a store that is not configured does not degrade; live ingest counts only when it is enabled, and only on a weekday between 06:00 and 22:00 New York time, when SEC accepts filings; the filing stream and webhook delivery count only when enabled, at any hour). The HTTP status is 503 only when the database is down. One of: `ok`, `degraded`. | | `store` | object | no | The snapshot in use. Counts and load details are on /v3/coverage, which needs a key. | | `store.available` | boolean | no | | | `store.snapshot_date` | date (YYYY-MM-DD) \| null | no | | | `store.stale` | boolean \| null | no | | | `time` | date-time (RFC 3339, UTC) | no | | | `version` | string | no | | ## Example request ```bash curl -sS 'https://api.secblast.com/v3/health' ``` [Open this route in the console](https://www.secblast.com/console#get-v3-health) ## More in Coverage, usage and service Previous: [`GET /v3/forms`](https://www.secblast.com/docs/reference/get-forms) · Next: [`GET /v3/openapi.json`](https://www.secblast.com/docs/reference/get-openapi-json) --- # GET /v3/openapi.json This OpenAPI 3.1 document. **API key:** not needed. **Group:** [Coverage, usage and service](https://www.secblast.com/docs/reference#coverage-usage-and-service) ## Parameters This route takes no parameters. ## Responses | Status | Body | Description | |---|---|---| | `200` | [OpenApi](https://www.secblast.com/docs/reference/schemas#schema-openapi) (`application/json`) | OK | | `503` | [Problem](https://www.secblast.com/docs/reference/schemas#schema-problem) (`application/problem+json`) | Database unavailable; retry after the Retry-After delay. | | `default` | [Problem](https://www.secblast.com/docs/reference/schemas#schema-problem) (`application/problem+json`) | Any other error (405, 500, 504). | ## Response body A `200` carries a [OpenApi](https://www.secblast.com/docs/reference/schemas#schema-openapi) object. ## Example request ```bash curl -sS 'https://api.secblast.com/v3/openapi.json' ``` [Open this route in the console](https://www.secblast.com/console#get-v3-openapi-json) ## More in Coverage, usage and service Previous: [`GET /v3/health`](https://www.secblast.com/docs/reference/get-health) · Next: [`GET /v3/usage`](https://www.secblast.com/docs/reference/get-usage) --- # GET /v3/usage The calling key's limits and this month's usage: requests and billable response bytes (measured before compression; 5xx and 429 not billable) of its organization and of the key itself, what is left of the monthly allowance, when it starts again, and which limits are enforced. Never refused for an exhausted allowance. Every authenticated answer of the API may carry RateLimit-Policy and RateLimit (draft-ietf-httpapi-ratelimit-headers) and X-Quota-\* headers while those limits are enforced; over a limit the answer is 429 with code rate_limited (per-second rate, Retry-After) or quota_exceeded (monthly allowance), and 403 with code blocked for a suspended organization. **API key:** required. See [Authentication](https://www.secblast.com/docs/authentication). **Group:** [Coverage, usage and service](https://www.secblast.com/docs/reference#coverage-usage-and-service) ## Parameters This route takes no parameters. ## Responses | Status | Body | Description | |---|---|---| | `200` | [Usage](https://www.secblast.com/docs/reference/schemas#schema-usage) (`application/json`) | OK | | `401` | [Problem](https://www.secblast.com/docs/reference/schemas#schema-problem) (`application/problem+json`) | Missing, invalid or inactive API key (code unauthorized), or a refused access token (code invalid_token: malformed, unknown key, bad signature, expired, wrong issuer or audience, revoked grant). WWW-Authenticate names the protected-resource metadata (RFC 9728). | | `503` | [Problem](https://www.secblast.com/docs/reference/schemas#schema-problem) (`application/problem+json`) | Database unavailable; retry after the Retry-After delay. | | `default` | [Problem](https://www.secblast.com/docs/reference/schemas#schema-problem) (`application/problem+json`) | Any other error (405, 500, 504). | ## Response body A `200` carries a [Usage](https://www.secblast.com/docs/reference/schemas#schema-usage) object. | Field | Type | Required | Description | |---|---|---|---| | `as_of` | date-time (RFC 3339, UTC) | yes | | | `enforcement` | object | yes | Each feature: off, observe (counted and logged, never refused) or enforce. | | `key` | object | yes | | | `key.bytes` | integer \| null | no | | | `key.fingerprint` | string | no | First 12 hex digits of the key's SHA-256. | | `key.requests` | integer \| null | no | | | `limits` | object \| null | yes | Null while no limit is applied (metering off) and for a key without an organization. | | `limits.burst` | integer \| null | no | | | `limits.exempt` | object \| null | no | Null, or the caller's exemption from the rate limit (and, when concurrency is true, from the concurrency cap). The transfer allowance still applies. | | `limits.exempt.concurrency` | boolean | no | | | `limits.exempt.expires_at` | date-time (RFC 3339, UTC) \| null | no | When the exemption ends; null = no end set. | | `limits.exempt.rate` | boolean | no | | | `limits.exempt.scope` | string | no | key: this key; org: every credential of the organization; config: the server's configuration. One of: `key`, `org`, `config`. | | `limits.monthly_bytes` | integer \| null | no | Included response bytes per month (measured before compression); null = unlimited. | | `limits.monthly_requests` | integer \| null | no | | | `limits.requests_per_second` | integer \| null | no | Null while the caller is exempt from the rate limit. | | `month` | string | yes | The month counted, YYYY-MM: the calendar month in New York time (America/New_York). | | `org` | object | yes | This month, all keys of the organization (a legacy key: that key). Null members while usage is not counted. | | `org.bytes` | integer \| null | no | Billable response bytes (5xx and 429 excluded). | | `org.bytes_remaining` | integer \| null | no | | | `org.requests` | integer \| null | no | | | `org_id` | integer \| null | yes | The organization of the key; null for a legacy key not attributed to one. | | `plan` | string \| null | yes | The organization's plan id; null when its entitlements are not known (default limits apply). | | `reset_at` | date-time (RFC 3339, UTC) | yes | When the monthly allowance starts again: the start of the next month, midnight in New York (04:00 or 05:00 UTC). | ## Example request ```bash curl -sS -H "Authorization: Bearer $SECBLAST_API_KEY" \ 'https://api.secblast.com/v3/usage' ``` [Open this route in the console](https://www.secblast.com/console#get-v3-usage) ## More in Coverage, usage and service Previous: [`GET /v3/openapi.json`](https://www.secblast.com/docs/reference/get-openapi-json) --- # Schemas The objects the routes take and return. Fields of nested objects are written with dots; `[]` marks the items of an array. ## Schema: Addresses | Field | Type | Required | Description | |---|---|---|---| | `business` | object \| null | no | {street1, street2, city, state, zip, phone} as filed. | | `mail` | object \| null | no | | ## Schema: CallbackAttempt | Field | Type | Required | Description | |---|---|---|---| | `at` | date-time (RFC 3339, UTC) | yes | | | `duration_ms` | integer \| null | yes | | | `error_class` | string \| null | yes | One of: `timeout`, `connect`, `tls`, `dns`, `blocked_address`, `redirect`, `http`, `too_large`, `null`. | | `http_status` | integer \| null | yes | Null when no status line was received. | | `n` | integer | yes | 1 for the first attempt. | | `remote_ip` | string \| null | yes | The address connected to. | | `response_excerpt` | string \| null | yes | The first 512 bytes of the endpoint's answer. | ## Schema: CallbackDelivery One delivery of a webhook event to one endpoint. | Field | Type | Required | Description | |---|---|---|---| | `accession` | string \| null | yes | The filing's accession number, for filing events. | | `attempt_count` | integer | yes | Attempts made so far; a manual retry or a replay continues the count. | | `billed_bytes` | integer | yes | The payload bytes billed: the payload size once the endpoint answered 2xx, else 0. Failed attempts, test events and endpoint verification are not billed. | | `created_at` | date-time (RFC 3339, UTC) | yes | | | `delivered_at` | date-time (RFC 3339, UTC) \| null | yes | | | `endpoint_id` | string | yes | cbe_ and 24 hex digits. | | `held_reason` | string \| null | yes | Only while state is held. One of: `quota_exceeded`, `plan_required`, `endpoint_disabled`, `endpoint_unverified`, `digest`, `null`. | | `id` | string | yes | dlv_ and 24 hex digits. | | `last_attempt_at` | date-time (RFC 3339, UTC) \| null | yes | When the newest attempt was made; null before the first. | | `last_error` | string \| null | yes | Why the last attempt failed (an error class such as timeout, or gone, quota_exceeded, plan_required, hold_expired, endpoint_inactive, superseded: a verification challenge replaced by a newer one before it was sent). | | `last_status` | integer \| null | yes | The HTTP status of the last attempt that got one. | | `next_attempt_at` | date-time (RFC 3339, UTC) \| null | yes | When the next attempt is due; only while state is pending. | | `state` | string | yes | pending: waiting for its next attempt. held: waiting for a condition (held_reason). delivering: an attempt is in flight. delivered: the endpoint answered 2xx. failed: every attempt failed, or the endpoint answered 410, or a hold ran out (last_error says which). dropped: the endpoint was inactive or the hold on an unverified or disabled endpoint ran out, or (a verification) a newer challenge replaced it. One of: `pending`, `held`, `delivering`, `delivered`, `failed`, `dropped`. | | `subscription_id` | string \| null | yes | sub_ and 24 hex digits; null for an event that belongs to no subscription. | | `type` | string | yes | The event type, for example filing.new. | ## Schema: CallbackDeliveryDetail | Field | Type | Required | Description | |---|---|---|---| | `accession` | string \| null | yes | The filing's accession number, for filing events. | | `attempt_count` | integer | yes | Attempts made so far; a manual retry or a replay continues the count. | | `billed_bytes` | integer | yes | The payload bytes billed: the payload size once the endpoint answered 2xx, else 0. Failed attempts, test events and endpoint verification are not billed. | | `created_at` | date-time (RFC 3339, UTC) | yes | | | `delivered_at` | date-time (RFC 3339, UTC) \| null | yes | | | `endpoint_id` | string | yes | cbe_ and 24 hex digits. | | `held_reason` | string \| null | yes | Only while state is held. One of: `quota_exceeded`, `plan_required`, `endpoint_disabled`, `endpoint_unverified`, `digest`, `null`. | | `id` | string | yes | dlv_ and 24 hex digits. | | `last_attempt_at` | date-time (RFC 3339, UTC) \| null | yes | When the newest attempt was made; null before the first. | | `last_error` | string \| null | yes | Why the last attempt failed (an error class such as timeout, or gone, quota_exceeded, plan_required, hold_expired, endpoint_inactive, superseded: a verification challenge replaced by a newer one before it was sent). | | `last_status` | integer \| null | yes | The HTTP status of the last attempt that got one. | | `next_attempt_at` | date-time (RFC 3339, UTC) \| null | yes | When the next attempt is due; only while state is pending. | | `state` | string | yes | pending: waiting for its next attempt. held: waiting for a condition (held_reason). delivering: an attempt is in flight. delivered: the endpoint answered 2xx. failed: every attempt failed, or the endpoint answered 410, or a hold ran out (last_error says which). dropped: the endpoint was inactive or the hold on an unverified or disabled endpoint ran out, or (a verification) a newer challenge replaced it. One of: `pending`, `held`, `delivering`, `delivered`, `failed`, `dropped`. | | `subscription_id` | string \| null | yes | sub_ and 24 hex digits; null for an event that belongs to no subscription. | | `type` | string | yes | The event type, for example filing.new. | | `attempts` | array of [CallbackAttempt](#schema-callbackattempt) | yes | Every attempt, oldest first; empty before the first. | | `payload` | object | yes | The event as sent, the body of the request. | ## Schema: CallbackDeliveryList | Field | Type | Required | Description | |---|---|---|---| | `data` | array of [CallbackDelivery](#schema-callbackdelivery) | yes | | | `next_cursor` | string \| null | yes | Pass it as cursor for the next page; null on the last page. | ## Schema: CallbackEndpoint A webhook endpoint of the caller's organization. The signing secret is never part of it. | Field | Type | Required | Description | |---|---|---|---| | `active` | boolean | yes | | | `created_at` | date-time (RFC 3339, UTC) | yes | | | `description` | string \| null | yes | | | `event_types` | array of string | yes | | | `health` | object | yes | | | `health.consecutive_failures` | integer | no | | | `health.disabled_at` | date-time (RFC 3339, UTC) \| null | no | | | `health.disabled_reason` | string \| null | no | | | `health.failing_since` | date-time (RFC 3339, UTC) \| null | no | | | `health.last_success_at` | date-time (RFC 3339, UTC) \| null | no | | | `health.state` | string | yes | One of: `unverified`, `active`, `failing`, `disabled`. | | `health.verified_at` | date-time (RFC 3339, UTC) \| null | no | | | `id` | string | yes | cbe_ and 24 hex digits. | | `last_24h` | object | yes | Deliveries of the last 24 hours by state. | | `last_24h.delivered` | integer | no | | | `last_24h.dropped` | integer | no | | | `last_24h.failed` | integer | no | | | `last_24h.held` | integer | no | | | `updated_at` | date-time (RFC 3339, UTC) | yes | | | `url` | string | yes | As stored: https, the host in lower case, no :443, / for an empty path. | ## Schema: CallbackEndpointCreate | Field | Type | Required | Description | |---|---|---|---| | `description` | string \| null | no | At most 800 bytes. | | `event_types` | array of string | yes | | | `url` | string | yes | https only, port 443 only, no user name or password, a public DNS name (not an IP address, localhost, .local or .internal) of letters, digits and hyphens (an international name in its xn-- form) that resolves to a public address; at most 2,048 characters. | ## Schema: CallbackEndpointCreated | Field | Type | Required | Description | |---|---|---|---| | `active` | boolean | yes | | | `created_at` | date-time (RFC 3339, UTC) | yes | | | `description` | string \| null | yes | | | `event_types` | array of string | yes | | | `health` | object | yes | | | `health.consecutive_failures` | integer | no | | | `health.disabled_at` | date-time (RFC 3339, UTC) \| null | no | | | `health.disabled_reason` | string \| null | no | | | `health.failing_since` | date-time (RFC 3339, UTC) \| null | no | | | `health.last_success_at` | date-time (RFC 3339, UTC) \| null | no | | | `health.state` | string | yes | One of: `unverified`, `active`, `failing`, `disabled`. | | `health.verified_at` | date-time (RFC 3339, UTC) \| null | no | | | `id` | string | yes | cbe_ and 24 hex digits. | | `last_24h` | object | yes | Deliveries of the last 24 hours by state. | | `last_24h.delivered` | integer | no | | | `last_24h.dropped` | integer | no | | | `last_24h.failed` | integer | no | | | `last_24h.held` | integer | no | | | `updated_at` | date-time (RFC 3339, UTC) | yes | | | `url` | string | yes | As stored: https, the host in lower case, no :443, / for an empty path. | | `secret` | string | yes | whsec_ and the standard base64 (with padding) of 32 random bytes: the Standard Webhooks signing secret. Shown only in this answer. | ## Schema: CallbackEndpointList | Field | Type | Required | Description | |---|---|---|---| | `data` | array of [CallbackEndpoint](#schema-callbackendpoint) | yes | | | `has_more` | boolean | yes | | | `limits` | object | yes | | | `limits.endpoints` | object | no | | | `limits.endpoints.limit` | integer \| null | no | The plan's limit; 0 without callbacks. | | `limits.endpoints.used` | integer | no | Active endpoints. | | `next_cursor` | string \| null | yes | | ## Schema: CallbackEndpointPatch | Field | Type | Required | Description | |---|---|---|---| | `active` | boolean | no | true on an inactive endpoint counts against the plan's limit. | | `description` | string \| null | no | null clears it. | | `event_types` | array of string | no | | | `url` | string | no | | ## Schema: CallbackEndpointTestRequest | Field | Type | Required | Description | |---|---|---|---| | `type` | string | yes | One of the endpoint's event_types. The sample event has this type and test: true in its envelope; there is no separate test type. One of: `filing.new`, `filing.updated`, `filing.corrected`, `filing.deleted`, `search.match`, `search.digest`, `filing.digest`, `search.export.completed`. | ## Schema: CallbackEndpointTestResult | Field | Type | Required | Description | |---|---|---|---| | `delivered` | boolean | no | 200 only: the endpoint answered 2xx. | | `duration_ms` | integer \| null | no | 200 only: the attempt's duration. | | `error_class` | string \| null | no | 200 only. One of: `timeout`, `connect`, `tls`, `dns`, `blocked_address`, `redirect`, `http`, `too_large`, `null`. | | `http_status` | integer \| null | no | 200 only: the endpoint's status; null when no HTTP answer came. | | `id` | string | yes | The test delivery's id (dlv_ and 24 hex digits), in the delivery log. | | `state` | string | yes | 200: delivered, failed or dropped (the attempt's outcome is final: a test send is attempted once). 202: still pending, delivering or held when the 12 seconds ran out; the delivery is still made, and its outcome is in the delivery log. One of: `pending`, `delivering`, `held`, `delivered`, `failed`, `dropped`. | ## Schema: CallbackReplayRequest | Field | Type | Required | Description | |---|---|---|---| | `from` | string | yes | Start of the window of created_at, inclusive: YYYY-MM-DDTHH:MM:SSZ, or YYYY-MM-DD for midnight UTC. | | `states` | array of string | no | Default both. | | `to` | string | no | End of the window, exclusive, same forms; default now. The window is at most 30 days. | | `types` | array of string | no | Only deliveries of these event types; default every type. | ## Schema: CallbackReplayResult | Field | Type | Required | Description | |---|---|---|---| | `last_created_at` | date-time (RFC 3339, UTC) \| null | yes | When truncated: the created_at (whole seconds) of the last delivery requeued; replay again with the same to, states and types and from set to it. | | `replayed` | integer | yes | Deliveries requeued. | | `truncated` | boolean | yes | true when more than 10,000 deliveries matched; the oldest 10,000 were requeued. | ## Schema: CallbackRetryRequest No members; the body is optional. An object with no fixed fields. ## Schema: CallbackRotateSecret | Field | Type | Required | Description | |---|---|---|---| | `expire_previous_in_s` | integer | no | How long the previous secret still signs beside the new one; 0: not at all. | ## Schema: CallbackVerifyRequest No members; the body is optional. The challenge goes to the endpoint's stored url. An object with no fixed fields. ## Schema: Coverage | Field | Type | Required | Description | |---|---|---|---| | `computed_at` | date-time (RFC 3339, UTC) | no | When data (the per-day part) was computed, UTC. The value is served until a later computation replaces it. | | `data` | array of [CoverageDay](#schema-coverageday) | yes | Per feed day, the latest non-superseded ingest run; newest day first. At most window.max_days days: the newest ones of the window. The default window is recomputed in the background every few minutes, an explicit one by a request at most once a minute; computed_at says when. | | `live` | object \| null | no | Live ingest: the daemon's last heartbeat (it writes one every 10 s). Null when there is none or live ingest is not enabled. It can be old: live_check says what to make of it. Only the members listed here are given, each checked: a number outside 0..10^15, a time that is not one, or a word outside its list is null, and no free text of the daemon is passed on. | | `live.covered_until` | date-time (RFC 3339, UTC) \| null | no | SEC's list of new filings has been read without a gap up to here. | | `live.ended` | string \| null | no | How the session ended; null while it runs. The reason is in the daemon's log, not here. One of: `clean`, `failed`, `null`. | | `live.fetch` | object | no | requests, http_404, http_429, http_5xx, network, integrity, too_large, bytes, and recent {requests, failed}. | | `live.filings` | object | no | Counts since the session started: seen, listed, documents, failed, skipped_known, and per_min_1, per_min_5, per_min_peak. | | `live.heartbeat_at` | date-time (RFC 3339, UTC) \| null | no | | | `live.items_unmapped` | number \| null | no | 8-K item descriptions seen without an item code. | | `live.last_new_accession` | string \| null | no | | | `live.last_new_filing_at` | date-time (RFC 3339, UTC) \| null | no | | | `live.latency_ms` | object | no | recent (the last window_s seconds) and day: n, and p50 / p95 of accept_to_seen, seen_to_listed, seen_to_documents. | | `live.limiter` | object | no | The shared SEC request limiter as the daemon sees it: priority (on, off, unavailable), wait_ms {p50, p95}, waits_over_1s, refused. | | `live.mode` | string \| null | no | One of: `live`, `dry_run`, `null`. | | `live.paused_until` | date-time (RFC 3339, UTC) \| null | no | | | `live.pauses_24h` | number \| null | no | | | `live.poll` | object | no | Counts of polls and sweeps of SEC's list; rtt_ms and skew_ms in milliseconds. | | `live.poll.below_page0` | number \| null | no | | | `live.poll.failed` | number \| null | no | | | `live.poll.last_ok_at` | date-time (RFC 3339, UTC) \| null | no | | | `live.poll.last_poll_failed` | boolean | no | Whether the last poll failed. The error text stays in the daemon's log. | | `live.poll.ok` | number \| null | no | | | `live.poll.out_of_order` | number \| null | no | | | `live.poll.overflows` | number \| null | no | | | `live.poll.pages_swept` | number \| null | no | | | `live.poll.rtt_ms` | object | no | | | `live.poll.skew_ms` | number \| null | no | | | `live.poll.sweeps` | object | no | | | `live.poll.sweeps_abandoned` | number \| null | no | | | `live.poll.sweeps_exhausted` | number \| null | no | | | `live.poll.uncovered` | array of object | no | Spans of SEC's list a sweep could not cover (the nightly feed covers those filings); at most 50. | | `live.poll.uncovered[].at` | date-time (RFC 3339, UTC) \| null | no | | | `live.poll.uncovered[].from` | date-time (RFC 3339, UTC) \| null | no | | | `live.poll.uncovered[].reason` | string \| null | no | One of: `max_start`, `page_unanswered`, `null`. | | `live.poll.uncovered[].until` | date-time (RFC 3339, UTC) \| null | no | | | `live.poll_interval_ms` | number \| null | no | | | `live.queue` | object | no | fetch_fresh, fetch_backlog, build, retry, oldest_age_s, behind_since. | | `live.roles_unmapped` | integer | no | Role strings of SEC's list that have no v3 role (how many, not which). | | `live.schema` | number \| null | no | | | `live.started_at` | date-time (RFC 3339, UTC) \| null | no | | | `live.state` | string \| null | no | One of: `ok`, `idle`, `catching_up`, `paused`, `cautious`, `sec_unreachable`, `db_down`, `disk_low`, `halted`, `stopping`, `stopped`, `failed`, `null`. | | `live.window_open` | boolean \| null | no | | | `live_check` | string | no | As checks.live of /v3/health. One of: `ok`, `paused`, `degraded`, `down`, `disabled`. | | `snapshot` | object | yes | The snapshot store and the snapshot it serves. | | `snapshot.accessions` | integer \| null | no | Distinct filings in the snapshot. | | `snapshot.age_days` | integer \| null | no | | | `snapshot.available` | boolean | no | | | `snapshot.date` | date (YYYY-MM-DD) \| null | no | | | `snapshot.fallback` | boolean \| null | no | A newer snapshot exists but could not be loaded. | | `snapshot.filers` | integer \| null | no | | | `snapshot.filings` | integer \| null | no | Filing listings in the snapshot (a filing listed by two filers counts twice). | | `snapshot.loaded_at` | date-time (RFC 3339, UTC) \| null | no | | | `snapshot.reloading` | boolean \| null | no | A newer snapshot is being loaded; the current one keeps serving. | | `snapshot.stale` | boolean \| null | no | The snapshot is more than 3 days old. | | `snapshot.state` | string | no | One of: `ok`, `stale`, `loading`, `unavailable`, `disabled`. | | `snapshot.tickers_date` | date (YYYY-MM-DD) \| null | no | Newest copy of SEC's ticker file. | | `snapshot.tickers_from` | date (YYYY-MM-DD) \| null | no | Oldest copy kept. | | `totals` | object | yes | Table-wide totals, whatever the window; recomputed in the background every few minutes (5 by default). They are served until a later computation replaces them: when one fails, the previous totals stay, and computed_at shows their age. | | `totals.accepted_at_stored` | integer | no | Filings with an acceptance time stored in v3 (any source: a header time, or SEC's from the snapshot sync). | | `totals.amendments` | integer | no | Amendments, deleted ones excluded. | | `totals.amendments_resolved` | integer | no | Of those amendments, the ones linked to their original. | | `totals.computed_at` | date-time (RFC 3339, UTC) | no | When the totals were computed, UTC. | | `totals.deleted_filings` | integer | no | | | `totals.documents` | integer | no | | | `totals.filings` | integer | no | | | `totals.max_feed_date` | date (YYYY-MM-DD) \| null | no | | | `totals.max_filing_date` | date (YYYY-MM-DD) \| null | no | | | `totals.min_feed_date` | date (YYYY-MM-DD) \| null | no | | | `totals.min_filing_date` | date (YYYY-MM-DD) \| null | no | | | `truncated` | boolean | yes | True when the window holds more feed days than max_days: the older ones are left out. Ask for them with from / to. | | `window` | object | yes | The window of feed days this answer covers. | | `window.default` | boolean | no | True when neither from nor to was given: the last 90 feed days. | | `window.from` | date (YYYY-MM-DD) \| null | no | The from that was asked for; without one, the oldest day listed (null when no day is listed). | | `window.max_days` | integer | no | The most days one answer lists: 90 for the default window, 366 when from or to is given. | | `window.to` | date (YYYY-MM-DD) \| null | no | The to that was asked for; without one, the newest day listed (null when no day is listed). | ## Schema: CoverageCount | Field | Type | Required | Description | |---|---|---|---| | `as_of` | date-time (RFC 3339, UTC) | yes | When these figures were read, UTC (every few seconds; 5 by default). | | `deleted` | integer | yes | Filings SEC deleted (status deleted), now. Not counted in filings; they are still served. | | `documents` | integer | yes | Current documents, counted as documents of /v3/coverage/summary (one per document of each filing, deleted filings included) plus those of filings registered since. Never goes down within a running server. | | `filings` | integer | yes | Filings in v3 that are not deleted: final and provisional (filings_basis). Never goes down between two answers of a running server except after a deletion. A filing registered with an old acceptance time (a backfill) is added at the next computation of /v3/coverage/summary, at most about 20 minutes later; right after that computation filings equals its filings.final + filings.provisional. | | `filings_basis` | string | yes | What filings counts: final and provisional filings; deleted filings are not counted. One of: `final_and_provisional`. | | `latest_accepted_at` | date-time (RFC 3339, UTC) \| null | yes | The newest SEC acceptance time of a filing that is not deleted. | | `live` | object \| null | yes | Live ingest latency over the daemon's current New York day, from its own status, read with the counts. "seen" is when SEC Blast's poll of SEC's list of new filings first saw the filing. SEC publishes no time at which a filing appears in that list, so the time from SEC publishing a filing to it being seen is not measured; it is bounded by poll_interval_ms. Null when this deployment has no live ingest. | | `live.accept_to_seen_ms` | object | no | SEC's acceptance time to seen, milliseconds. | | `live.accept_to_seen_ms.p50` | number \| null | no | | | `live.accept_to_seen_ms.p95` | number \| null | no | | | `live.check` | string | no | As checks.live of /v3/health. One of: `ok`, `paused`, `degraded`, `down`. | | `live.n` | integer \| null | no | Filings whose documents live ingest stored that day. | | `live.poll_interval_ms` | number \| null | no | The daemon's current interval between two polls of SEC's list. | | `live.seen_to_documents_ms` | object | no | Seen to the filing's documents being stored and registered, milliseconds. | | `live.seen_to_documents_ms.p50` | number \| null | no | | | `live.seen_to_documents_ms.p95` | number \| null | no | | | `live.seen_to_stored_ms` | object | no | Seen to the filing being registered in the database (from then on the API lists it, provisional), milliseconds. | | `live.seen_to_stored_ms.p50` | number \| null | no | | | `live.seen_to_stored_ms.p95` | number \| null | no | | | `live.window` | string | no | The figures cover the daemon's current New York day. One of: `day`. | | `live.window_open` | boolean \| null | no | The daemon is in its business-hours window (fast polling). | | `provisional` | integer | yes | Filings registered by live ingest and not yet confirmed by SEC's nightly feed (status provisional), now. | | `summary_computed_at` | date-time (RFC 3339, UTC) \| null | yes | computed_at of the /v3/coverage/summary counts these figures add to. | ## Schema: CoverageDay | Field | Type | Required | Description | |---|---|---|---| | `day` | date (YYYY-MM-DD) | no | | | `filings` | integer | no | Filings whose feed_date is this day. | | `finished_at` | date-time (RFC 3339, UTC) \| null | no | | | `members_failed` | integer | no | | | `members_ok` | integer | no | | | `members_skipped` | integer | no | | | `members_total` | integer | no | | | `realtime` | object \| null | no | Live ingest activity, from the daemon's session records of this New York calendar day that ran in mode live (dry runs are left out); null when there is none or live ingest is not enabled. Not the live view of this feed day's filings: a filing accepted after 17:30 belongs to the next feed day, weekend sessions fall on no feed day, and today's activity is in the top-level live until the nightly feed has run. | | `realtime.documents` | integer | no | Filings whose documents were registered (on the day that happened, which can be the day after the filing was seen). | | `realtime.failed` | integer | no | Filings whose documents could not be fetched; the feed supplies them. | | `realtime.latency_ms` | object \| null | no | The newest session's latency figures for its day: n, and p50 / p95 of accept_to_seen, seen_to_listed, seen_to_documents, in milliseconds. | | `realtime.listed` | integer | no | Filings registered from their header (visible in the API). | | `realtime.seen` | integer | no | Sightings in SEC's list of new filings. Not distinct filings: one in flight across a restart of the daemon is counted again. | | `realtime.sessions` | integer | no | Sessions of the daemon that day (a restart starts a new one). The counts are summed over them. | | `realtime.skipped` | integer | no | Sightings of filings v3 already had; every restart's catch-up adds to it. | | `reconciliation` | object \| null | no | The newest complete reconcile run of the day (a later partial run does not replace it); null when the day has none. | | `reconciliation.chains_deferred` | integer | no | Filings whose version chain was still waiting to be re-ordered with snapshot acceptance times when the run ended; 0 when none. | | `reconciliation.finished_at` | date-time (RFC 3339, UTC) \| null | no | | | `reconciliation.outcomes` | object | no | check name → outcome → row count. Checks: feed_vs_daily_index, feed_vs_submissions, and, for a day live ingest covered, feed_vs_realtime (what the feed's copy changed against the live one: equal_after_normalization, header_changed, docs_added, docs_changed; realtime_missed: in the feed, never seen live; realtime_only: seen live, never delivered by the feed). | | `reconciliation.run_id` | integer | no | | | `reconciliation.status` | string | no | Both comparisons (SEC daily index, submissions snapshot) ran. It does not say that the order of version chains is final: see chains_deferred. One of: `complete`. | | `run_id` | integer | no | | | `started_at` | date-time (RFC 3339, UTC) \| null | no | | | `status` | string | no | One of: `running`, `complete`, `partial`, `source_invalid`, `failed`. | ## Schema: CoverageSummary | Field | Type | Required | Description | |---|---|---|---| | `amendments` | object | yes | Amendment links by link status; amendments of deleted filings are not counted. link_rate is resolved / total, rounded to 4 decimals; null when total is 0. | | `amendments.ambiguous` | integer | no | | | `amendments.link_rate` | number \| null | no | | | `amendments.resolved` | integer | no | | | `amendments.target_not_public` | integer | no | | | `amendments.target_not_yet_ingested` | integer | no | | | `amendments.total` | integer | no | | | `amendments.unresolved` | integer | no | | | `before_1993` | object | yes | Filings whose by_year_basis date is before 1993, deleted filings not counted: paper records keyed in later, and dates SEC mistyped. Not years of coverage, so not in by_year. | | `before_1993.filings` | integer | no | | | `before_1993.first_year` | integer \| null | no | The earliest year counted; null when filings is 0. | | `before_1993.paper` | integer | no | Paper filing records among filings (is_paper). | | `by_year` | array of object | yes | Filings per calendar year of by_year_basis from 1993 (EDGAR's first year), oldest year first; deleted filings are not counted. Filings dated earlier are counted in before_1993. | | `by_year[].filings` | integer | no | | | `by_year[].paper` | integer | no | Paper filing records among filings (is_paper). | | `by_year[].year` | integer | no | | | `by_year_basis` | string | yes | The date by_year groups by. One of: `filing_date`. | | `callbacks` | object \| null | yes | Webhook delivery, computed with the counts. Null when this deployment has no webhook delivery. | | `callbacks.computed_at` | date-time (RFC 3339, UTC) | no | When the callbacks block was computed, UTC. | | `callbacks.latency` | object | no | | | `callbacks.latency.first_attempt_from_accepted` | object | no | Seconds from SEC's acceptance to the first delivery attempt, over the first attempts of the last 24 hours of filing.new and search.match deliveries of live filings (test sends and filings first seen in the nightly feed are left out; nearest-rank percentiles; n is the number of first attempts). | | `callbacks.latency.first_attempt_from_accepted.n` | integer | no | | | `callbacks.latency.first_attempt_from_accepted.p50` | number \| null | no | Null when n is 0. | | `callbacks.latency.first_attempt_from_accepted.p95` | number \| null | no | Null when n is 0. | | `computed_at` | date-time (RFC 3339, UTC) | yes | When the counts were computed, UTC. They are served until a later computation replaces them. | | `document_versions` | integer | yes | Stored document versions, every delivery of every document. | | `documents` | integer | yes | Current documents (one per document of each filing). | | `feed_days` | object | yes | Feed days with a complete or partial ingest run (targeted repair runs not counted). | | `feed_days.count` | integer | no | | | `feed_days.first` | date (YYYY-MM-DD) \| null | no | | | `feed_days.last` | date (YYYY-MM-DD) \| null | no | | | `filings` | object | yes | Filings in v3 by status; total counts every status. | | `filings.deleted` | integer | no | | | `filings.final` | integer | no | | | `filings.provisional` | integer | no | | | `filings.total` | integer | no | | | `gaps` | object \| null | yes | Known coverage gaps, from a list maintained by hand and read when the server starts: feed days absent from the archive, feed days SEC delivered truncated, and filings no feed delivers. Null when this deployment has no list. | | `live` | object \| null | yes | Live ingest, read per request from the daemon's newest session (at most once every 2 s for the whole process). Null when this deployment has no live ingest. | | `live.check` | string | no | As checks.live of /v3/health. One of: `ok`, `paused`, `degraded`, `down`. | | `live.covered_until` | date-time (RFC 3339, UTC) \| null | no | SEC's list of new filings has been read without a gap up to here. | | `live.last_new_filing_at` | date-time (RFC 3339, UTC) \| null | no | When the newest filing was first seen. | | `live.median_lag_seconds` | integer \| null | no | Median seconds from SEC's acceptance to the filing being seen, over the daemon's current New York day; null with fewer than 5 filings that day, and when the figure is negative or absurd. | | `live.mode` | string \| null | no | One of: `live`, `dry_run`, `null`. | | `live.state` | string \| null | no | The daemon's own state in its last heartbeat, as live.state of /v3/health without the dry_run substitution. | | `stream` | object \| null | yes | The filing stream, computed with the counts. Null when this deployment has no stream. | | `stream.computed_at` | date-time (RFC 3339, UTC) | no | When the stream block was computed, UTC. | | `stream.head_seq` | integer \| null | no | The last stream seq the sequencer assigned; null before its first pass. | | `stream.latency` | object | no | | | `stream.latency.from_accepted` | object | no | Seconds from SEC's acceptance to the filing.new event, over live filings of the last 24 hours (nearest-rank percentiles; n is the number of filings, zeros when it is 0). | | `stream.latency.from_accepted.n` | integer | no | | | `stream.latency.from_accepted.p50` | number \| null | no | Null when n is 0. | | `stream.latency.from_accepted.p95` | number \| null | no | Null when n is 0. | ## Schema: Dataset | Field | Type | Required | Description | |---|---|---|---| | `coverage` | object | no | A range, not a statement that every filing in it is parsed. | | `coverage.basis` | string | no | | | `coverage.from` | date (YYYY-MM-DD) \| null | no | | | `coverage.to` | date (YYYY-MM-DD) \| null | no | | | `dataset` | string | no | | | `derive_steps` | array of object | no | | | `derive_steps[].step` | string | no | | | `derive_steps[].version` | string | no | | | `description` | string \| null | no | | | `extractor` | string | no | | | `filings` | object | no | Only when the server is configured to publish it (owner default: off). | | `filings.by_status` | object | no | | | `filings.total` | integer | no | | | `forms` | array of string | no | | | `latest_parsed_at` | date-time (RFC 3339, UTC) \| null | no | | | `links` | object | no | | | `queue` | object | no | The queue of the extractor's active version: its depth. failed (filings the worker gave up on) only with the server option datasets_status_counts. | | `queue.failed` | integer | no | | | `queue.oldest_queued_at` | date-time (RFC 3339, UTC) \| null | no | | | `queue.queued` | integer | no | | | `rows_estimated` | object | no | Estimated rows per table (the planner's statistics); null when never analysed. | | `status` | string | no | One of: `available`, `in_preparation`. | | `tables` | array of string | no | | | `version` | string | no | The deployed extractor version. | ## Schema: DatasetList | Field | Type | Required | Description | |---|---|---|---| | `computed_at` | date-time (RFC 3339, UTC) | yes | | | `data` | array of [Dataset](#schema-dataset) | yes | | | `has_more` | boolean | yes | | | `next_cursor` | string \| null | yes | | ## Schema: DocTableCell | Field | Type | Required | Description | |---|---|---|---| | `col` | integer | no | | | `col_span` | integer | no | | | `currency` | string \| null | no | | | `dash` | boolean | no | | | `fact_ids` | array of string | no | | | `footnotes` | array of string | no | | | `header` | boolean | no | | | `id` | string | no | | | `negative` | boolean | no | | | `numeric` | boolean | no | | | `percent` | boolean | no | | | `punctuation` | boolean | no | | | `row` | integer | no | | | `row_span` | integer | no | | | `scale` | integer \| null | no | The power of ten that applies to this value (0 for per-share amounts and percents). | | `span_end` | integer | no | | | `span_start` | integer | no | | | `text` | string | no | | | `text_end` | integer | no | | | `text_start` | integer | no | | | `value` | string \| null | no | The number as displayed (Decimal string, sign applied, not scaled). | | `value_raw` | string \| null | no | | ## Schema: DocTableOutline | Field | Type | Required | Description | |---|---|---|---| | `block_id` | string | no | | | `block_ordinal` | integer | no | | | `caption` | string \| null | no | | | `column_headers` | array of string | no | | | `extractor_version` | string | no | | | `fact_cells` | integer | no | | | `header_rows` | integer | no | | | `kind` | string | no | One of: `data`, `layout`. | | `kind_reason` | string | no | One of: `values`, `too_small`, `few_values`, `text`, `contents`. | | `n_cols` | integer | no | | | `n_rows` | integer | no | | | `page` | integer | no | | | `per_share_except` | boolean | no | | | `scale` | integer \| null | no | The power of ten the table states (in thousands: 3); null when it states none. | | `scale_source` | string \| null | no | One of: `header`, `caption`, `continued`, `document`, `null`. | | `scale_text` | string \| null | no | | | `span_end` | integer | no | | | `span_start` | integer | no | | | `text_cells` | integer | no | | | `text_end` | integer | no | | | `text_start` | integer | no | | | `value_cells` | integer | no | | ## Schema: DocTables | Field | Type | Required | Description | |---|---|---|---| | `accession` | string | no | | | `cells` | array of [DocTableCell](#schema-doctablecell) \| null | no | | | `cells_reason` | string \| null | no | One of: `model_changed`, `bytes_unavailable`, `rules_changed`, `null`. | | `cells_status` | string | no | One of: `current`, `from_version`, `reparse_pending`. | | `data` | array of [DocTableOutline](#schema-doctableoutline) | no | | | `document` | object \| null | no | | | `extraction` | object | no | | | `filing` | [FilingRef](#schema-filingref) | no | | | `has_more` | boolean | no | | | `next_cursor` | string \| null | no | | | `rules_version` | string | no | | | `table` | [DocTableOutline](#schema-doctableoutline) | no | | ## Schema: Document | Field | Type | Required | Description | |---|---|---|---| | `decode_status` | string | no | One of: `ok`, `repaired`, `failed`. | | `description` | string \| null | no | | | `encoding` | string | no | One of: `text`, `uu`, `base64`. | | `filename` | string | no | | | `is_primary` | boolean | no | | | `mime` | string | no | | | `seq` | integer | no | | | `sha256` | string \| null | no | Hex SHA-256 of the stored bytes; also the ETag. | | `size_bytes` | integer \| null | no | | | `type` | string | no | | | `url` | string | no | | ## Schema: DocumentList | Field | Type | Required | Description | |---|---|---|---| | `data` | array of [Document](#schema-document) | yes | | | `has_more` | boolean | no | | | `next_cursor` | string \| null | no | | ## Schema: EightKEvent | Field | Type | Required | Description | |---|---|---|---| | `confidence` | number | no | | | `event_no` | integer | no | | | `event_type` | string | no | | | `exhibits` | array of object | no | | | `exhibits[].doc_seq` | integer \| null | no | | | `exhibits[].number` | string | no | | | `exhibits[].type` | string \| null | no | | | `exhibits[].url` | string \| null | no | | | `extracted_at` | string | no | | | `extractor_version` | string | no | | | `fields` | array of [EightKEventField](#schema-eightkeventfield) | no | | | `flags` | array of string | no | | | `item_code` | string | no | | | `item_text_end` | integer | no | | | `item_text_start` | integer | no | | | `rules` | string | no | | | `rules_version` | string | no | | ## Schema: EightKEventField | Field | Type | Required | Description | |---|---|---|---| | `confidence` | number | no | rule confidence | | `doc_seq` | integer | no | | | `fiscal_year_end` | string | no | 2.02 period_kind from the fiscal calendar: the fiscal year end used, --MM-DD. | | `fiscal_year_end_source` | string | no | One of: `xbrl`, `sec_header`. | | `name` | string | no | | | `period_kind_source` | string | no | 2.02 period_kind only: derived from period_end and the company's fiscal year end (q1, q2, q3, year_and_q4, other), or the text's reading. One of: `fiscal_calendar`, `text`. | | `rule_id` | string | no | | | `span_end` | integer | no | | | `span_exact` | boolean | no | True: span_start..span_end are exactly the filed characters; false: the enclosing element. | | `span_start` | integer | no | | | `text_end` | integer | no | | | `text_start` | integer | no | | | `value` | any | no | Typed by value_type: a string, an array of strings, YYYY-MM-DD, a boolean, or a Decimal string for a number. | | `value_as_found` | string | no | The filed characters the value was read from. | | `value_type` | string | no | One of: `text`, `text_list`, `date`, `boolean`, `number`. | ## Schema: EightKEventList | Field | Type | Required | Description | |---|---|---|---| | `accuracy` | object | no | Items 1.01 and 2.01 only (served with a field list): served_fields_version, served_fields, event_type_served, holdout, holdout_filings, and per served field (and event_type when served) precision, recall, tp, fp, fn, n on the item's holdout (static). 1.01 serves event_type, cash_per_share, exchange_ratio, price_per_share; 2.01 serves cash_per_share, exchange_ratio, price_per_share, closing_date, with event_type transaction_completed. | | `as_of` | string \| null | no | | | `data` | array of object | no | | | `data[].events` | array of [EightKEvent](#schema-eightkevent) | no | | | `data[].filing` | [FilingRef](#schema-filingref) | no | | | `data[].item_code` | string | no | | | `data[].links` | object | no | | | `has_more` | boolean | no | | | `item` | string | no | | | `next_cursor` | string \| null | no | | | `snapshot` | object | no | | ## Schema: EightKExhibit | Field | Type | Required | Description | |---|---|---|---| | `block_id` | string | no | | | `confidence` | number \| null | no | | | `description` | string \| null | no | | | `found_in` | string | no | | | `item_code` | string \| null | no | | | `link_href` | string \| null | no | | | `number_as_filed` | string | no | | | `row_no` | integer | no | | | `span_end` | integer | no | | | `span_start` | integer | no | | ## Schema: EightKFiling | Field | Type | Required | Description | |---|---|---|---| | `accession` | string | no | | | `document` | object \| null | no | | | `exhibits` | array of [EightKExhibit](#schema-eightkexhibit) | no | | | `extraction` | [Extraction](#schema-extraction) | no | | | `filing` | [FilingRef](#schema-filingref) | no | | | `header_body_agree` | boolean \| null | no | | | `item_sets` | object \| null | no | | | `item_sets.body` | array of any | no | | | `item_sets.header` | array of any | no | | | `item_sets.union` | array of any | no | | | `items` | array of [EightKItem](#schema-eightkitem) | no | | | `links` | object | no | | | `mismatch_kind` | string \| null | no | One of: `none`, `header_omits_901`, `differs`, `null`. | | `snapshot` | [Snapshot](#schema-snapshot) | no | | ## Schema: EightKItem | Field | Type | Required | Description | |---|---|---|---| | `body_status` | string | no | One of: `heading`, `combined_heading`, `not_applicable`, `not_found`. | | `confidence` | number \| null | no | Rule confidence by heading kind (not a probability). | | `flags` | array of string | no | | | `in_body` | boolean | no | | | `in_header` | boolean | no | | | `item_code` | string | no | | | `item_legacy` | string \| null | no | | | `links` | object | no | | | `mapping` | string | no | One of: `none`, `legacy_2004`. | | `section` | string | no | | | `source` | string | no | One of: `header`, `body`, `both`. | | `span_end` | integer \| null | no | | | `span_start` | integer \| null | no | | | `text_end` | integer \| null | no | | | `text_start` | integer \| null | no | | | `title` | string \| null | no | | ## Schema: EightKItemSearchList | Field | Type | Required | Description | |---|---|---|---| | `as_of` | string \| null | no | | | `data` | array of object | no | | | `data[].filing` | [FilingRef](#schema-filingref) | no | | | `data[].item` | [EightKItem](#schema-eightkitem) | no | | | `data[].links` | object | no | | | `data[].mismatch_kind` | string | no | | | `has_more` | boolean | no | | | `item` | string | no | | | `next_cursor` | string \| null | no | | | `snapshot` | [Snapshot](#schema-snapshot) | no | | ## Schema: Entity Most recent as-filed attributes of a CIK, plus SEC's current entity record. When the snapshot store is unavailable and v3 has no filing for the CIK, nothing can be said about it: the body is then only {cik, data: null, snapshot}. | Field | Type | Required | Description | |---|---|---|---| | `addresses` | [Addresses](#schema-addresses) | no | | | `as_of` | object \| null | no | The filing the as-filed attributes come from; null when v3 has no filing for the CIK. | | `as_of.accession` | string | no | | | `as_of.filing_date` | date (YYYY-MM-DD) | no | | | `as_of.role` | string | no | | | `cik` | string | no | | | `current` | [EntityCurrent](#schema-entitycurrent) | no | | | `data` | null | no | Present (null) only in the {cik, data, snapshot} body described above. | | `filings` | integer | no | Filings in v3 that name the entity. | | `first_filing_date` | date (YYYY-MM-DD) \| null | no | | | `fiscal_year_end` | string \| null | no | | | `former_names` | array of object | no | | | `irs_number` | string \| null | no | | | `last_filing_date` | date (YYYY-MM-DD) \| null | no | | | `links` | object | no | | | `links.filings` | string | no | | | `links.sec_filings` | string | no | | | `links.self` | string | no | | | `name` | string \| null | no | | | `role_counts` | object | no | | | `roles` | array of string | no | | | `sic` | string \| null | no | | | `snapshot` | [Snapshot](#schema-snapshot) | no | | | `spac` | [Spac](#schema-spac) | no | | | `state_of_inc` | string \| null | no | | ## Schema: EntityCurrent SEC's entity record from the submissions snapshot; null when the snapshot has no such CIK or is unavailable (see snapshot.available). | Field | Type | Required | Description | |---|---|---|---| | `addresses` | [Addresses](#schema-addresses) | no | | | `category` | string \| null | no | | | `cik` | string | no | | | `ein` | string \| null | no | | | `entity_type` | string \| null | no | | | `exchanges` | array of string | no | | | `filings` | integer | no | Filings in SEC's list for the entity. | | `first_filing_date` | date (YYYY-MM-DD) \| null | no | | | `fiscal_year_end` | string \| null | no | | | `flags` | string \| null | no | | | `former_names` | array of object | no | | | `last_filing_date` | date (YYYY-MM-DD) \| null | no | | | `lei` | string \| null | no | | | `listed` | array of object | no | The entity's rows in SEC's ticker file: {ticker, exchange}. | | `listed_as_of` | date (YYYY-MM-DD) \| null | no | | | `name` | string | no | | | `phone` | string \| null | no | | | `sic` | string \| null | no | | | `sic_description` | string \| null | no | | | `state_of_inc` | string \| null | no | | | `ticker_exchanges` | array of object | no | | | `tickers` | array of string | no | | ## Schema: EntityList | Field | Type | Required | Description | |---|---|---|---| | `data` | array of [EntityMatch](#schema-entitymatch) | yes | | | `has_more` | boolean | no | | | `next_cursor` | string \| null | no | | | `snapshot` | [Snapshot](#schema-snapshot) | yes | available is true when the snapshot was searched; false when the list is names as filed. | ## Schema: EntityMatch | Field | Type | Required | Description | |---|---|---|---| | `cik` | string | no | | | `filings` | integer | no | Filings in v3 that name the entity. | | `matched` | string | no | What the query matched. Snapshot search results only. One of: `cik`, `ticker`, `name`, `former_name`. | | `name` | string \| null | no | SEC's current name (snapshot search) or the most recent name as filed. | | `sec_filings` | integer | no | Filings in SEC's list for the entity. Snapshot search results only. | | `tickers` | array of string | no | Snapshot search results only. | ## Schema: Event | Field | Type | Required | Description | |---|---|---|---| | `at` | date-time (RFC 3339, UTC) | no | | | `details` | object | no | | | `event` | string | no | | | `seq` | integer | no | | | `source` | string | no | | ## Schema: EventList | Field | Type | Required | Description | |---|---|---|---| | `data` | array of [Event](#schema-event) | yes | | | `has_more` | boolean | no | | | `next_cursor` | string \| null | no | | ## Schema: Excluded The deleted (SEC-withdrawn) filings this current or aggregate answer left out (owner ruling 2026-10-27: the remaining filings make the answer), at most 20, by accession; excluded_total counts them all. Empty when nothing was left out. An object with no fixed fields. ## Schema: Extraction The parse state of the filing for one extractor (contract §1.3). | Field | Type | Required | Description | |---|---|---|---| | `active_version` | string | yes | The version the deployed parser runs. | | `dataset` | string | yes | 13f, 8k_items, sections. | | `extractor` | string | yes | | | `first_parsed_at` | date-time (RFC 3339, UTC) \| null | no | | | `method` | string \| null | no | One of: `header`, `xml`, `xbrl`, `table`, `rule`, `null`. | | `parsed_at` | date-time (RFC 3339, UTC) \| null | no | The last write of the result. | | `reparse` | object \| null | yes | A parse of the deployed version queued, running or given up while a result stands; null otherwise. | | `reparse.attempts` | integer \| null | no | | | `reparse.queued_at` | date-time (RFC 3339, UTC) \| null | no | | | `reparse.state` | string | no | One of: `queued`, `running`, `failed`. | | `reparse.version` | string | no | | | `rows_stale` | boolean | no | A later parse could not read the filing and left the rows of an earlier good parse in place. | | `status` | string | yes | One of: `ok`, `ok_with_warnings`, `partial`, `unparseable`, `not_applicable`, `pending`, `failed`, `not_parsed`. | | `version` | string \| null | yes | The extractor version that last verified the filing; null without a result. | | `warnings` | array of [ParseWarning](#schema-parsewarning) | yes | At most 100, in order. | | `warnings_total` | integer | yes | | | `warnings_truncated` | boolean | yes | | ## Schema: F13fCover Cover page as filed; contact fields limited to city, state or country and ZIP code; the signer without the phone. | Field | Type | Required | Description | |---|---|---|---| | `amendment_no` | integer \| null | no | | | `amendment_type` | string \| null | no | | | `confidence` | number \| null | no | Rule confidence (not a probability). | | `is_amendment` | boolean | no | | | `manager_address` | object \| null | no | | | `manager_address.city` | any | no | | | `manager_address.state_or_country` | any | no | | | `manager_address.zip_code` | any | no | | | `manager_cik` | string | no | | | `manager_name` | string \| null | no | | | `period` | date (YYYY-MM-DD) \| null | no | | | `report_type` | string \| null | no | | | `signature` | object \| null | no | | | `signature.city` | any | no | | | `signature.name` | any | no | | | `signature.signature` | any | no | | | `signature.signature_date` | any | no | | | `signature.state_or_country` | any | no | | | `signature.title` | any | no | | ## Schema: F13fEffectiveHoldingList | Field | Type | Required | Description | |---|---|---|---| | `as_of` | string \| null | no | | | `confidential_omitted` | boolean | no | | | `data` | array of [F13fHolding](#schema-f13fholding) + object | no | | | `effective` | object | no | | | `effective.reported_13f_long_value_usd` | [NullableDecimal](#schema-nullabledecimal) | no | | | `effective.rows` | integer \| null | no | | | `excluded` | [Excluded](#schema-excluded) | no | view=effective only. | | `excluded_total` | integer | no | view=effective only. | | `has_more` | boolean | no | | | `has_notice` | boolean | no | | | `ledger` | array of [LedgerStep](#schema-ledgerstep) | no | | | `limits` | [F13fLimits](#schema-f13flimits) | no | | | `manager_cik` | string | no | | | `next_cursor` | string \| null | no | | | `period` | date (YYYY-MM-DD) | no | | | `rebuild_pending` | boolean | no | A member filing was deleted since the group was built: its rows are not served and the total is null until the rebuild. | | `view` | string | no | One of: `effective`, `as_filed`. | ## Schema: F13fFiling | Field | Type | Required | Description | |---|---|---|---| | `accession` | string | no | | | `cover` | [F13fCover](#schema-f13fcover) | no | | | `extraction` | [Extraction](#schema-extraction) | no | | | `filing` | [FilingRef](#schema-filingref) | no | | | `ledger` | any | no | | | `links` | object | no | | | `other_managers` | object | no | | | `other_managers.included` | array of [F13fOtherManager](#schema-f13fothermanager) | no | | | `other_managers.reporting_for_filer` | array of [F13fOtherManager](#schema-f13fothermanager) | no | | | `snapshot` | [Snapshot](#schema-snapshot) | no | | | `summary` | [F13fSummary](#schema-f13fsummary) | no | | | `value_unit` | [ValueUnit](#schema-valueunit) | no | | ## Schema: F13fHolderList | Field | Type | Required | Description | |---|---|---|---| | `as_of` | string \| null | no | | | `cusip` | string | no | | | `data` | array of [F13fHolding](#schema-f13fholding) + object | no | | | `excluded` | [Excluded](#schema-excluded) | no | | | `excluded_total` | integer | no | | | `has_more` | boolean | no | | | `limits` | [F13fLimits](#schema-f13flimits) | no | | | `next_cursor` | string \| null | no | | | `period` | date (YYYY-MM-DD) | no | | ## Schema: F13fHolding One information-table row as filed; value_usd = value_reported x the unit decision's multiplier (null when the unit is ambiguous, untested with the flag unit_contradicted, or not decided). | Field | Type | Required | Description | |---|---|---|---| | `accession` | string | no | | | `amount_type` | string \| null | no | | | `confidence` | number \| null | no | | | `cusip` | string \| null | no | | | `cusip_raw` | string \| null | no | | | `cusip_status` | string | no | | | `flags` | array of string | no | | | `name_of_issuer` | string \| null | no | | | `observed_in` | string | no | | | `put_call` | string \| null | no | | | `row_id` | string | no | | | `row_no` | integer | no | | | `shares_or_principal` | [NullableDecimal](#schema-nullabledecimal) | no | | | `title_of_class` | string \| null | no | | | `value_raw` | string \| null | no | | | `value_reported` | [NullableDecimal](#schema-nullabledecimal) | no | | | `value_usd` | [NullableDecimal](#schema-nullabledecimal) | no | | ## Schema: F13fHoldingList | Field | Type | Required | Description | |---|---|---|---| | `accession` | string | no | | | `data` | array of [F13fHolding](#schema-f13fholding) | no | | | `extraction` | [Extraction](#schema-extraction) | no | | | `filing` | [FilingRef](#schema-filingref) | no | | | `has_more` | boolean | no | | | `next_cursor` | string \| null | no | | | `snapshot` | [Snapshot](#schema-snapshot) | no | | | `value_unit` | [ValueUnit](#schema-valueunit) | no | | ## Schema: F13fLimits What Form 13F does not report: filed up to 45 days after the quarter end; long positions only; Section 13(f) securities only; managers with over USD 100 million only; positions under confidential treatment can be omitted. Manager totals are reported 13F long values, never assets under management. An object with no fixed fields. ## Schema: F13fManagerPeriod | Field | Type | Required | Description | |---|---|---|---| | `base_accession` | string \| null | no | | | `computed_at` | date-time (RFC 3339, UTC) \| null | no | | | `confidential_omitted` | boolean | no | | | `derive_version` | string | no | | | `flags` | array of string | no | | | `has_notice` | boolean | no | | | `latest` | object | no | | | `latest.accepted_at` | date-time (RFC 3339, UTC) \| null | no | | | `latest.accepted_at_source` | string \| null | no | | | `latest.accession` | string | no | | | `latest.filing_date` | date (YYYY-MM-DD) | no | | | `links` | object | no | | | `manager_cik` | string | no | | | `period` | date (YYYY-MM-DD) | no | | | `rebuild_pending` | boolean | no | A member filing was deleted since the group was built: the total is null until the rebuild. | | `report_type` | string \| null | no | | | `reported_13f_long_value_usd` | [NullableDecimal](#schema-nullabledecimal) | no | | | `rows_effective` | integer | no | | | `steps` | integer | no | | | `unit_flags` | array of string | no | | ## Schema: F13fManagerPeriodList | Field | Type | Required | Description | |---|---|---|---| | `as_of` | string \| null | no | | | `data` | array of [F13fManagerPeriod](#schema-f13fmanagerperiod) | no | | | `excluded` | [Excluded](#schema-excluded) | no | | | `excluded_total` | integer | no | | | `has_more` | boolean | no | | | `limits` | [F13fLimits](#schema-f13flimits) | no | | | `manager_cik` | string | no | | | `next_cursor` | string \| null | no | | ## Schema: F13fOtherManager | Field | Type | Required | Description | |---|---|---|---| | `cik` | string \| null | no | | | `cik_raw` | string \| null | no | | | `form13f_file_number` | string \| null | no | | | `name` | string \| null | no | | | `row_no` | integer | no | | | `sequence_number` | integer \| null | no | | ## Schema: F13fSummary | Field | Type | Required | Description | |---|---|---|---| | `rows_parsed` | integer \| null | no | | | `table_entry_total` | integer \| null | no | | | `table_value_total` | [NullableDecimal](#schema-nullabledecimal) | no | | | `value_sum_reported` | [NullableDecimal](#schema-nullabledecimal) | no | | ## Schema: F144Filing | Field | Type | Required | Description | |---|---|---|---| | `accession` | string | no | | | `chain` | object \| null | no | | | `extraction` | [Extraction](#schema-extraction) | no | | | `filing` | [FilingRef](#schema-filingref) | no | | | `header_entities` | array of object | no | | | `limits` | array of string | no | | | `notice` | [F144Notice](#schema-f144notice) | no | | | `snapshot` | [Snapshot](#schema-snapshot) | no | | ## Schema: F144Notice A Form 144 notice as filed. A notice is not a sale. | Field | Type | Required | Description | |---|---|---|---| | `accession` | string | no | | | `acquisitions` | array of object | no | | | `flags` | array of string | no | | | `form_type` | string | no | | | `issuer` | object | no | | | `nothing_sold_past_3_months` | boolean \| null | no | | | `notice_date` | string \| null | no | | | `plan_adoption_dates` | array of string \| null | no | | | `previous_accession` | string \| null | no | | | `sales_past_3_months` | array of object | no | | | `securities` | array of object | no | | | `seller` | object | no | | ## Schema: FeedbackCreate One feedback message to SEC Blast about the API, the MCP server or the data. Do not include personal data, API keys or other secrets. | Field | Type | Required | Description | |---|---|---|---| | `category` | string | yes | bug: something failed or misbehaved; missing_data: SEC data expected but not there; missing_tool: no route or tool does what was needed; wrong_answer: a value or text is wrong; docs: a description or error message is unclear; other. One of: `bug`, `missing_data`, `missing_tool`, `wrong_answer`, `docs`, `other`. | | `client` | object \| null | no | The client program, e.g. the MCP client's name and version from its initialize request. | | `client.name` | string | yes | | | `client.version` | string \| null | no | | | `context` | object \| null | no | Details such as accession, query and request_id: a JSON object of at most 16 KB as compact JSON. | | `message` | string | yes | What happened and what was expected: 1 to 4,000 characters after trimming, no NUL. | | `source` | string | no | Where the feedback comes from; the MCP server sends mcp. One of: `api`, `mcp`. | | `tool` | string \| null | no | The MCP tool or API route the feedback is about (at most 100 bytes). | ## Schema: FeedbackCreated | Field | Type | Required | Description | |---|---|---|---| | `id` | integer (int64) | yes | The feedback's id. | ## Schema: Filing | Field | Type | Required | Description | |---|---|---|---| | `accepted_at` | date-time (RFC 3339, UTC) \| null | no | The acceptance time stored in v3. A time from the filing's own header (source realtime or archives_txt) always wins over SEC's; once stored a time does not move (a later SEC value goes to accepted_at_snapshot). Otherwise SEC's submissions value: for a filing new since the previous snapshot sync, SEC's value minus the New York UTC offset (SEC's values carry that offset), source submissions_corrected; for history, SEC's value as given, source submissions_unverified (it may carry 0, 1 or 2 such offsets). Null when no source has a time. | | `accepted_at_snapshot` | date-time (RFC 3339, UTC) | no | Present only when SEC's submissions value differs from accepted_at (at whole seconds): SEC's value as given. | | `accepted_at_source` | string \| null | no | realtime / archives_txt: from the filing's header (live ingest / SEC Archives). submissions_corrected, submissions_unverified: from SEC's submissions snapshot (see accepted_at). oldload and submissions are not written any more. One of: `realtime`, `archives_txt`, `submissions_corrected`, `submissions_unverified`, `oldload`, `submissions`, `null`. | | `accession` | string | yes | | | `base_form` | string | yes | | | `deleted_at` | date-time (RFC 3339, UTC) \| null | no | When SEC deleted the filing: the TIMESTAMP of its DELETION notice (the notice's feed day at midnight New York time when it has none). Null unless status is deleted. | | `doc_count` | integer | no | | | `feed_date` | date (YYYY-MM-DD) \| null | no | | | `filing_date` | date (YYYY-MM-DD) | yes | | | `first_seen_at` | date-time (RFC 3339, UTC) \| null | no | When v3 first saw the filing: for a live filing its entry in SEC's list of new filings; otherwise the moment v3 registered it, which for a backfilled filing is the day of the load, years after the filing. v3's time, never SEC's. | | `form_type` | string | yes | Form type as filed. | | `header_in_file` | boolean | no | Single filing only. false: SEC's submission file of the filing has no SGML header (part of the 1994-1995 Archives files hold only their documents); its form type, filing date and filers are SEC's submissions index values, links.header is null and /header answers 404 with reason no_header_in_file. | | `is_amendment` | boolean | yes | | | `is_inline_xbrl` | boolean \| null | no | SEC's isInlineXBRL; null as is_xbrl. | | `is_xbrl` | boolean \| null | no | SEC's isXBRL; null when SEC does not say or the snapshot sync has not seen the filing. | | `items` | array of string | no | | | `items_unmapped` | array of string | no | Item descriptions of the header that have no item code yet. In lists only when there are any; always on the single filing. | | `links` | object | yes | | | `links.documents` | string | no | | | `links.events` | string | no | | | `links.header` | string \| null | no | null when header_in_file is false (single filing). | | `links.self` | string | no | | | `period_of_report` | date (YYYY-MM-DD) \| null | no | SEC's reportDate (submissions snapshot) when it gives one, otherwise the value in the filing's header. | | `period_of_report_header` | date (YYYY-MM-DD) \| null | no | Single filing only, and only when SEC's reportDate replaced a different header period: the header's (null: the header has none). | | `period_of_report_source` | string \| null | no | One of: `submissions`, `header`, `null`. | | `primary_cik` | string | yes | | | `primary_name` | string \| null | no | Name of the primary entity as filed (header_in_file false: the name SEC's submissions index gives for the filing date, or null). | | `provisional` | boolean | no | status == provisional. | | `sec_items` | array of string \| null | no | SEC's 8-K items list (items is the header's); null when the snapshot sync has not seen the filing. | | `sec_primary_doc_description` | string \| null | no | Single filing only: SEC's primaryDocDescription. | | `sec_primary_document` | string \| null | no | SEC's primaryDocument (file name). | | `sec_url` | string (URI) | yes | | | `snapshot_date` | date (YYYY-MM-DD) \| null | no | Single filing only: the snapshot whose values were last written to the filing; null when none was. | | `source` | string | no | realtime: registered by live ingest; it becomes feed when the nightly feed delivers the filing. One of: `feed`, `oldload`, `archives`, `realtime`. | | `status` | string | yes | provisional: registered by live ingest and not yet confirmed by the nightly feed, which makes it final (and may replace its documents). deleted: SEC deleted (withdrew) the filing; it is still served, with its documents when they were delivered (deleted_at, and the deletion block on the single filing). One of: `provisional`, `final`, `deleted`. | | `total_bytes` | integer | no | | ## Schema: FilingDetail | Field | Type | Required | Description | |---|---|---|---| | `accepted_at` | date-time (RFC 3339, UTC) \| null | no | The acceptance time stored in v3. A time from the filing's own header (source realtime or archives_txt) always wins over SEC's; once stored a time does not move (a later SEC value goes to accepted_at_snapshot). Otherwise SEC's submissions value: for a filing new since the previous snapshot sync, SEC's value minus the New York UTC offset (SEC's values carry that offset), source submissions_corrected; for history, SEC's value as given, source submissions_unverified (it may carry 0, 1 or 2 such offsets). Null when no source has a time. | | `accepted_at_snapshot` | date-time (RFC 3339, UTC) | no | Present only when SEC's submissions value differs from accepted_at (at whole seconds): SEC's value as given. | | `accepted_at_source` | string \| null | no | realtime / archives_txt: from the filing's header (live ingest / SEC Archives). submissions_corrected, submissions_unverified: from SEC's submissions snapshot (see accepted_at). oldload and submissions are not written any more. One of: `realtime`, `archives_txt`, `submissions_corrected`, `submissions_unverified`, `oldload`, `submissions`, `null`. | | `accession` | string | yes | | | `base_form` | string | yes | | | `deleted_at` | date-time (RFC 3339, UTC) \| null | no | | | `doc_count` | integer | no | | | `feed_date` | date (YYYY-MM-DD) \| null | no | | | `filing_date` | date (YYYY-MM-DD) | yes | | | `first_seen_at` | date-time (RFC 3339, UTC) \| null | no | | | `form_type` | string | yes | Form type as filed. | | `header_in_file` | boolean | no | Single filing only. false: SEC's submission file of the filing has no SGML header (part of the 1994-1995 Archives files hold only their documents); its form type, filing date and filers are SEC's submissions index values, links.header is null and /header answers 404 with reason no_header_in_file. | | `is_amendment` | boolean | yes | | | `is_inline_xbrl` | boolean \| null | no | SEC's isInlineXBRL; null as is_xbrl. | | `is_xbrl` | boolean \| null | no | SEC's isXBRL; null when SEC does not say or the snapshot sync has not seen the filing. | | `items` | array of string | no | | | `items_unmapped` | array of string | no | | | `links` | object | yes | | | `links.documents` | string | no | | | `links.events` | string | no | | | `links.header` | string \| null | no | null when header_in_file is false (single filing). | | `links.self` | string | no | | | `period_of_report` | date (YYYY-MM-DD) \| null | no | SEC's reportDate (submissions snapshot) when it gives one, otherwise the value in the filing's header. | | `period_of_report_header` | date (YYYY-MM-DD) \| null | no | Single filing only, and only when SEC's reportDate replaced a different header period: the header's (null: the header has none). | | `period_of_report_source` | string \| null | no | One of: `submissions`, `header`, `null`. | | `primary_cik` | string | yes | | | `primary_name` | string \| null | no | Name of the primary entity as filed (header_in_file false: the name SEC's submissions index gives for the filing date, or null). | | `provisional` | boolean | no | status == provisional. | | `sec_items` | array of string \| null | no | SEC's 8-K items list (items is the header's); null when the snapshot sync has not seen the filing. | | `sec_primary_doc_description` | string \| null | no | Single filing only: SEC's primaryDocDescription. | | `sec_primary_document` | string \| null | no | SEC's primaryDocument (file name). | | `sec_url` | string (URI) | yes | | | `snapshot_date` | date (YYYY-MM-DD) \| null | no | Single filing only: the snapshot whose values were last written to the filing; null when none was. | | `source` | string | no | realtime: registered by live ingest; it becomes feed when the nightly feed delivers the filing. One of: `feed`, `oldload`, `archives`, `realtime`. | | `status` | string | yes | provisional: registered by live ingest and not yet confirmed by the nightly feed, which makes it final (and may replace its documents). deleted: SEC deleted (withdrew) the filing; it is still served, with its documents when they were delivered (deleted_at, and the deletion block on the single filing). One of: `provisional`, `final`, `deleted`. | | `total_bytes` | integer | no | | | `date_of_change` | date (YYYY-MM-DD) \| null | no | | | `deleted` | boolean | no | status == deleted. | | `deletion` | object \| null | no | Only for a deleted filing (null otherwise): where the deletion came from. SEC's DELETION notice gives no reason. | | `deletion.feed_date` | date (YYYY-MM-DD) \| null | no | The feed day whose archive held the notice. | | `deletion.notice` | string \| null | no | The notice member, \#\. | | `deletion.recorded_at` | date-time (RFC 3339, UTC) \| null | no | When v3 registered the deletion. | | `deletion.source` | string \| null | no | Where the deletion notice came from, as the filing's events say it: feed (SEC's nightly feed, which carries the notices) for every deletion today. | | `documents` | array of [Document](#schema-document) | no | | | `effectiveness_date` | date (YYYY-MM-DD) \| null | no | | | `entities` | array of [FilingEntity](#schema-filingentity) | no | | | `events` | array of [Event](#schema-event) | no | | | `finalized_at` | date-time (RFC 3339, UTC) \| null | no | | | `is_correction` | boolean | no | | | `is_paper` | boolean | no | | | `is_private_release` | boolean | no | | | `live` | object | no | Only while the filing is provisional and its source is realtime: where live ingest is with it. Gone once the filing is final. | | `live.documents_at` | date-time (RFC 3339, UTC) \| null | no | When its documents were registered; null until then. | | `live.listed_at` | date-time (RFC 3339, UTC) \| null | no | When the filing was listed. | | `live.state` | string | no | listed: the header is registered (entities, items, acceptance time, /header); doc_count is 0 and the documents are still being fetched. complete: the documents are registered. documents_failed: they could not be fetched; the nightly feed will supply them. One of: `listed`, `complete`, `documents_failed`. | | `previous_accession` | string \| null | no | | | `released_at` | date-time (RFC 3339, UTC) \| null | no | | | `snapshot` | [Snapshot](#schema-snapshot) | no | | | `versions` | [Versions](#schema-versions) | no | | ## Schema: FilingEntity | Field | Type | Required | Description | |---|---|---|---| | `addresses` | [Addresses](#schema-addresses) | no | | | `cik` | string | no | | | `file_number` | string \| null | no | | | `film_number` | string \| null | no | | | `fiscal_year_end` | string \| null | no | | | `name` | string \| null | no | | | `role` | string | no | One of: `filer`, `subject`, `filed_by`, `filed_for`, `reporting_owner`, `issuer`, `depositor`, `securitizer`, `issuing_entity`, `underwriter`, `serial_company`. | | `sic` | string \| null | no | | | `state_of_inc` | string \| null | no | | ## Schema: FilingList | Field | Type | Required | Description | |---|---|---|---| | `data` | array of [Filing](#schema-filing) | yes | | | `has_more` | boolean | yes | True when another page follows (pages are complete for every sort). | | `next_cursor` | string \| null | yes | | | `snapshot` | [Snapshot](#schema-snapshot) | yes | | ## Schema: FilingRef The filing a parsed result belongs to: a strict subset of Filing (same names, types and values). | Field | Type | Required | Description | |---|---|---|---| | `accepted_at` | date-time (RFC 3339, UTC) \| null | no | The acceptance time stored in v3. A time from the filing's own header (source realtime or archives_txt) always wins over SEC's; once stored a time does not move (a later SEC value goes to accepted_at_snapshot). Otherwise SEC's submissions value: for a filing new since the previous snapshot sync, SEC's value minus the New York UTC offset (SEC's values carry that offset), source submissions_corrected; for history, SEC's value as given, source submissions_unverified (it may carry 0, 1 or 2 such offsets). Null when no source has a time. | | `accepted_at_source` | string \| null | no | realtime / archives_txt: from the filing's header (live ingest / SEC Archives). submissions_corrected, submissions_unverified: from SEC's submissions snapshot (see accepted_at). oldload and submissions are not written any more. One of: `realtime`, `archives_txt`, `submissions_corrected`, `submissions_unverified`, `oldload`, `submissions`, `null`. | | `accession` | string | no | | | `base_form` | string | no | | | `deleted` | boolean | no | status == deleted. | | `deleted_at` | date-time (RFC 3339, UTC) \| null | no | When SEC deleted the filing: the TIMESTAMP of its DELETION notice (the notice's feed day at midnight New York time when it has none). Null unless status is deleted. | | `deletion` | object \| null | no | Per-filing routes only (absent in lists): Only for a deleted filing (null otherwise): where the deletion came from. SEC's DELETION notice gives no reason. | | `deletion.feed_date` | date (YYYY-MM-DD) \| null | no | The feed day whose archive held the notice. | | `deletion.notice` | string \| null | no | The notice member, \#\. | | `deletion.recorded_at` | date-time (RFC 3339, UTC) \| null | no | When v3 registered the deletion. | | `deletion.source` | string \| null | no | Where the deletion notice came from, as the filing's events say it: feed (SEC's nightly feed, which carries the notices) for every deletion today. | | `filing_date` | date (YYYY-MM-DD) | no | | | `form_type` | string | no | Form type as filed. | | `links` | object | no | | | `links.self` | string | no | | | `period_of_report` | date (YYYY-MM-DD) \| null | no | SEC's reportDate (submissions snapshot) when it gives one, otherwise the value in the filing's header. | | `period_of_report_source` | string \| null | no | One of: `submissions`, `header`, `null`. | | `primary_cik` | string | no | | | `primary_name` | string \| null | no | Name of the primary entity as filed (header_in_file false: the name SEC's submissions index gives for the filing date, or null). | | `provisional` | boolean | no | status == provisional. | | `status` | string | no | provisional: registered by live ingest and not yet confirmed by the nightly feed, which makes it final (and may replace its documents). deleted: SEC deleted (withdrew) the filing; it is still served, with its documents when they were delivered (deleted_at, and the deletion block on the single filing). One of: `provisional`, `final`, `deleted`. | ## Schema: FormCount | Field | Type | Required | Description | |---|---|---|---| | `base_form` | string | no | | | `count` | integer | no | | | `form_type` | string | no | | | `is_amendment` | boolean | no | | ## Schema: FormDFiling | Field | Type | Required | Description | |---|---|---|---| | `accession` | string | yes | | | `chain` | object \| null | yes | The offering chain: chain_id, members \[{accession, chain_seq, link_method root \| previous_accession \| issuer_file_number, form_type, filing_date, accepted_at, flags, filing_status}\], effective_accession (the latest member: its rows are the offering), steps, flags, derive_version, computed_at. | | `extraction` | object | yes | | | `filing` | object | yes | | | `header_entities` | array of object | yes | | | `issuers` | array of object | yes | | | `offering` | any | yes | | | `recipients` | array of object | yes | | | `related_persons` | array of object | yes | | | `snapshot` | object | yes | | ## Schema: FormDOffering One Form D notice as filed (v3_formd_offerings): form_type (D \| D/A, from the filing), submission_type_xml, schema_version, is_amendment (from the form type; is_amendment_xml as filed), previous_accession, industry_group_type, investment_fund_type, is_40_act, revenue_range and nav_range (filed text, e.g. Decline to Disclose), federal_exemptions, date_of_first_sale (+_raw), first_sale_yet_to_occur, more_than_one_year, types_of_securities (as filed), minimum_investment, the three amounts total_offering_amount, total_amount_sold, total_remaining (whole dollars or null, each with _raw and _indefinite: Indefinite is a filed value, never a number), investors, commissions, finders' fees, proceeds to related persons (each with _raw and estimate flags), signature_block, n_issuers, n_related_persons, n_recipients, flags (amount_indefinite, amounts_do_not_add, remaining_inconsistent, amendment_flag_mismatch, previous_accession_missing, first_sale_yet_to_occur, size_declined). An object with no fixed fields. ## Schema: FormDOfferings | Field | Type | Required | Description | |---|---|---|---| | `as_of` | string \| null | yes | | | `cik` | string \| null | yes | | | `data` | array of object | yes | | | `excluded` | [Excluded](#schema-excluded) | no | | | `excluded_total` | integer | no | | | `has_more` | boolean | yes | | | `next_cursor` | string \| null | yes | | | `view` | string | yes | One of: `as_filed`, `effective`. | ## Schema: FormList | Field | Type | Required | Description | |---|---|---|---| | `computed_at` | date-time (RFC 3339, UTC) | no | When the list was computed, UTC. It is served until a later computation replaces it. | | `data` | array of [FormCount](#schema-formcount) | yes | | | `has_more` | boolean | no | | | `next_cursor` | string \| null | no | | ## Schema: Health | Field | Type | Required | Description | |---|---|---|---| | `checks` | object | yes | | | `checks.callbacks` | string | no | Webhook delivery, judged per organization: the lateness of the least late organization among those with a first attempt due or one made in the last minute (one organization's own backlog does not count while others are served on time). ok: at most 60 s past due. degraded: up to 5 minutes. down: more, or the delivery table cannot be read (also while the database is down). degraded and down make the status degraded at any hour, never an outage. disabled: this deployment has no webhook delivery. One of: `ok`, `degraded`, `down`, `disabled`. | | `checks.db` | string | no | One of: `ok`, `fail`. | | `checks.docs_root` | string | no | One of: `ok`, `missing`. | | `checks.live` | string | no | Live ingest (the daemon that registers filings seconds after SEC accepts them). ok: its heartbeat is at most 45 s old and it is polling, idle outside the window, or catching up. paused: SEC refused a request; nothing is sent until live.paused_until, and the 30 careful minutes after. degraded: SEC unreachable, database down, disk low, or halted after repeated pauses. down: no heartbeat (not running, stopping, or its status could not be read). disabled: this deployment has no live ingest. One of: `ok`, `paused`, `degraded`, `down`, `disabled`. | | `checks.mcp` | string | no | The MCP server sb_mcp_v3 (its /healthz, probed at most every 5 s). disabled: this deployment does not name one. Informational: it never changes status. One of: `ok`, `down`, `disabled`. | | `checks.store` | string | no | The snapshot store. stale: its snapshot is more than 3 days old (still used). loading: no snapshot served yet. disabled: not configured. One of: `ok`, `stale`, `loading`, `unavailable`, `disabled`. | | `checks.stream` | string | no | The filing stream (the sequencer that writes the log behind /v3/stream). ok: it wrote its cursor at most 30 s ago. stale: the cursor is older, or there is none; the status is then degraded, never an outage. stale also when the database cannot be read. disabled: this deployment has no stream. One of: `ok`, `stale`, `disabled`. | | `live` | object | no | Present only when live ingest is enabled. Counts and the full heartbeat are on /v3/coverage, which needs a key. | | `live.lag_seconds` | integer \| null | no | Median seconds from SEC's acceptance to the filing being seen, over the last 15 minutes; null with fewer than 5 filings, and when the figure is negative or absurd. | | `live.last_new_filing_at` | date-time (RFC 3339, UTC) \| null | no | When the newest filing was first seen. | | `live.last_poll_at` | date-time (RFC 3339, UTC) \| null | no | The last successful poll of SEC's list of new filings. | | `live.paused_until` | date-time (RFC 3339, UTC) \| null | no | End of a pause in force; null otherwise. | | `live.state` | string \| null | no | The daemon's own state in its last heartbeat (ok, idle, catching_up, paused, cautious, sec_unreachable, db_down, disk_low, halted, stopping, stopped, failed), or dry_run when the daemon that answers is a dry run (it registers no filings; checks.live is then never ok); null without a heartbeat or when it is none of these. It is the daemon's last word, so a daemon that died still shows its last state: checks.live is the judgement, which also knows how old the heartbeat is and whether the session ended. | | `metering` | object | no | Only when the API runs with a metering switches file (one in force, or one that was refused): the mode of each feature; config (ok \| refused: the file cannot be read or is invalid, and the previous switches, or all off, stay), config_error and config_last_good (when a valid file was last taken); the usage flusher (last success, pending records, failures, events written and dropped, whether the month was read back); the age of the cached entitlements; entitlements_statement (unchecked \| ok \| insufficient_privilege \| failed: whether this role can run the entitlements statement, which reads v3_acct_entitlements and v3_usage_rollup_state; updated by every entitlements read, and checked actively while a feature is enforced) and entitlements_error; limits_unknown (requests served without limits because their org's limits could not be read); and the refusal counters. It makes status degraded, never an outage, while the file is refused, or while a feature is enforced and entitlements_statement is insufficient_privilege. | | `status` | string | yes | degraded unless every check is ok and the metering block (when present) is not degraded (a store that is not configured does not degrade; live ingest counts only when it is enabled, and only on a weekday between 06:00 and 22:00 New York time, when SEC accepts filings; the filing stream and webhook delivery count only when enabled, at any hour). The HTTP status is 503 only when the database is down. One of: `ok`, `degraded`. | | `store` | object | no | The snapshot in use. Counts and load details are on /v3/coverage, which needs a key. | | `store.available` | boolean | no | | | `store.snapshot_date` | date (YYYY-MM-DD) \| null | no | | | `store.stale` | boolean \| null | no | | | `time` | date-time (RFC 3339, UTC) | no | | | `version` | string | no | | ## Schema: InsiderFootnoteRef | Field | Type | Required | Description | |---|---|---|---| | `field` | string \| null | no | The column the footnote is on; null when it is on a group of fields (transaction coding). | | `footnote_id` | string \| null | no | | | `ref_seq` | integer | no | | | `target_path` | string \| null | no | | | `text` | string \| null | no | | ## Schema: InsiderRow One row of Table I or II of a Form 3/4/5 as filed. Every amount is a Decimal beside its filed text (_raw). A price given only in a footnote is null with the flag price_in_footnote, never 0. | Field | Type | Required | Description | |---|---|---|---| | `accession` | string | no | | | `acquired_disposed` | string \| null | no | | | `confidence` | number \| null | no | | | `conversion_or_exercise_price` | [NullableDecimal](#schema-nullabledecimal) | no | | | `deemed_execution_date` | string \| null | no | | | `equity_swap` | boolean \| null | no | | | `exercise_date` | string \| null | no | | | `expiration_date` | string \| null | no | | | `extracted_at` | string | no | | | `extractor_version` | string | no | | | `flags` | array of string | no | | | `footnotes` | array of [InsiderFootnoteRef](#schema-insiderfootnoteref) | no | | | `ownership_form` | string \| null | no | | | `ownership_nature` | string \| null | no | | | `price` | [NullableDecimal](#schema-nullabledecimal) | no | | | `price_raw` | string \| null | no | | | `row_id` | string | no | | | `row_no` | integer | no | | | `security_title` | string \| null | no | | | `shares` | [NullableDecimal](#schema-nullabledecimal) | no | | | `shares_after` | [NullableDecimal](#schema-nullabledecimal) | no | | | `shares_raw` | string \| null | no | | | `table` | string | no | One of: `non_derivative_transaction`, `non_derivative_holding`, `derivative_transaction`, `derivative_holding`. | | `table_code` | string | no | One of: `NT`, `NH`, `DT`, `DH`. | | `timeliness` | string \| null | no | | | `total_value` | [NullableDecimal](#schema-nullabledecimal) | no | | | `transaction_code` | string \| null | no | | | `transaction_date` | string \| null | no | | | `transaction_date_raw` | string \| null | no | | | `transaction_form_type` | string \| null | no | | | `underlying_shares` | [NullableDecimal](#schema-nullabledecimal) | no | | | `underlying_title` | string \| null | no | | | `underlying_value` | [NullableDecimal](#schema-nullabledecimal) | no | | | `value_after` | [NullableDecimal](#schema-nullabledecimal) | no | | ## Schema: InsiderRowList | Field | Type | Required | Description | |---|---|---|---| | `as_of` | string \| null | no | | | `data` | array of [InsiderRow](#schema-insiderrow) + object | no | | | `excluded` | [Excluded](#schema-excluded) | no | view=effective only. | | `excluded_total` | integer | no | view=effective only. | | `has_more` | boolean | no | | | `next_cursor` | string \| null | no | | | `provisional` | boolean | no | True for view=effective: the row-level amendment view is provisional. | | `view` | string | no | One of: `as_filed`, `effective`. | ## Schema: LedgerStep | Field | Type | Required | Description | |---|---|---|---| | `accepted_at` | date-time (RFC 3339, UTC) \| null | no | | | `accepted_at_source` | string \| null | no | | | `accession` | string | no | | | `applied_action` | string | no | One of: `base`, `replace`, `add`, `notice`, `ignored_duplicate`, `no_table`. | | `applied_rule` | string | no | | | `computed_at` | date-time (RFC 3339, UTC) \| null | no | | | `declared_type` | string \| null | no | | | `derive_version` | string | no | | | `filing_date` | date (YYYY-MM-DD) | no | | | `flags` | array of string | no | | | `manager_cik` | string | no | | | `period` | date (YYYY-MM-DD) | no | | | `rows_after` | integer \| null | no | | | `rows_before` | integer \| null | no | | | `step` | integer | no | | | `value_usd_after` | [NullableDecimal](#schema-nullabledecimal) | no | | | `value_usd_before` | [NullableDecimal](#schema-nullabledecimal) | no | | ## Schema: NportFiling | Field | Type | Required | Description | |---|---|---|---| | `accession` | string | yes | | | `extraction` | object | yes | | | `filing` | object | yes | | | `has_more` | boolean | yes | | | `holdings` | array of [NportHolding](#schema-nportholding) | yes | | | `ledger` | object \| null | yes | series_id, report_date, step, applied_action base \| replace \| ignored_duplicate, applied_rule, flags, effective_accession, steps, is_effective. | | `limits` | array of string | yes | | | `next_cursor` | string \| null | yes | | | `report` | any | yes | | ## Schema: NportFundHoldings | Field | Type | Required | Description | |---|---|---|---| | `data` | array of object | yes | | | `has_more` | boolean | yes | | | `id_type` | string | yes | | | `id_value` | string | yes | | | `limits` | array of string | yes | | | `next_cursor` | string \| null | yes | | | `view` | string | yes | One of: `effective`, `as_filed`. | ## Schema: NportHolding One investment (v3_nport_holdings): row_no, name, lei, title, cusip_raw (as filed), cusip (null unless nine characters; a placeholder is never a CUSIP), cusip_status, identifiers \[{type isin \| ticker \| other, value, other_desc}\], balance, units, currency, exchange_rate, value_usd, pct_of_nav (Decimals with _raw), payoff_profile, asset_category, issuer_category (from the conditional element when the code is other, with its _desc), country, is_restricted, fair_value_level, debt_sec, repo_agreement, derivative_info, security_lending (as filed), flags. An object with no fixed fields. ## Schema: NportReport One N-PORT filing as filed (v3_nport_filings): form_type, amended_accession, registrant {name, file_number, cik, lei, address, phone}, series_id, series_name, series_lei, class_ids, report_date, fiscal_year_end, is_final_filing, total_assets, total_liabilities, net_assets (Decimal strings, each with _raw), monthly \[{month 1..3, sales, reinvestment, redemption, other_net_realized_gain, other_net_unrealized_appreciation}\], returns \[{class_id, rtn1, rtn2, rtn3 (+_raw)}\], rows_parsed, flags. An object with no fixed fields. ## Schema: NportSeriesReports | Field | Type | Required | Description | |---|---|---|---| | `data` | array of [NportReport](#schema-nportreport) | yes | | | `has_more` | boolean | yes | | | `next_cursor` | string \| null | yes | | | `series_id` | string | yes | | | `view` | string | yes | One of: `effective`, `as_filed`. | ## Schema: NullableDecimal An object with no fixed fields. ## Schema: OpenApi This document. An object with no fixed fields. ## Schema: OwnershipFiling | Field | Type | Required | Description | |---|---|---|---| | `accession` | string | no | | | `amendment_chain` | object \| null | no | Provisional: the original with the amendments that name it, the steps, how each amendment was linked and its row links. | | `document` | object \| null | no | | | `extraction` | [Extraction](#schema-extraction) | no | | | `filing` | [FilingRef](#schema-filingref) | no | | | `footnotes` | array of object | no | | | `header_entities` | array of object | no | The SEC header's entities with every field, addresses and phone numbers included. | | `issuer` | object \| null | no | | | `links` | object | no | | | `other_footnote_references` | array of object | no | | | `owners` | array of object | no | Every reporting owner, document order, with the whole address and relationship. | | `signatures` | array of object | no | | | `snapshot` | [Snapshot](#schema-snapshot) | no | | | `tables` | object | no | | | `tables.derivative_holdings` | array of [InsiderRow](#schema-insiderrow) | no | | | `tables.derivative_transactions` | array of [InsiderRow](#schema-insiderrow) | no | | | `tables.non_derivative_holdings` | array of [InsiderRow](#schema-insiderrow) | no | | | `tables.non_derivative_transactions` | array of [InsiderRow](#schema-insiderrow) | no | | ## Schema: ParseWarning | Field | Type | Required | Description | |---|---|---|---| | `code` | string | no | | | `detail` | string \| null | no | Text the extractor wrote. | | `path` | string \| null | no | | | `row_kind` | string \| null | no | | | `row_no` | integer \| null | no | | | `severity` | string | no | One of: `info`, `warning`, `error`. | | `table` | string \| null | no | | ## Schema: ParsedChange | Field | Type | Required | Description | |---|---|---|---| | `at` | date-time (RFC 3339, UTC) | yes | When the old version was replaced (unit_decision: when it was decided). | | `extractor` | string \| null | no | superseded only. | | `from_version` | string \| null | no | | | `group_key` | string \| null | no | replaced: the group (e.g. \\|\, \\|\). | | `id` | integer | yes | The row's id in its source (v3_parse_superseded, v3_derived_history, v3_13f_unit_decisions). | | `kind` | string | yes | One of: `superseded`, `replaced`, `unit_decision`. | | `old` | any | yes | superseded: the old row (object); replaced: the old rows (array); unit_decision: the decision. Numbers are strings holding the stored value. | | `reason` | string | yes | superseded: changed, removed, withdrawn; replaced: rebuilt, recomputed, reparsed, withdrawn; unit_decision: decided, redecided, revised, withdrawn. | | `row_key` | object \| null | no | superseded: the row's key columns, type-tagged as in the parse envelope ({"row_no":{"int":"3"}}). | | `table` | string | yes | | | `to_version` | string \| null | no | unit_decision: the derive version that decided. | ## Schema: ParsedChanges | Field | Type | Required | Description | |---|---|---|---| | `accession` | string | yes | | | `data` | array of [ParsedChange](#schema-parsedchange) | yes | | | `filing` | [FilingRef](#schema-filingref) | yes | | | `has_more` | boolean | yes | | | `next_cursor` | string \| null | yes | | ## Schema: ParsedItem | Field | Type | Required | Description | |---|---|---|---| | `active_version` | string | yes | The version the deployed parser runs. | | `dataset` | string | yes | 13f, 8k_items, sections. | | `extractor` | string | yes | | | `first_parsed_at` | date-time (RFC 3339, UTC) \| null | no | | | `method` | string \| null | no | One of: `header`, `xml`, `xbrl`, `table`, `rule`, `null`. | | `parsed_at` | date-time (RFC 3339, UTC) \| null | no | The last write of the result. | | `reparse` | object \| null | yes | A parse of the deployed version queued, running or given up while a result stands; null otherwise. | | `reparse.attempts` | integer \| null | no | | | `reparse.queued_at` | date-time (RFC 3339, UTC) \| null | no | | | `reparse.state` | string | no | One of: `queued`, `running`, `failed`. | | `reparse.version` | string | no | | | `rows_stale` | boolean | no | A later parse could not read the filing and left the rows of an earlier good parse in place. | | `status` | string | yes | One of: `ok`, `ok_with_warnings`, `partial`, `unparseable`, `not_applicable`, `pending`, `failed`, `not_parsed`. | | `version` | string \| null | yes | The extractor version that last verified the filing; null without a result. | | `warnings` | array of [ParseWarning](#schema-parsewarning) | yes | At most 100, in order. | | `warnings_total` | integer | yes | | | `warnings_truncated` | boolean | yes | | | `derived` | array of object | yes | The dataset's derive steps for this filing (13F: units, ledger); version and computed_at null until the step has run for it. | | `derived[].computed_at` | date-time (RFC 3339, UTC) \| null | no | | | `derived[].step` | string | no | | | `derived[].version` | string \| null | no | | | `inputs` | array of object | yes | The documents the last parse read. | | `inputs[].filename` | string \| null | no | | | `inputs[].seq` | integer \| null | no | | | `inputs[].sha256` | string \| null | no | | | `inputs[].type` | string \| null | no | | | `links` | object | yes | | | `links.data` | string \| null | no | The dataset's route for this filing; null while this server does not answer it. | | `rows_total` | integer | yes | | ## Schema: ParsedList | Field | Type | Required | Description | |---|---|---|---| | `accession` | string | yes | | | `data` | array of [ParsedItem](#schema-parseditem) | yes | One per extractor that covers the filing's form type; empty when none does. | | `filing` | [FilingRef](#schema-filingref) | yes | | | `has_more` | boolean | yes | | | `next_cursor` | string \| null | yes | | | `snapshot` | [Snapshot](#schema-snapshot) | yes | | ## Schema: Problem RFC 9457 problem details. | Field | Type | Required | Description | |---|---|---|---| | `code` | string | yes | One of: `invalid_parameter`, `unknown_parameter`, `unauthorized`, `invalid_token`, `forbidden`, `not_found`, `gone`, `method_not_allowed`, `rate_limited`, `timeout`, `internal`, `db_unavailable`, `range_not_satisfiable`, `request_too_large`, `warming_up`, `invalid_query`, `query_too_complex`, `prefix_too_broad`, `negative_only_query`, `unsupported_operator`, `invalid_cursor`, `search_timeout`, `search_busy`, `search_unavailable`, `ticker_resolution_unavailable`, `no_text`, `not_covered`, `conversion_timeout`, `document_too_large`, `unsupported_media_type`, `invalid_body`, `callbacks_unavailable`, `plan_required`, `limit_reached`, `conflict`, `quota_exceeded`, `blocked`, `invalid_state`, `replay_running`, `test_running`, `endpoint_unverified`, `endpoint_disabled`. | | `detail` | string | yes | | | `length` | integer | no | Search query errors: length in characters of the offending part of q. | | `parameter` | string | no | The offending parameter, for 400 responses. | | `position` | integer | no | Search query errors: character offset in q. | | `request_id` | string | yes | | | `status` | integer | yes | | | `title` | string | yes | | | `type` | string (URI) | yes | | ## Schema: ProposedSaleList | Field | Type | Required | Description | |---|---|---|---| | `as_of` | string \| null | no | | | `data` | array of [F144Notice](#schema-f144notice) + object | no | | | `excluded` | [Excluded](#schema-excluded) | no | view=effective only. | | `excluded_total` | integer | no | view=effective only. | | `has_more` | boolean | no | | | `limits` | array of string | no | | | `next_cursor` | string \| null | no | | | `provisional` | boolean | no | | | `view` | string | no | One of: `as_filed`, `effective`. | ## Schema: Report | Field | Type | Required | Description | |---|---|---|---| | `amended` | boolean | no | True when any live member is an amendment. | | `base_form` | string | no | Base form of the chain's head. | | `cik` | string | no | | | `first_filing_date` | date (YYYY-MM-DD) \| null | no | Filing date of the chain's head (the original, or the first ingested amendment when the original is absent). | | `head_is_amendment` | boolean | no | The chain's first listed filing is an amendment: its original is not ingested, or it is unlinked, unresolved or ambiguous. | | `latest` | object | no | | | `latest.accepted_at` | date-time (RFC 3339, UTC) \| null | no | As a filing's accepted_at. | | `latest.accepted_at_snapshot` | date-time (RFC 3339, UTC) | no | As on a filing: only when SEC's value differs from accepted_at. | | `latest.accepted_at_source` | string \| null | no | | | `latest.accession` | string | no | | | `latest.filing_date` | date (YYYY-MM-DD) \| null | no | | | `latest.form_type` | string \| null | no | | | `link_status` | string \| null | no | Link status of the head when it is an amendment. | | `links` | object | no | | | `links.latest` | string | no | | | `links.versions` | string | no | | | `original_ingested` | boolean | no | True only when the head is an ingested original (not an amendment). | | `period_of_report` | date (YYYY-MM-DD) \| null | no | Period of the chain's head: SEC's reportDate when it gives one, otherwise its header's. The period filter compares this value. | | `period_of_report_source` | string \| null | no | One of: `submissions`, `header`, `null`. | | `report_key` | string | no | | | `versions` | integer | no | Live (not deleted) ingested members; /versions count also includes deleted and not-ingested items. | ## Schema: ReportList | Field | Type | Required | Description | |---|---|---|---| | `data` | array of [Report](#schema-report) | yes | | | `has_more` | boolean | yes | | | `next_cursor` | string \| null | yes | | | `snapshot` | [Snapshot](#schema-snapshot) | yes | | ## Schema: ResolveMatch | Field | Type | Required | Description | |---|---|---|---| | `cik` | string | no | | | `exchange` | string \| null | no | | | `links` | object | no | | | `links.entity` | string | no | | | `links.filings` | string | no | | | `name` | string \| null | no | | | `ticker` | string | no | | ## Schema: ResolveResult | Field | Type | Required | Description | |---|---|---|---| | `as_of` | date (YYYY-MM-DD) \| null | no | | | `coverage_from` | date (YYYY-MM-DD) \| null | no | The oldest copy kept; earlier dates cannot be resolved. | | `data` | array of [ResolveMatch](#schema-resolvematch) | yes | | | `file_date` | date (YYYY-MM-DD) \| null | no | The daily copy of SEC's ticker file that answered. | | `has_more` | boolean | no | | | `next_cursor` | string \| null | no | | | `snapshot` | [Snapshot](#schema-snapshot) | yes | available is false when the store could not be asked, or had neither a ticker file nor a snapshot to consult: empty data then means unknown, not that no entity holds the ticker. | | `source` | string \| null | no | One of: `sec_company_tickers`, `submissions`, `null`. | | `ticker` | string | yes | | ## Schema: SearchDocument A matching document (members as trimmed by fields). | Field | Type | Required | Description | |---|---|---|---| | `description` | string \| null | no | | | `doc_class` | string \| null | no | | | `doc_id` | string | no | | | `doc_type` | string \| null | no | | | `filename` | string \| null | no | | | `is_primary` | boolean \| null | no | | | `score` | number | no | | | `seq` | integer | no | | | `snippets` | array of [SearchSnippet](#schema-searchsnippet) | no | | | `url` | string | no | /v3/filings/{accession}/documents/{seq} | ## Schema: SearchFacetBucket | Field | Type | Required | Description | |---|---|---|---| | `count` | integer | no | | | `value` | any | no | An integer for the year facet, a string for form, sic and state. | ## Schema: SearchFacets Only the facets named in facets=. Counts are in the result unit (documents for group=document, filings for group=filing); a hit counts once under each of its values. At most facet_size buckets each, largest first. | Field | Type | Required | Description | |---|---|---|---| | `form` | array of [SearchFacetBucket](#schema-searchfacetbucket) | no | | | `sic` | array of [SearchFacetBucket](#schema-searchfacetbucket) | no | | | `state` | array of [SearchFacetBucket](#schema-searchfacetbucket) | no | | | `year` | array of [SearchFacetBucket](#schema-searchfacetbucket) | no | Filing year; value is an integer. | ## Schema: SearchHit group=document: one document with its filing members; group=filing: one filing with documents_matched, documents and collapsed. Members as trimmed by fields. | Field | Type | Required | Description | |---|---|---|---| | `accepted_at` | date-time (RFC 3339, UTC) \| null | no | | | `accepted_at_source` | string \| null | no | | | `accession` | string | no | | | `collapsed` | object \| null | no | Only with collapse=true: null, or {cluster_id, matched} for the best member of a template cluster standing for matched results. | | `description` | string \| null | no | | | `doc_class` | string \| null | no | | | `doc_id` | string | no | | | `doc_type` | string \| null | no | | | `documents` | array of [SearchDocument](#schema-searchdocument) | no | | | `documents_matched` | integer | no | | | `entities` | array of object | no | | | `filename` | string \| null | no | | | `filing_date` | date (YYYY-MM-DD) \| null | no | | | `form_type` | string \| null | no | | | `is_primary` | boolean \| null | no | | | `provisional` | boolean | no | | | `score` | number | no | | | `seq` | integer | no | | | `snippets` | array of [SearchSnippet](#schema-searchsnippet) | no | | | `status` | string | no | The filing's status as indexed: filings SEC deleted are searchable; status= narrows. One of: `provisional`, `final`, `deleted`. | | `url` | string | no | | ## Schema: SearchIndexInfo The index that answered. | Field | Type | Required | Description | |---|---|---|---| | `extractor` | string \| null | no | Text extractor of the newest searched year; snippet offsets count characters of that extractor's text. | | `index_version` | string \| null | no | Build id of the newest searched year. | | `indexed_through` | date-time (RFC 3339, UTC) \| null | no | Acceptance-time horizon of the live indexer. | | `ranking_version` | integer | no | | | `years_missing` | array of integer | no | Years that cannot be searched now. | ## Schema: SearchParse How a query is read; nothing is executed. | Field | Type | Required | Description | |---|---|---|---| | `ast` | object \| null | no | The query tree under the requested syntax: sexpr and tree. | | `differs` | boolean | no | The two readings differ. | | `edgar` | object | no | The EDGAR reading: ast, echo (the query EDGAR would build) and error when it does not parse. | | `filters` | object | no | The structured filters after alias mapping and ticker resolution. | | `match` | string | no | One of: `exact`, `stem`. | | `normalized` | string | no | The normalised query. | | `prefixes` | array of object | no | | | `prefixes[].capped` | boolean | no | | | `prefixes[].expansions` | integer | no | | | `prefixes[].in_span` | boolean | no | Inside NEAR or a phrase (capped at 1,024 expansions). | | `prefixes[].prefix` | string | no | | | `prefixes[].top` | array of array of any | no | Up to 20 \[term, document frequency\] pairs. | | `resolved` | object | no | {tickers: {TICKER: \[cik, ...\]}}. | | `shards` | array of integer | no | The index years the query would search. | | `syntax` | string | no | One of: `sb`, `edgar`. | | `warnings` | array of [SearchWarning](#schema-searchwarning) | no | | ## Schema: SearchResults | Field | Type | Required | Description | |---|---|---|---| | `data` | array of [SearchHit](#schema-searchhit) | yes | | | `facets` | [SearchFacets](#schema-searchfacets) | no | | | `has_more` | boolean | yes | | | `index` | [SearchIndexInfo](#schema-searchindexinfo) | yes | | | `next_cursor` | string \| null | yes | Pass back as cursor with the same query, filters, sort and group. Null when nothing follows, and always null with from \> 0. | | `resolved` | object | yes | {tickers: {TICKER: \[cik, ...\]}}: how tickers were resolved. | | `resolved.tickers` | object | no | | | `took_ms` | integer | yes | | | `total` | [SearchTotals](#schema-searchtotals) | yes | | | `warnings` | array of [SearchWarning](#schema-searchwarning) | yes | | ## Schema: SearchSnippet | Field | Type | Required | Description | |---|---|---|---| | `end` | integer | no | Code-point offset of the end of the snippet (exclusive), as start. | | `highlights` | array of array of integer | no | \[start, end) character offsets in text of the matched words. | | `start` | integer | no | Code-point offset of the snippet in the text that /v3/filings/{accession}/documents/{document}/text returns, under the same extractor (see index.extractor); offsets can move when the extractor changes. | | `text` | string | no | Plain text, never HTML. | ## Schema: SearchStatus Per year: document and filing counts, index_version, extractor, built at; the live indexer's lag and freshness; indexed_through; the years being rebuilt. Exactly these members. | Field | Type | Required | Description | |---|---|---|---| | `damaged_years` | array of integer \| null | yes | Years found damaged and dropped from the index until they are rebuilt; searches answer from the other years. | | `freshness` | object \| null | yes | Seconds from a filing's acceptance to its first searchable commit, over the last 15 minutes; null without a live indexer. | | `freshness.p50_s` | number \| null | no | | | `freshness.p95_s` | number \| null | no | | | `freshness.window` | string \| null | no | "15m". | | `indexed_through` | date-time (RFC 3339, UTC) \| null | yes | The newest event time the live index has applied. | | `indexer` | object \| null | yes | | | `indexer.indexed_through` | date-time (RFC 3339, UTC) \| null | no | | | `indexer.lag_events` | integer \| null | no | | | `indexer.lag_seconds` | number \| null | no | | | `indexer_stale` | boolean \| null | yes | True when the live indexer has not updated its status for over 120 seconds, or reports none; null when the index service does not say. | | `lag_seconds` | number \| null | yes | How far the live indexer is behind (0 when caught up). | | `partial_years` | array of integer \| null | yes | Years the live indexer started (the current or next year) that no full build has replaced yet: searchable, but they hold only the filings indexed live since; state is degraded while any exist. | | `rebuilding` | array of integer \| null | yes | Years being rebuilt. | | `state` | string \| null | yes | | | `tickers` | object \| null | yes | | | `tickers.file_date` | date (YYYY-MM-DD) \| null | no | | | `years` | array of object | yes | | | `years[].built_at` | string \| null | no | | | `years[].documents` | integer \| null | no | | | `years[].extractor` | string \| null | no | | | `years[].filings` | integer \| null | no | | | `years[].index_version` | string \| null | no | | | `years[].year` | integer | no | | | `years_missing` | array of integer \| null | yes | Years not searchable now: listed years that cannot be opened, and damaged_years. | ## Schema: SearchSubscription A saved search of the caller's organization that delivers to one of its callback endpoints. | Field | Type | Required | Description | |---|---|---|---| | `active` | boolean | yes | | | `created_at` | date-time (RFC 3339, UTC) | yes | | | `endpoint_id` | string | yes | cbe_ and 24 hex digits. | | `id` | string | yes | sub_ and 24 hex digits. | | `include_corrections` | boolean | yes | | | `kind` | string | yes | From the query: search when q is not empty, or doctypes, primary_only=true or entityName is given; else filing when a filing-level filter is given (forms, form_types, form_families and their exclusions, ciks, tickers, sics, states, inc_states, locationCode, items); else firehose. filing and firehose deliver filing.new, search delivers search.match. A filing subscription counts against limits.filter. Text subscriptions (kind search) are not offered: a create or PATCH whose query has q, doctypes, primary_only=true or entityName is a 400 invalid_parameter naming that parameter. One of: `filing`, `firehose`, `search`. | | `min_interval_s` | integer \| null | yes | Digest interval; null: every event is delivered alone. | | `name` | string | yes | | | `query` | object | yes | As stored: q, syntax, match and the structured filters as /v3/search/parse normalises them, tickers resolved into ciks at save time (no tickers member), items as given, accepted_from and accepted_to always null. | | `query.filters` | object | yes | | | `query.match` | string | yes | One of: `exact`, `stem`. | | `query.q` | string | yes | | | `query.syntax` | string | yes | One of: `sb`, `edgar`. | | `updated_at` | date-time (RFC 3339, UTC) | yes | | ## Schema: SearchSubscriptionCreate | Field | Type | Required | Description | |---|---|---|---| | `endpoint_id` | string | yes | One of the organization's endpoints; it must list filing.new (filing, firehose) or search.match (search). | | `include_corrections` | boolean | no | | | `min_interval_s` | integer \| null | no | | | `name` | string | yes | 1 to 800 bytes. | | `query` | object | yes | The query and filter parameters of /v3/search (q, syntax, match, forms, form_types, form_families, doctypes, ciks, tickers, sics, states, inc_states, primary_only, entityName, locationCode, ...) as JSON members (a list as a comma string or an array), plus items (8-K item codes). A filing-date window (filed_from, filed_to, startdt, enddt, or a dateRange preset) is a 400 naming it, and so is status (a subscription receives new filings); an acceptance window is not stored. An unknown ticker is a 400 naming tickers (q for a ticker: term in q). | ## Schema: SearchSubscriptionCreated | Field | Type | Required | Description | |---|---|---|---| | `active` | boolean | yes | | | `created_at` | date-time (RFC 3339, UTC) | yes | | | `endpoint_id` | string | yes | cbe_ and 24 hex digits. | | `id` | string | yes | sub_ and 24 hex digits. | | `include_corrections` | boolean | yes | | | `kind` | string | yes | From the query: search when q is not empty, or doctypes, primary_only=true or entityName is given; else filing when a filing-level filter is given (forms, form_types, form_families and their exclusions, ciks, tickers, sics, states, inc_states, locationCode, items); else firehose. filing and firehose deliver filing.new, search delivers search.match. A filing subscription counts against limits.filter. Text subscriptions (kind search) are not offered: a create or PATCH whose query has q, doctypes, primary_only=true or entityName is a 400 invalid_parameter naming that parameter. One of: `filing`, `firehose`, `search`. | | `min_interval_s` | integer \| null | yes | Digest interval; null: every event is delivered alone. | | `name` | string | yes | | | `query` | object | yes | As stored: q, syntax, match and the structured filters as /v3/search/parse normalises them, tickers resolved into ciks at save time (no tickers member), items as given, accepted_from and accepted_to always null. | | `query.filters` | object | yes | | | `query.match` | string | yes | One of: `exact`, `stem`. | | `query.q` | string | yes | | | `query.syntax` | string | yes | One of: `sb`, `edgar`. | | `updated_at` | date-time (RFC 3339, UTC) | yes | | | `resolved` | object | yes | The tickers of the query and the CIKs they were resolved to at save time; in the answers of POST and of a PATCH with a query. | | `resolved.tickers` | object | no | | ## Schema: SearchSubscriptionList | Field | Type | Required | Description | |---|---|---|---| | `data` | array of [SearchSubscription](#schema-searchsubscription) | yes | | | `has_more` | boolean | yes | | | `limits` | object | yes | By kind: filter (stored kind filing), firehose, search. limit: the plan's (0 without); used: active subscriptions of that kind. | | `limits.filter` | object | no | | | `limits.filter.limit` | integer | no | | | `limits.filter.used` | integer | no | | | `limits.firehose` | object | no | | | `limits.firehose.limit` | integer | no | | | `limits.firehose.used` | integer | no | | | `limits.search` | object | no | | | `limits.search.limit` | integer | no | | | `limits.search.used` | integer | no | | | `next_cursor` | string \| null | yes | | ## Schema: SearchSubscriptionPatch | Field | Type | Required | Description | |---|---|---|---| | `active` | boolean | no | true on an inactive subscription counts against its kind's limit. | | `endpoint_id` | string | no | | | `include_corrections` | boolean | no | | | `min_interval_s` | integer \| null | no | null clears it. | | `name` | string | no | | | `query` | object | no | Replaces the stored query whole. | ## Schema: SearchSubscriptionTest | Field | Type | Required | Description | |---|---|---|---| | `data` | array of object | yes | The payloads the subscription would have produced for filings accepted in the last 7 days, newest first, each the webhook envelope with test: true: filing.new (filing, firehose; id new:\:\) or search.match (search; id match:\:\). Nothing is delivered. | ## Schema: SearchSubscriptionTestRequest No members; the body is optional. An object with no fixed fields. ## Schema: SearchTotals Exact counts of the whole query (every page), in both units. All counts are null with totals=false. | Field | Type | Required | Description | |---|---|---|---| | `collapsed_hidden` | integer \| null | no | Results hidden by collapse=true; 0 without it. Totals and facets are never collapsed. | | `documents` | integer \| null | no | Matching documents. | | `filings` | integer \| null | no | Filings with at least one matching document. | | `relation` | string | no | gte when a NEAR candidate budget was exhausted (warning near_budget_exhausted); eq otherwise. One of: `eq`, `gte`. | ## Schema: SearchWarning | Field | Type | Required | Description | |---|---|---|---| | `code` | string | no | One of ignored_parameter, unknown_ticker, snippet_truncated, near_budget_exhausted, leading_wildcard_dropped, no_searchable_text, cursor_generation_expired, cluster_table_changed. | | `detail` | string | no | | | `doc_id` | string | no | snippet_truncated: the document whose snippet scan was cut short. | | `parameter` | string | no | ignored_parameter: the parameter's name. | | `position` | integer \| null | no | Character offset in q, when the warning concerns q. | | `ticker` | string | no | unknown_ticker: the ticker the ticker file does not know. | ## Schema: SecFiling One filing as SEC lists it for the entity. | Field | Type | Required | Description | |---|---|---|---| | `accepted_at` | date-time (RFC 3339, UTC) \| null | no | | | `accession` | string | no | | | `act` | string \| null | no | | | `cik` | string | no | | | `file_number` | string \| null | no | | | `filing_date` | date (YYYY-MM-DD) | no | | | `film_number` | string \| null | no | | | `form` | string | no | | | `in_v3` | boolean | no | Whether v3 has ingested this filing. A filing SEC deleted is in v3 too (status deleted). | | `is_inline_xbrl` | boolean \| null | no | | | `is_xbrl` | boolean \| null | no | | | `items` | array of string | no | | | `links` | object | no | | | `links.filing` | string \| null | no | The filing in v3; null when in_v3 is false. | | `primary_doc_description` | string \| null | no | | | `primary_document` | string \| null | no | | | `report_date` | date (YYYY-MM-DD) \| null | no | | | `size` | integer \| null | no | | | `status` | string \| null | no | The filing's status in v3; null when in_v3 is false. One of: `provisional`, `final`, `deleted`, `null`. | ## Schema: SecFilingList | Field | Type | Required | Description | |---|---|---|---| | `data` | array of [SecFiling](#schema-secfiling) | yes | | | `has_more` | boolean | no | | | `next_cursor` | string \| null | no | Always null: this list is paged with offset; use next_offset. | | `next_offset` | integer \| null | no | The offset of the next page; null on the last page (and when the snapshot store is unavailable). | | `offset` | integer | no | | | `snapshot` | [Snapshot](#schema-snapshot) | yes | | | `total` | integer \| null | no | Rows matching the filters; null when the snapshot store is unavailable. | ## Schema: Section | Field | Type | Required | Description | |---|---|---|---| | `absence_basis` | string | no | One of: `none`, `form_optional`, `bracketed`, `amendment_scope`. | | `confidence` | number \| null | no | Rule confidence (not a probability). | | `flags` | array of string | no | | | `incorporation` | object \| null | no | | | `item_code` | string | no | | | `item_order` | integer | no | | | `label` | string \| null | no | | | `links` | object | no | | | `part` | string | no | | | `section` | string | no | The key: 10k.1a, 10q.p1i2, 20f.3d. | | `status` | string | no | One of: `ok`, `incorporated_by_reference`, `combined_with`, `omitted`, `reserved`, `not_found`. | | `text_end` | integer \| null | no | | | `text_start` | integer \| null | no | | ## Schema: SectionMapOfFiling GET /v3/filings/{accession}/sections for S-4, S-4/A, F-4, F-4/A, DEFM14A, PREM14A, DEFM14C and DEF 14A. | Field | Type | Required | Description | |---|---|---|---| | `accession` | string | no | | | `confidence` | number \| null | no | | | `document` | object \| null | no | | | `extraction` | object | no | | | `family` | string \| null | no | One of: `merger`, `proxy`, `null`. | | `filing` | [FilingRef](#schema-filingref) | no | | | `flags` | array of string | no | | | `form` | string | no | | | `keys_found` | array of string | no | | | `primary_text_bytes` | integer \| null | no | | | `registrant` | string \| null | no | | | `sections` | array of [SectionMapRow](#schema-sectionmaprow) | no | | | `sections_found` | integer \| null | no | Sections with a key. | | `sections_unmapped` | integer \| null | no | | | `snapshot` | object | no | | | `source_format` | string \| null | no | | | `toc_entries` | integer \| null | no | | | `toc_kind` | string \| null | no | One of: `linked`, `text`, `none`, `null`. | | `versions` | string | no | | ## Schema: SectionMapRow One top-level section of a merger document's or proxy statement's map (extractor section_maps 0.2.0): a keyed heading, or an unmapped heading not inside one. It runs from its heading to the next heading that has a key or stands at its depth of the contents or shallower; the unmapped sub-headings in between are its subsections. Contents of one style give no depths: sections are then flat. | Field | Type | Required | Description | |---|---|---|---| | `block_count` | integer | no | | | `confidence` | number | no | | | `extracted_at` | string | no | | | `extractor_version` | string | no | | | `first_block_id` | string \| null | no | | | `flags` | array of string | no | | | `heading_block_id` | string | no | | | `heading_text` | string | no | The heading as filed. | | `key` | string | no | The canonical key, or 'unmapped'. Proposals: proposal_\, n = 1..99, one key per proposal (there is no 'proposals' key). | | `label` | string \| null | no | | | `last_block_id` | string \| null | no | | | `links` | object | no | | | `ordinal` | integer | no | 1-based, document order. | | `proposal_title` | string \| null | no | proposal_\: the heading without its number ('Proposal No. 2: Ratification of Ernst & Young LLP' -\> 'Ratification of Ernst & Young LLP'); null for other keys. | | `section` | string | no | The key or unmapped_\ for a heading no key names; the {section} of the text route. | | `signals` | array of string | no | | | `span_end` | integer | no | | | `span_start` | integer | no | | | `status` | string | no | One of: `ok`. | | `subsections` | array of object | no | The unmapped sub-headings inside this section, document order; each runs to the next heading. | | `subsections[].block_count` | integer | no | | | `subsections[].heading_block_id` | string | no | | | `subsections[].heading_text` | string | no | | | `subsections[].links` | object | no | | | `subsections[].ordinal` | integer | no | | | `subsections[].section` | string | no | unmapped_\ | | `subsections[].span_end` | integer | no | | | `subsections[].span_start` | integer | no | | | `subsections[].text_bytes` | integer | no | | | `subsections[].text_end` | integer | no | | | `subsections[].text_start` | integer | no | | | `subsections[].toc_text` | string \| null | no | | | `text_bytes` | integer | no | | | `text_end` | integer | no | | | `text_start` | integer | no | | | `title_as_found` | string | no | Same as heading_text (the shape of 10-K sections). | | `toc_text` | string \| null | no | The table of contents entry as filed, when the section came from it. | ## Schema: SectionScope | Field | Type | Required | Description | |---|---|---|---| | `amendment_no` | integer \| null | no | | | `explanatory_note` | object \| null | no | | | `is_amendment` | boolean | no | | | `items_present` | array of string | no | | | `kind` | string | no | One of: `full`, `part_iii_only`, `exhibits_only`, `items_subset`, `no_items`. | ## Schema: SectionSearchList | Field | Type | Required | Description | |---|---|---|---| | `as_of` | string \| null | no | | | `data` | array of object | no | | | `data[].filing` | [FilingRef](#schema-filingref) | no | | | `data[].form` | string | no | | | `data[].links` | object | no | | | `data[].scope_kind` | string | no | | | `data[].section` | [Section](#schema-section) | no | | | `form` | string | no | | | `has_more` | boolean | no | | | `next_cursor` | string \| null | no | | | `section` | string | no | | | `snapshot` | [Snapshot](#schema-snapshot) | no | | ## Schema: SectionsOfFiling | Field | Type | Required | Description | |---|---|---|---| | `accession` | string | no | | | `document` | object \| null | no | | | `extraction` | [Extraction](#schema-extraction) | no | | | `filing` | [FilingRef](#schema-filingref) | no | | | `financial_statements` | object \| null | no | | | `form` | string \| null | no | | | `scope` | [SectionScope](#schema-sectionscope) | no | | | `sections` | array of [Section](#schema-section) | no | | | `snapshot` | [Snapshot](#schema-snapshot) | no | | | `versions` | string | no | | ## Schema: Snapshot Which SEC submissions snapshot the response speaks for. On filing responses (filings, a filing, versions, reports): the snapshot whose values v3 stores, i.e. the date of the last complete snapshot sync; available is false until one has completed (the values are then those v3 learned itself). On entity responses: whether the snapshot store was used, and its snapshot; when available is false that response was built from the v3 database alone. | Field | Type | Required | Description | |---|---|---|---| | `available` | boolean | yes | | | `date` | date (YYYY-MM-DD) \| null | yes | Date of that snapshot; null when there is none. | ## Schema: Spac Whether the entity was a SPAC (blank check, SIC 6770), from the SIC and name in the headers of its filings over time (derive:spac_history). status: current (its filings still read SIC 6770), former (a later filing reads another SIC, or its name moved away from a SPAC name while the SIC still reads 6770), none (no filing reads 6770). merger_closed_at: the de-SPAC close, the period of report (event date) of the 8-K with Item 2.01 nearest the change (basis item_2_01); without one, the first filing under the new SIC (sic_change) or the date of the name change (name_change); merger_accession is the filing it comes from. ipo_at: the first 424B prospectus filed under 6770. flags: no_item_2_01, item_2_01_after_change, no_ipo_prospectus (a blank-check shell, not a listed SPAC), sic_returned_to_6770, name_change_only, merged_into_other_registrant (SIC and name unchanged: the SPAC merged into a new holding company, which is another entity), sic_changed_without_close (current: EDGAR moved the SIC, usually at the deal announcement, but no close was filed). | Field | Type | Required | Description | |---|---|---|---| | `basis` | string | yes | One of: `item_2_01`, `sic_change`, `name_change`, `none`. | | `computed_at` | string \| null | no | | | `current_name` | string \| null | no | | | `derive_version` | string \| null | no | | | `flags` | array of string | no | | | `ipo_accession` | string \| null | no | | | `ipo_at` | date (YYYY-MM-DD) \| null | no | | | `merger_accession` | string \| null | yes | | | `merger_closed_at` | date (YYYY-MM-DD) \| null | yes | | | `sic_history_source` | object \| null | no | first_6770_accession, first_6770_date, last_6770_accession, last_6770_date, sic_change_accession, sic_change_date, new_sic. | | `spac_name` | string \| null | no | | | `status` | string | yes | One of: `current`, `former`, `none`. | ## Schema: SpacCompanies | Field | Type | Required | Description | |---|---|---|---| | `data` | array of object | yes | | | `data[].cik` | string | no | | | `data[].links` | object | no | | | `data[].name` | string \| null | no | | | `data[].spac` | [Spac](#schema-spac) | no | | | `has_more` | boolean | yes | | | `next_cursor` | string \| null | yes | | | `spac` | string | yes | One of: `former`, `current`. | ## Schema: SpanText The canonical text of an item or section (not the filed HTML), page \[text_offset, text_offset + text_bytes) in UTF-8 bytes. | Field | Type | Required | Description | |---|---|---|---| | `accession` | string | no | | | `docmodel_version` | string \| null | no | | | `document` | object \| null | no | | | `extraction` | [Extraction](#schema-extraction) | no | | | `next_offset` | integer \| null | no | | | `section` | string | no | | | `served_model_version` | string | no | | | `text` | string \| null | no | | | `text_bytes` | integer \| null | no | | | `text_offset` | integer \| null | no | | | `text_reason` | string \| null | no | One of: `model_changed`, `bytes_unavailable`, `null`. | | `text_status` | string | no | One of: `current`, `from_version`, `reparse_pending`, `no_text`, `parse_pending`. | | `text_total_bytes` | integer \| null | no | | | `text_truncated` | boolean | no | | ## Schema: StreamEvent | Field | Type | Required | Description | |---|---|---|---| | `data` | object | yes | filing.\* events carry {filing} (and change or changes for filing.updated and filing.corrected); filing.deleted carries {accession, deleted_at, reason}; feed.day_closed carries {day, filings, live_first_seen, feed_only, corrected, deleted, realtime_missed}. | | `data.filing` | [StreamFiling](#schema-streamfiling) | no | | | `emitted_at` | date-time (RFC 3339, UTC) | yes | | | `id` | string | yes | str_\, zero padded. | | `schema_version` | integer | yes | One of: `1`. | | `stream_seq` | integer | yes | The event's position in the stream log; dense: a jump means a missed event. | | `type` | string | yes | One of: `filing.new`, `filing.updated`, `filing.corrected`, `filing.deleted`, `feed.day_closed`. | ## Schema: StreamFiling The filing of a filing.\* event: the members of GET /v3/filings/{accession} under the same names, plus form_family, registered_at, documents_state, primary_document and links.sec_index. Metadata and links only; document bytes come from the document links. | Field | Type | Required | Description | |---|---|---|---| | `accepted_at` | date-time (RFC 3339, UTC) \| null | no | | | `accepted_at_source` | string \| null | no | | | `accession` | string | no | | | `base_form` | string \| null | no | | | `doc_count` | integer | no | | | `documents` | array of object | no | At most 100 entries, none with detail=summary. | | `documents_state` | string | no | pending: the documents were not fetched within the 15 s hold; documents is empty and a filing.updated with change documents_added follows. One of: `complete`, `pending`. | | `documents_truncated` | boolean | no | true when the list was cut: the filing has more than 100 documents, or the list was shortened to fit the event's 16 KiB. | | `entities` | array of object | no | The filing's entities, as on GET /v3/filings/{accession}, with tickers. | | `entities_truncated` | boolean | no | true when the entities were cut to fit the event's 16 KiB: the filer plus the first 50, or the filer alone. Additive member. | | `filing_date` | date (YYYY-MM-DD) \| null | no | | | `first_seen_at` | date-time (RFC 3339, UTC) \| null | no | | | `form_family` | string \| null | no | | | `form_type` | string \| null | no | | | `items` | array of string | no | | | `late` | boolean | no | | | `links` | object | no | | | `links.sec_index` | string | no | | | `links.self` | string | no | | | `period_of_report` | date (YYYY-MM-DD) \| null | no | | | `primary_document` | object \| null | no | | | `provisional` | boolean | no | | | `registered_at` | date-time (RFC 3339, UTC) \| null | no | | | `source` | string | no | realtime for a filing seen live, feed for one first seen in the nightly feed (late: true). | | `status` | string | no | | | `total_bytes` | integer | no | | ## Schema: StreamPage | Field | Type | Required | Description | |---|---|---|---| | `data` | array of [StreamEvent](#schema-streamevent) | yes | In stream order (the order of emission, not acceptance order). | | `has_more` | boolean | yes | true when more events are waiting: ask again at once. | | `head_cursor` | string | yes | | | `live` | object | yes | | | `live.covered_until` | date-time (RFC 3339, UTC) \| null | no | | | `live.state` | string | no | The live ingest daemon's state, or down. | | `next_cursor` | string | yes | On every answer, an empty one included; with filters it moves past the events they dropped. | | `retention` | object | yes | | | `retention.days` | integer | no | | | `retention.oldest_cursor` | string \| null | no | | ## Schema: StreamStatus | Field | Type | Required | Description | |---|---|---|---| | `head_cursor` | string | yes | | | `latency` | object | yes | Percentiles in seconds of live filing.new, over the last hour and the last 24 hours: from SEC's acceptance to the event, and from registration to the event. | | `latency.from_accepted` | object | no | | | `latency.from_registered` | object | no | | | `live` | object | yes | | | `live.covered_until` | date-time (RFC 3339, UTC) \| null | no | | | `live.state` | string | no | | | `retention` | object | yes | | | `retention.days` | integer | no | | | `retention.oldest_cursor` | string \| null | no | | | `sequencer` | object | yes | | | `sequencer.lag_events` | integer \| null | no | | | `sequencer.lag_seconds` | number \| null | no | | | `sequencer.leading` | boolean \| null | no | | ## Schema: Usage | Field | Type | Required | Description | |---|---|---|---| | `as_of` | date-time (RFC 3339, UTC) | yes | | | `enforcement` | object | yes | Each feature: off, observe (counted and logged, never refused) or enforce. | | `key` | object | yes | | | `key.bytes` | integer \| null | no | | | `key.fingerprint` | string | no | First 12 hex digits of the key's SHA-256. | | `key.requests` | integer \| null | no | | | `limits` | object \| null | yes | Null while no limit is applied (metering off) and for a key without an organization. | | `limits.burst` | integer \| null | no | | | `limits.exempt` | object \| null | no | Null, or the caller's exemption from the rate limit (and, when concurrency is true, from the concurrency cap). The transfer allowance still applies. | | `limits.exempt.concurrency` | boolean | no | | | `limits.exempt.expires_at` | date-time (RFC 3339, UTC) \| null | no | When the exemption ends; null = no end set. | | `limits.exempt.rate` | boolean | no | | | `limits.exempt.scope` | string | no | key: this key; org: every credential of the organization; config: the server's configuration. One of: `key`, `org`, `config`. | | `limits.monthly_bytes` | integer \| null | no | Included response bytes per month (measured before compression); null = unlimited. | | `limits.monthly_requests` | integer \| null | no | | | `limits.requests_per_second` | integer \| null | no | Null while the caller is exempt from the rate limit. | | `month` | string | yes | The month counted, YYYY-MM: the calendar month in New York time (America/New_York). | | `org` | object | yes | This month, all keys of the organization (a legacy key: that key). Null members while usage is not counted. | | `org.bytes` | integer \| null | no | Billable response bytes (5xx and 429 excluded). | | `org.bytes_remaining` | integer \| null | no | | | `org.requests` | integer \| null | no | | | `org_id` | integer \| null | yes | The organization of the key; null for a legacy key not attributed to one. | | `plan` | string \| null | yes | The organization's plan id; null when its entitlements are not known (default limits apply). | | `reset_at` | date-time (RFC 3339, UTC) | yes | When the monthly allowance starts again: the start of the next month, midnight in New York (04:00 or 05:00 UTC). | ## Schema: ValueUnit The unit decision of one filing's values: dollar values are served only together with it. | Field | Type | Required | Description | |---|---|---|---| | `computed_at` | date-time (RFC 3339, UTC) \| null | no | | | `derive_version` | string \| null | no | | | `detected` | string \| null | no | One of: `dollars`, `thousands`, `ambiguous`, `untested`, `null`. | | `flags` | array of string | no | | | `method` | string \| null | no | One of: `date_rule`, `consensus_price`, `prior_period`, `null`. | | `multiplier` | integer \| null | no | | | `previous` | object \| null | no | | | `previous.detected` | string \| null | no | | | `previous.multiplier` | integer \| null | no | | | `previous.redecided_at` | date-time (RFC 3339, UTC) \| null | no | | | `rows_tested` | integer \| null | no | | | `status` | string | no | One of: `decided`, `pending`, `not_applicable`. | | `summary_unit` | string \| null | no | | ## Schema: Versions Version chain of a report: the original and its amendments. A single-item chain when nothing is linked. | Field | Type | Required | Description | |---|---|---|---| | `count` | integer | no | Members of the whole chain, deleted and not-ingested included. | | `items` | array of object | no | | | `items[].accepted_at` | date-time (RFC 3339, UTC) \| null | no | As a filing's accepted_at; null for a member that is not ingested. | | `items[].accepted_at_snapshot` | date-time (RFC 3339, UTC) | no | As on a filing: only when SEC's value differs from accepted_at. | | `items[].accepted_at_source` | string \| null | no | | | `items[].accession` | string | no | | | `items[].amendment_no` | integer \| null | no | | | `items[].amendment_seq` | integer \| null | no | 0 for the root, 1..n for amendments in filing order. A filing that is not an amendment has 0 from the moment it is ingested; an amendment is null until the linker has linked it. | | `items[].amendment_type` | string \| null | no | | | `items[].current` | boolean | no | | | `items[].filing_date` | date (YYYY-MM-DD) \| null | no | | | `items[].form_type` | string \| null | no | | | `items[].header_in_file` | boolean \| null | no | As on GET /v3/filings/{accession}. | | `items[].ingested` | boolean | no | False for a root known only from an amendment's link. | | `items[].link` | object | no | | | `items[].link.candidates` | array of object | no | Possible originals, shown for an ambiguous link. | | `items[].link.confidence` | number \| null | no | | | `items[].link.method` | string \| null | no | One of: `explicit_header`, `explicit_xml`, `original_date`, `period_match`, `date_items_match`, `file_number`, `parties`, `filer_file_number`, `description_text`, `manual`, `null`. | | `items[].link.status` | string | no | One of: `resolved`, `ambiguous`, `unresolved`, `target_not_public`, `target_not_yet_ingested`. | | `items[].primary_cik` | string \| null | no | | | `items[].scope` | string \| null | no | | | `items[].sec_url` | string \| null | no | | | `items[].status` | string \| null | no | | | `latest` | string \| null | no | Newest ingested, non-deleted member; null when every ingested member is deleted. | | `position` | integer | no | 1-based place of this filing in the whole chain (not in items when truncated). | | `report_key` | string | no | Accession of the chain's root (the original filing, even when it is not ingested). | | `root` | string | no | Alias of report_key. | | `snapshot` | [Snapshot](#schema-snapshot) | no | On /v3/filings/{accession}/versions only; the block embedded in a filing has none (the filing carries it). | | `truncated` | boolean | no | True when the chain has more than 200 members and items holds 200 of them (always the root, this filing and the latest, then the nearest to this filing). | ## Schema: WebhookEndpointVerification {"type": "endpoint.verification", "data": {"challenge": "…"}}: signed like every event. | Field | Type | Required | Description | |---|---|---|---| | `data` | object | yes | | | `data.challenge` | string | yes | | | `type` | string | yes | One of: `endpoint.verification`. | ## Schema: WebhookEnvelope The body of every webhook request (Standard Webhooks: type, a timestamp and data). Receivers ignore unknown members and unknown types; within schema_version 1 changes are additive only. Deliveries are at least once: deduplicate on id (the webhook-id header). | Field | Type | Required | Description | |---|---|---|---| | `data` | object | yes | | | `emitted_at` | date-time (RFC 3339, UTC) | yes | | | `event_seq` | integer \| null | no | search.match: the outbox position. | | `id` | string | yes | The webhook-id header's value: stable across the attempts of one delivery. | | `schema_version` | integer | yes | One of: `1`. | | `stream_seq` | integer | no | filing.\* events from the stream log: their stream position. | | `subscription` | object \| null | no | The subscription that produced the event ({id, name}); null for a test send; absent from endpoint.verification. | | `subscription.id` | string | no | | | `subscription.name` | string | no | | | `test` | boolean | yes | true for a test send (POST /v3/callbacks/endpoints/{id}/test): sample data, not billed. | | `type` | string | yes | | ## Schema: WebhookFilingCorrected | Field | Type | Required | Description | |---|---|---|---| | `data` | object | yes | | | `data.changes` | object | yes | | | `data.changes.docs_added` | array of any | no | | | `data.changes.docs_changed` | array of any | no | | | `data.changes.docs_removed` | array of any | no | | | `data.changes.header_fields` | array of object | no | | | `data.changes.header_fields[].after` | any | no | | | `data.changes.header_fields[].before` | any | no | | | `data.changes.header_fields[].field` | string | no | | | `data.filing` | [StreamFiling](#schema-streamfiling) | yes | | | `emitted_at` | date-time (RFC 3339, UTC) | yes | | | `event_seq` | integer \| null | no | search.match: the outbox position. | | `id` | string | yes | The webhook-id header's value: stable across the attempts of one delivery. | | `schema_version` | integer | yes | One of: `1`. | | `stream_seq` | integer | no | filing.\* events from the stream log: their stream position. | | `subscription` | object \| null | no | The subscription that produced the event ({id, name}); null for a test send; absent from endpoint.verification. | | `subscription.id` | string | no | | | `subscription.name` | string | no | | | `test` | boolean | yes | true for a test send (POST /v3/callbacks/endpoints/{id}/test): sample data, not billed. | | `type` | string | yes | One of: `filing.corrected`. | ## Schema: WebhookFilingDeleted | Field | Type | Required | Description | |---|---|---|---| | `data` | object | yes | | | `data.accession` | string | yes | | | `data.deleted_at` | date-time (RFC 3339, UTC) | yes | | | `data.reason` | string | yes | One of: `feed_deletion`, `sec_404`. | | `emitted_at` | date-time (RFC 3339, UTC) | yes | | | `event_seq` | integer \| null | no | search.match: the outbox position. | | `id` | string | yes | The webhook-id header's value: stable across the attempts of one delivery. | | `schema_version` | integer | yes | One of: `1`. | | `stream_seq` | integer | no | filing.\* events from the stream log: their stream position. | | `subscription` | object \| null | no | The subscription that produced the event ({id, name}); null for a test send; absent from endpoint.verification. | | `subscription.id` | string | no | | | `subscription.name` | string | no | | | `test` | boolean | yes | true for a test send (POST /v3/callbacks/endpoints/{id}/test): sample data, not billed. | | `type` | string | yes | One of: `filing.deleted`. | ## Schema: WebhookFilingDigest | Field | Type | Required | Description | |---|---|---|---| | `data` | object | yes | | | `data.count` | integer | yes | | | `data.events` | array of object | yes | | | `data.events[].data` | object | no | | | `data.events[].type` | string | no | | | `data.truncated` | boolean | yes | | | `emitted_at` | date-time (RFC 3339, UTC) | yes | | | `event_seq` | integer \| null | no | search.match: the outbox position. | | `id` | string | yes | The webhook-id header's value: stable across the attempts of one delivery. | | `schema_version` | integer | yes | One of: `1`. | | `stream_seq` | integer | no | filing.\* events from the stream log: their stream position. | | `subscription` | object \| null | no | The subscription that produced the event ({id, name}); null for a test send; absent from endpoint.verification. | | `subscription.id` | string | no | | | `subscription.name` | string | no | | | `test` | boolean | yes | true for a test send (POST /v3/callbacks/endpoints/{id}/test): sample data, not billed. | | `type` | string | yes | One of: `filing.digest`. | ## Schema: WebhookFilingNew | Field | Type | Required | Description | |---|---|---|---| | `data` | object | yes | | | `data.filing` | [StreamFiling](#schema-streamfiling) | yes | | | `emitted_at` | date-time (RFC 3339, UTC) | yes | | | `event_seq` | integer \| null | no | search.match: the outbox position. | | `id` | string | yes | The webhook-id header's value: stable across the attempts of one delivery. | | `schema_version` | integer | yes | One of: `1`. | | `stream_seq` | integer | no | filing.\* events from the stream log: their stream position. | | `subscription` | object \| null | no | The subscription that produced the event ({id, name}); null for a test send; absent from endpoint.verification. | | `subscription.id` | string | no | | | `subscription.name` | string | no | | | `test` | boolean | yes | true for a test send (POST /v3/callbacks/endpoints/{id}/test): sample data, not billed. | | `type` | string | yes | One of: `filing.new`. | ## Schema: WebhookFilingUpdated | Field | Type | Required | Description | |---|---|---|---| | `data` | object | yes | | | `data.change` | string | yes | documents_added, documents_refetched, finalized, delivery_merged or amendment_linked; new values may be added (receivers ignore unknown ones). | | `data.filing` | [StreamFiling](#schema-streamfiling) | yes | | | `emitted_at` | date-time (RFC 3339, UTC) | yes | | | `event_seq` | integer \| null | no | search.match: the outbox position. | | `id` | string | yes | The webhook-id header's value: stable across the attempts of one delivery. | | `schema_version` | integer | yes | One of: `1`. | | `stream_seq` | integer | no | filing.\* events from the stream log: their stream position. | | `subscription` | object \| null | no | The subscription that produced the event ({id, name}); null for a test send; absent from endpoint.verification. | | `subscription.id` | string | no | | | `subscription.name` | string | no | | | `test` | boolean | yes | true for a test send (POST /v3/callbacks/endpoints/{id}/test): sample data, not billed. | | `type` | string | yes | One of: `filing.updated`. | ## Schema: WebhookSearchDigest | Field | Type | Required | Description | |---|---|---|---| | `data` | object | yes | | | `data.count` | integer | yes | | | `data.events` | array of object | yes | | | `data.events[].data` | object | no | | | `data.events[].type` | string | no | | | `data.truncated` | boolean | yes | | | `emitted_at` | date-time (RFC 3339, UTC) | yes | | | `event_seq` | integer \| null | no | search.match: the outbox position. | | `id` | string | yes | The webhook-id header's value: stable across the attempts of one delivery. | | `schema_version` | integer | yes | One of: `1`. | | `stream_seq` | integer | no | filing.\* events from the stream log: their stream position. | | `subscription` | object \| null | no | The subscription that produced the event ({id, name}); null for a test send; absent from endpoint.verification. | | `subscription.id` | string | no | | | `subscription.name` | string | no | | | `test` | boolean | yes | true for a test send (POST /v3/callbacks/endpoints/{id}/test): sample data, not billed. | | `type` | string | yes | One of: `search.digest`. | ## Schema: WebhookSearchExportCompleted | Field | Type | Required | Description | |---|---|---|---| | `data` | object | yes | | | `data.export` | object | yes | | | `data.export.bytes_written` | integer | no | | | `data.export.download_url` | string \| null | no | | | `data.export.id` | string | no | | | `data.export.rows_written` | integer | no | | | `data.export.state` | string | no | | | `emitted_at` | date-time (RFC 3339, UTC) | yes | | | `event_seq` | integer \| null | no | search.match: the outbox position. | | `id` | string | yes | The webhook-id header's value: stable across the attempts of one delivery. | | `schema_version` | integer | yes | One of: `1`. | | `stream_seq` | integer | no | filing.\* events from the stream log: their stream position. | | `subscription` | object \| null | no | The subscription that produced the event ({id, name}); null for a test send; absent from endpoint.verification. | | `subscription.id` | string | no | | | `subscription.name` | string | no | | | `test` | boolean | yes | true for a test send (POST /v3/callbacks/endpoints/{id}/test): sample data, not billed. | | `type` | string | yes | One of: `search.export.completed`. | ## Schema: WebhookSearchMatch | Field | Type | Required | Description | |---|---|---|---| | `data` | object | yes | | | `data.documents` | array of object | yes | | | `data.documents[].doc_type` | string \| null | no | | | `data.documents[].seq` | integer | no | | | `data.documents[].snippets` | array of any | no | | | `data.documents[].url` | string \| null | no | | | `data.event_seq` | integer \| null | no | | | `data.filing` | object | yes | | | `data.filing.accepted_at` | string \| null | no | | | `data.filing.accession` | string | no | | | `data.filing.entities` | array of object | no | | | `data.filing.filing_date` | string \| null | no | | | `data.filing.form_type` | string \| null | no | | | `data.matched_at` | date-time (RFC 3339, UTC) | yes | | | `data.rematch` | boolean | yes | | | `data.search_url` | string | yes | The /v3/search request of the subscription's query, up to the filing's acceptance. | | `data.truncated` | boolean | yes | true when documents were left out to keep the event within 64 KiB. | | `emitted_at` | date-time (RFC 3339, UTC) | yes | | | `event_seq` | integer \| null | no | search.match: the outbox position. | | `id` | string | yes | The webhook-id header's value: stable across the attempts of one delivery. | | `schema_version` | integer | yes | One of: `1`. | | `stream_seq` | integer | no | filing.\* events from the stream log: their stream position. | | `subscription` | object \| null | no | The subscription that produced the event ({id, name}); null for a test send; absent from endpoint.verification. | | `subscription.id` | string | no | | | `subscription.name` | string | no | | | `test` | boolean | yes | true for a test send (POST /v3/callbacks/endpoints/{id}/test): sample data, not billed. | | `type` | string | yes | One of: `search.match`. | ## Schema: XbrlCompanyPeriods | Field | Type | Required | Description | |---|---|---|---| | `as_of` | string \| null | yes | | | `cik` | string | yes | | | `concept` | string | yes | | | `data` | array of object | yes | | | `derivation` | object | yes | additivity of the concept's unit (flow, per_share, share_count, ratio, stock); derived false with the refusal status for anything but a flow. | | `dims` | string | yes | | | `excluded` | [Excluded](#schema-excluded) | yes | | | `excluded_total` | integer | yes | | | `has_more` | boolean | yes | | | `next_cursor` | null | yes | | | `rule` | string | yes | | | `rule_version` | string | yes | | ## Schema: XbrlCompanySegments | Field | Type | Required | Description | |---|---|---|---| | `accuracy` | object | no | Measured precision and coverage of each requested kind on the latest unseen holdout (static; contract 2.10). | | `as_of` | string \| null | yes | | | `axes` | array of string | yes | | | `cik` | string | yes | | | `data` | array of object | yes | | | `excluded` | [Excluded](#schema-excluded) | yes | | | `excluded_total` | integer | yes | | | `from` | string \| null | yes | | | `has_more` | boolean | yes | | | `kinds` | array of string | yes | | | `limit` | integer | yes | Period ends per page (default 1: the latest fiscal year). | | `next_cursor` | string \| null | yes | Opaque: the next page (earlier period ends), same filters. | | `period` | string \| null | yes | | | `periods` | string | yes | The period classes served, canonical (default annual: the year ends, their years and instants). | | `rule` | string | yes | | | `rules` | object | yes | | | `to` | string \| null | yes | | | `view` | string | yes | One of: `latest`, `first_reported`. | ## Schema: XbrlCompanyStandard | Field | Type | Required | Description | |---|---|---|---| | `accuracy` | object | no | Measured precision and coverage of each requested field on the named map version (static; contract 2.9). | | `as_of` | string \| null | yes | | | `cik` | string | yes | | | `data` | array of object | yes | | | `data[].values` | object | no | | | `excluded` | [Excluded](#schema-excluded) | yes | | | `excluded_total` | integer | yes | | | `fields` | array of string | yes | | | `filings` | object | yes | By accession, each filing a value of the page comes from (or a derived value's input): form_type, filing_date, accepted_at, template, map {version, fingerprint}. | | `from` | string \| null | yes | | | `has_more` | boolean | yes | | | `limit` | integer | yes | Period ends per page. | | `map` | object | yes | | | `next_cursor` | string \| null | yes | Opaque: the next page (earlier period ends), same filters. | | `period` | string \| null | yes | | | `periods` | string | yes | The period classes served, canonical (default annual,quarterly). | | `rule` | string | yes | | | `to` | string \| null | yes | | | `ttm` | boolean | no | true: TTM rows (class ttm) at each quarter end of the monetary flow fields. | | `view` | string | yes | One of: `latest`, `first_reported`. | ## Schema: XbrlCompanyStatements | Field | Type | Required | Description | |---|---|---|---| | `as_of` | string \| null | yes | | | `category` | string \| null | yes | | | `cik` | string | yes | | | `data` | array of object | yes | | | `data[].accession` | string | no | | | `data[].filing` | object | no | With links.next: the filing route's next page of this report. | | `data[].has_more` | boolean | no | | | `data[].statements` | array of [XbrlStatement](#schema-xbrlstatement) | no | | | `excluded` | [Excluded](#schema-excluded) | yes | | | `excluded_total` | integer | yes | | | `has_more` | boolean | yes | A category alone: the report's next roles (next_cursor). | | `kind` | string \| null | yes | | | `next_cursor` | string \| null | yes | | | `role_uri` | string \| null | yes | | ## Schema: XbrlDuplicate The fact's duplicate group inside its instance (XBRL International note 2025-01-14): complete, consistent or inconsistent; rank 1 is the preferred member (higher decimals, then document order). No member is removed. | Field | Type | Required | Description | |---|---|---|---| | `group` | integer | no | | | `rank` | integer | no | | | `status` | string | no | One of: `complete`, `consistent`, `inconsistent`. | ## Schema: XbrlFact One fact as filed. value is the exact number (null for text, nil, a text block or filed text that is not a number); value_raw the filed characters (null for nil and text blocks). A text block's content is not served: text gives its span in the stored instance. | Field | Type | Required | Description | |---|---|---|---| | `concept` | object | no | | | `concept.is_extension` | boolean | no | | | `concept.name` | string | no | | | `concept.prefix` | string | no | | | `concept.qname` | string | no | | | `context` | object \| null | no | Null when the fact's contextRef names no context (warning context_missing). | | `decimals` | string \| null | no | As filed: INF, -3, 0, ...; null when absent. | | `dims_hash` | string \| null | no | First 16 bytes (hex) of the SHA-256 of the canonical dimensions; null without dimensions. | | `doc_seq` | integer | no | | | `duplicate` | [XbrlDuplicate](#schema-xbrlduplicate) | no | | | `entity_cik` | string \| null | no | | | `fact_id` | string \| null | no | | | `fact_seq` | integer | no | 1..n across every instance of the filing, in reading order. | | `footnote_nos` | array of integer | no | | | `is_nil` | boolean | no | | | `is_text_block` | boolean | no | | | `period` | [XbrlPeriod](#schema-xbrlperiod) | no | | | `precision_raw` | string \| null | no | | | `text` | object \| null | no | | | `text.document` | string | no | | | `text.sha256` | string \| null | no | | | `text.span_end` | integer | no | | | `text.span_start` | integer | no | | | `unit` | object \| null | no | | | `unit_norm` | string \| null | no | | | `value` | [NullableDecimal](#schema-nullabledecimal) | no | | | `value_raw` | string \| null | no | | | `xml_lang` | string \| null | no | | ## Schema: XbrlFilingFacts | Field | Type | Required | Description | |---|---|---|---| | `accession` | string | yes | | | `data` | array of [XbrlFact](#schema-xbrlfact) | yes | | | `extraction` | [Extraction](#schema-extraction) | yes | | | `filing` | [FilingRef](#schema-filingref) | yes | | | `footnotes` | array of object | yes | | | `has_more` | boolean | yes | | | `next_cursor` | string \| null | yes | | | `snapshot` | [Snapshot](#schema-snapshot) | yes | | | `xbrl` | object \| null | yes | The instances read, namespaces, taxonomy years, counts, dei cover values as filed, cover (registrants, securities, shares outstanding, public float, auditors), flags; null before a parse. | ## Schema: XbrlFilingRoles | Field | Type | Required | Description | |---|---|---|---| | `accession` | string | yes | | | `category` | string \| null | yes | | | `data` | array of [XbrlRole](#schema-xbrlrole) | yes | Role number order, at most 500 a page. | | `extraction` | [Extraction](#schema-extraction) | yes | | | `filing` | [FilingRef](#schema-filingref) | yes | | | `has_more` | boolean | yes | | | `next_cursor` | string \| null | yes | | | `snapshot` | [Snapshot](#schema-snapshot) | yes | | | `xbrl_statements` | object \| null | yes | | ## Schema: XbrlFilingStatements | Field | Type | Required | Description | |---|---|---|---| | `accession` | string | yes | | | `data` | array of [XbrlStatement](#schema-xbrlstatement) | yes | At most 25 roles (limit) and 2 MB of statement JSON a page. | | `extraction` | [Extraction](#schema-extraction) | yes | | | `filing` | [FilingRef](#schema-filingref) | yes | | | `has_more` | boolean | yes | | | `next_cursor` | string \| null | yes | | | `roles` | array of object \| null | yes | The filing's roles, role number order: on the first page (no cursor) only, its first 500 (the rest: /statements/roles); null on later pages. | | `roles_has_more` | boolean | yes | | | `snapshot` | [Snapshot](#schema-snapshot) | yes | | | `xbrl_statements` | object \| null | yes | Metadata source, documents read, counts, flags; null before a parse. | ## Schema: XbrlFinancialFact | Field | Type | Required | Description | |---|---|---|---| | `accession` | string | no | | | `concept` | string | no | | | `context_no` | integer \| null | no | | | `decimals` | string \| null | no | | | `dims` | array of any \| null | no | | | `dims_hash` | string \| null | no | | | `duplicate` | [XbrlDuplicate](#schema-xbrlduplicate) | no | | | `entity_cik` | string \| null | no | | | `fact_seq` | integer | no | | | `filing` | object | no | | | `filing.accepted_at` | date-time (RFC 3339, UTC) \| null | no | | | `filing.accepted_at_source` | string \| null | no | | | `filing.deleted_at` | date-time (RFC 3339, UTC) \| null | no | | | `filing.filing_date` | date (YYYY-MM-DD) \| null | no | | | `filing.form_type` | string \| null | no | | | `filing.status` | string | no | One of: `provisional`, `final`, `deleted`. | | `is_nil` | boolean | no | | | `is_text_block` | boolean | no | | | `legal_entity_member` | string \| null | no | | | `period` | [XbrlPeriod](#schema-xbrlperiod) | no | | | `unit_norm` | string \| null | no | | | `value` | [NullableDecimal](#schema-nullabledecimal) | no | | | `value_raw` | string \| null | no | | ## Schema: XbrlFinancialFactList | Field | Type | Required | Description | |---|---|---|---| | `as_of` | string \| null | yes | | | `cik` | string | yes | | | `concept` | string | yes | | | `data` | array of [XbrlFinancialFact](#schema-xbrlfinancialfact) | yes | | | `dims` | string | yes | | | `has_more` | boolean | yes | | | `next_cursor` | string \| null | yes | | | `period` | string \| null | yes | | ## Schema: XbrlFrame | Field | Type | Required | Description | |---|---|---|---| | `as_of` | string \| null | yes | | | `concept` | string | yes | | | `data` | array of object | yes | | | `data[].accepted_at` | string | no | | | `data[].accession` | string | no | | | `data[].decimals` | string \| null | no | | | `data[].derived_key` | string \| null | no | | | `data[].dims_hash` | string \| null | no | | | `data[].entity_cik` | string | no | | | `data[].fact_seq` | integer \| null | no | | | `data[].from_accession` | string | no | | | `data[].period` | object | no | With frame only: the fact's own start and end. | | `data[].source` | string | no | With frame only. One of: `reported`, `derived`. | | `data[].unit_norm` | string | no | | | `data[].valid_from` | string | no | | | `data[].value` | [NullableDecimal](#schema-nullabledecimal) | no | | | `data[].value_raw` | string \| null | no | | | `dims` | string | yes | | | `excluded` | [Excluded](#schema-excluded) | no | | | `excluded_total` | integer | no | | | `frame` | string | no | With frame only: CY2024Q4, CY2024 or CY2024Q4I. | | `has_more` | boolean | yes | | | `next_cursor` | string \| null | yes | Pass as cursor for the next page; null on the last. | | `period` | string | yes | As requested; with frame, the calendar period's dates (YYYY-MM-DD/YYYY-MM-DD, or the instant). | | `refused` | object | no | With frame only: basis_mismatch, the number of companies whose only value for the frame is a derived quarter refused as basis_mismatch (no number in the frame). | | `rule` | string | no | | | `rule_version` | string | no | | | `unit` | string \| null | no | | ## Schema: XbrlPeriod | Field | Type | Required | Description | |---|---|---|---| | `end` | date (YYYY-MM-DD) \| null | no | | | `start` | date (YYYY-MM-DD) \| null | no | | | `type` | string | no | One of: `instant`, `duration`, `forever`. | ## Schema: XbrlRole One role of a filing: role_no, role_uri, long_name, short_name, menu_category, position, html_file (its R page), statement_kind (null: not a statement or cover role), parenthetical, kind_method, nodes, tree_stored, matches_sec_render (true / false; null: no R page or no instance), links.statement. An object with no fixed fields. ## Schema: XbrlSegmentRow One line of a breakdown: role member \| segments_total \| reconciling \| consolidated; member (qname; null on the consolidated row), member_label (the company's own label), member_standard (country:XX, a srt / us-gaap member, or null for the company's own member), axis_qname, concept (null for an L4 consolidated value), concept_label, status ok \| ambiguous, value (a decimal string, null unless ok), unit_norm, weight (the row's sign in the check), fact_seq and context_no (the fact behind it), source (consolidated: l4:\:\ or fact), flags (check_fail, ambiguous_duplicate). An object with no fixed fields. ## Schema: XbrlSeries | Field | Type | Required | Description | |---|---|---|---| | `as_of` | string \| null | yes | | | `cik` | string | yes | | | `concept` | string | yes | | | `data` | array of object | yes | | | `data[].accession` | string | no | | | `data[].decimals` | string \| null | no | | | `data[].dup_inconsistent` | boolean | no | | | `data[].fact_seq` | integer | no | | | `data[].filing` | object | no | | | `data[].identity` | object | no | | | `data[].identity.dims_hash` | string \| null | no | | | `data[].identity.period` | [XbrlPeriod](#schema-xbrlperiod) | no | | | `data[].identity.unit_norm` | string | no | | | `data[].is_nil` | boolean | no | | | `data[].revision` | object | no | number: 1 = first reported; of: incarnations known at as_of; original_value: the first one's; changed: the value differs from the previous incarnation's. | | `data[].value` | [NullableDecimal](#schema-nullabledecimal) | no | | | `data[].value_raw` | string \| null | no | | | `dims` | string | yes | | | `excluded` | [Excluded](#schema-excluded) | no | | | `excluded_total` | integer | no | | | `has_more` | boolean | yes | | | `next_cursor` | null | yes | | | `view` | string | yes | One of: `latest`, `first_reported`, `revisions`. | ## Schema: XbrlStandardFrame | Field | Type | Required | Description | |---|---|---|---| | `accuracy` | object | no | Measured precision and coverage of the field on the named map version (static; contract 2.9). | | `as_of` | string \| null | yes | | | `data` | array of [XbrlStdValue](#schema-xbrlstdvalue) | yes | One ok value per company, CIK order, with entity_cik, period and links.company: reported, or derived (a quarter of a quarter frame, a TTM) with formula and inputs. | | `excluded` | [Excluded](#schema-excluded) | yes | | | `excluded_total` | integer | yes | | | `field` | string | yes | | | `frame` | string | yes | | | `has_more` | boolean | yes | | | `limit` | integer | yes | Companies with a value per page. | | `map` | object | yes | | | `next_cursor` | string \| null | yes | Opaque: the companies after this page, same filters. | | `period` | string | yes | | | `refused` | object | yes | Companies left out by status: ambiguous, not_reported, not_applicable, basis_mismatch, refused_\*. | | `rule` | string | yes | | | `ttm` | boolean | yes | true: each value is the trailing twelve months ending in the frame's quarter. | | `view` | string | yes | | ## Schema: XbrlStatement | Field | Type | Required | Description | |---|---|---|---| | `calculation` | array of object | no | | | `calculation[].child` | string | no | | | `calculation[].order` | [NullableDecimal](#schema-nullabledecimal) | no | | | `calculation[].order_raw` | string \| null | no | | | `calculation[].parent` | string | no | | | `calculation[].weight` | [NullableDecimal](#schema-nullabledecimal) | no | | | `calculation[].weight_raw` | string \| null | no | | | `columns` | array of object | no | | | `columns[].days` | integer \| null | no | | | `columns[].is_document_period` | boolean | no | | | `columns[].period` | [XbrlPeriod](#schema-xbrlperiod) | no | | | `layout` | object | no | The rows as SEC's renderer lays them out (its R page): kind tree (value rows in tree order, rows filled only by member facts after) or roll_forward (equity: one row group per period, oldest first); rows \[{seq, column, members}\] (column: the period group's column, null for tree; members: the member row group, axis=member;..., null for a main row -- a row repeats once per member group). | | `layout.kind` | string | no | One of: `tree`, `roll_forward`. | | `layout.rows` | array of object | no | | | `layout.rows[].column` | integer \| null | no | | | `layout.rows[].members` | string \| null | no | | | `layout.rows[].seq` | integer | no | | | `matches_sec_render` | boolean \| null | no | Compared when the filing was parsed: the assembled layout has the non-abstract rows of the filing's R page of this role in the same order (true) or not (false); null when the filing has no R page for it or no instance. | | `role` | object | no | role_no, role_uri, names, menu_category, statement_kind (BS IS CF EQ CI CP UN; null for a note, policy, table or detail role), parenthetical, kind_method, r_page (the SEC-rendered page of the role). | | `rows` | array of object | no | | | `rows[].cells` | array of [XbrlStatementCell](#schema-xbrlstatementcell) | no | | | `rows_from_seq` | integer | no | The first row (seq) served here: 1, or where a role cut by the previous page's row budget continues. | | `rows_has_more` | boolean | no | The role's later rows are on the next page (the page's 2 MB were reached). The calculation comes with the first part only. | | `warnings` | array of object | no | On the part that starts at the first row. | ## Schema: XbrlStatementCell The fact of a cell as filed (null: no fact for that row and column, never zero). A text block (a note's row): is_text_block true, value and value_raw null, text {doc_seq, span_start, span_end} where its content is in the stored instance. | Field | Type | Required | Description | |---|---|---|---| | `decimals` | string \| null | no | | | `entity_cik` | string \| null | no | | | `fact_seq` | integer | no | | | `is_nil` | boolean | no | | | `is_text_block` | boolean | no | | | `text` | object | no | | | `unit_norm` | string \| null | no | | | `value` | [NullableDecimal](#schema-nullabledecimal) | no | | | `value_raw` | string \| null | no | | ## Schema: XbrlStdValue One standard field for one period. Reported (source reported): status ok \| not_reported \| ambiguous \| not_applicable, value (null unless ok: a blank is never a zero), unit_norm, rule (candidate:\ or rollup), flags (identity_fail:\, scale_outlier:\, via_fallback, via_rollup, sign_applied), sources (the facts: fact_seq, context_no, concept, role value \| rollup_child, weight, calc_role_uri, value_raw), alternatives (other candidates with a fact), accession of the incarnation served (on /v3/companies/{cik}/standard its filing is in the response's filings; on /v3/financials/standard inline: filing, map {version, fingerprint}, template), incarnations (filings that stated an ok value). Derived (source derived; Q4, Q3, Q2, H2 of monetary flow fields): status ok \| basis_mismatch \| refused_\*, value, formula, inputs, rule_version, flags, detail, first_reported beside a basis_mismatch. An object with no fixed fields.