# 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'
```
