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