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