---
title: "List filings"
method: GET
path: "/v1/filings"
---

# List filings

`GET /v1/filings`

## Request

- Base URL: `https://api.turos.app`
- URL: `https://api.turos.app/v1/filings`
- Auth: one of:
  - API key in header `x-api-key`
  - HTTP bearer

Search indexed SEC filing records for a bounded research or monitoring workflow. Filter by one issuer identifier, form, filing date, text, or a known accession number; results include filing identity and source links. Coverage and freshness reflect the returned records and provenance, not a promise of real-time or complete EDGAR history.

## Query parameters

- `ticker` string
- `symbol` string
- `cik` string
- `form` string
- `forms` string
- `fp` string
- `q` string
- `accession_number` string
- `date_from` string, date
- `date_to` string, date
- `filing_year` integer
- `fy` integer
- `sort` 'filing_date_desc' | 'filing_date_asc'
- `limit` integer
- `cursor` integer
- `submission_file_limit` integer
- `view` 'default' | 'compact' | 'agent'

## Response `200`

Successful filing search response. Default and compact views return filing-list metadata with full or compact filing records; view=agent returns the runtime agent list envelope with compact filing citation records.

- union
  - FilingList
    - `object` 'list', required
    - `data` object[], required
      - `object` 'filing', required
      - `id` string, required
      - `createdAt` string, required
      - `livemode` boolean, required
      - `entityId` string, required
      - `ticker` string, nullable
      - `companyName` string
      - `form` string, required
      - `filingDate` string, required
      - `reportDate` string, nullable
      - `accessionNumber` string, required
      - `title` string, required
      - `summaryMd` string
      - `snippet` string
      - `provenance` object, required
        - `source` string, required
        - `sourceLabel` string
        - `sourceAgency` string
        - `canonicality` string
        - `fallbackPolicy` string
        - `accessionNumber` string, nullable, required
        - `filingUrl` string, uri, required
        - `acceptedAt` string, nullable
        - `retrievedAt` string, required
        - `parserVersion` string, required
      - `freshness` object
        - `status` 'fresh' | 'current' | 'archival' | 'stale' | 'degraded' | 'unknown', required
        - `asOf` string, required
        - `sourcePublishedAt` string, nullable
        - `lagMs` integer, nullable
        - `synthetic` boolean
      - `materialization` object
        - `parserVersion` string, required
        - `materializationVersion` string, required
      - `validation` object
        - `status` 'validated' | 'unvalidated' | 'degraded', required
        - `confidence` 'high' | 'medium' | 'low', nullable
        - `validatedAt` string, nullable
        - `validationPipeline` string, nullable
        - `exceptions` string[], required
    - `hasMore` boolean, required
    - `nextCursor` string, nullable, required
    - `responseMode` 'compact' | 'standard' | 'verbose', nullable
    - `include` string[], nullable
    - `requestId` string, required
  - object
    - `object` 'list', required
    - `data` object[], required
      - `object` 'filing', required
      - `ticker` string, nullable, required
      - `form` string, required
      - `accessionNumber` string, required
      - `filingDate` string, required
      - `title` string, required
      - `filingUrl` string, nullable, required
    - `hasMore` boolean, required
    - `nextCursor` string, nullable, required
    - `requestId` string, required

## Other responses

- `400`: Invalid filing search filters, pagination, or response view.
- `502`: The filing search path could not complete (filing_search_failed).
- `default`: Contract-aware error response

---

[API](https://skmtc.dev/turos/apis/turos-api.md) · [All operations](https://skmtc.dev/turos/apis/turos-api/llms.txt) · [OpenAPI document](https://skmtc.dev/turos/apis/turos-api/revisions/a68d3ec80a56?raw)