Skip to content

API basics

Every route of the SEC Blast API follows these rules.

Base address and key

Every route is under https://api.secblast.com/v3. Send your API key with every request; only a few status routes, such as GET /v3/health, need none. Authentication shows the three ways to send it.

Lists and paging

Every list answers with the same envelope: { data, has_more, next_cursor }. While has_more is true, send the same request again with cursor set to next_cursor. The same loop then reads every list that takes a cursor; Pagination has it.

Errors

A failed request gets an HTTP status and a JSON problem body (RFC 9457, application/problem+json) with a stable code and a request_id. Branch on code: it does not change, while the wording of title and detail may. Errors lists every code.

Unknown parameters are refused

A query parameter that the route does not define gets 400 with the code unknown_parameter, and parameter names it. A misspelled filter therefore fails at once instead of returning unfiltered data.

Several values in one parameter

A parameter that takes several values takes them separated by commas, such as form=8-K,10-Q. More values than the parameter takes get 400 too_many_values, and max says how many it takes.

Dates and times

Dates are written YYYY-MM-DD, such as 2026-11-16. Times are RFC 3339 in UTC, such as 2026-11-16T21:12:33Z, so you never have to guess a time zone.

Numbers in responses

Amounts and quantities from filings are JSON strings, so no precision is lost: "shares": "2399", "price": "351.36". They appear in:

  • insider transactions and holdings (shares, price, total_value);
  • 13F holdings (value_usd, shares_or_principal);
  • XBRL facts, statements, frames, and series (value).

Parse them as decimals, such as Decimal("351.36") in Python. Counts, sizes, confidence, and score are JSON numbers.

Request IDs

Every response has an X-Request-Id header, and every problem body repeats it as request_id. Quote it when you contact support, so we can find your request.

Methods

Routes that read take GET, and every path also answers HEAD and OPTIONS. The webhook routes also take POST, PATCH, and DELETE, as their reference pages show. Any other method gets 405.

Calling from a browser

The API allows cross-origin requests, so a web page can call it directly, as the console does. Anyone who opens such a page can read the key it sends.

Live filings and when they become final

A new filing arrives live with status provisional, and you can read it at once. It becomes final when SEC's nightly feed file for its day confirms it; the stream and webhooks send that change as filing.updated. To list only confirmed filings, pass status=final.

Values from SEC's daily data

Some values come from SEC's daily submissions data, not from the filing itself: acceptance times, report periods, company records, SEC's own filing lists, and tickers. A response that can carry them has a snapshot field, { available, date }. date is the day of SEC's data the response uses. When available is false, SEC's data was not used, and the response comes from SEC Blast's own records alone.

Markdown version: /docs/basics.md