# Filing Search API Reference | SEC API

> Complete API reference for the SEC EDGAR Filing Search API. Every request parameter, every searchable field and every response attribute, with types, constraints and a live example response.

Source: https://sec-api.io/api-reference/query-api

Filing search and retrieval

POST`https://api.sec-api.io`

Search every filing and exhibit published on SEC EDGAR since 1993 with a Lucene expression, and get the filing metadata back as JSON. New filings are searchable 300 milliseconds after EDGAR publishes them.

[Read the guide for this API →](https://sec-api.io/docs/query-api)

## Authentication

Send the API key either as a header or as a query parameter. The header is preferred; the query parameter exists for cases where a header cannot be set, such as opening a URL directly in a browser.

Authorization: required header

The API key on its own. Do not prefix it with Bearer or any other word.

Example `Authorization: YOUR_API_KEY`

token: optional query parameter

The API key, appended to the URL. Use this only when a header is not possible.

## Request body

A JSON object. Content-Type must be application/json.

query: required string

The search expression in Lucene syntax. Every field listed under Searchable fields can be used, combined with AND, OR, NOT, ranges and wildcards.

Example `ticker:TSLA AND formType:"10-Q"`

from: string, Maximum 10000

Index of the first result to return, used for pagination. Increment by the value of size to page through results.

Default `"0"`

size: string, Maximum 50

Number of filings to return in one response.

Default `"10"`

sort: array of object

Sort order. Each item maps one field to an order object, for example [{ "filedAt": { "order": "desc" } }].

Default `[{ "filedAt": { "order": "desc" } }]`

order: string

Either asc or desc.

## Searchable fields

Every field below can be used inside query. 45 fields are searchable, and they match the structure of the objects returned in the response.

| Field | Description |
| --- | --- |
| `accessionNo` | Accession number of the filing |
| `formType` | EDGAR form type — "10-K", "10-Q", "8-K", "S-1", … |
| `cik` | CIK of the primary filer (leading zeros removed) |
| `ticker` | Ticker symbol of the primary filer |
| `companyName` | Primary filing company / person name |
| `companyNameLong` | Long company name including filer type (Issuer, Filer, Reporting) |
| `description` | Filing description, includes 8-K / 1-U item numbers |
| `filedAt` | Filing acceptance timestamp (ISO 8601, Eastern Time) |
| `periodOfReport` | Period of report — fiscal year end, quarter end, or transaction date |
| `effectivenessDate` | Effectiveness date (EFFECT, 18-K, TA-1, …) |
| `effectivenessTime` | Effectiveness time on EFFECT forms (HH:mm:ss) |
| `registrationForm` | Registration form type on EFFECT filings, e.g. "S-3" |
| `referenceAccessionNo` | Referenced accession number on EFFECT filings |
| `items` | Item codes on Form 8-K / 1-U / D / ABS-15G — e.g. "2.02", "5.02" |
| `groupMembers` | Group member names on SC 13D / 13G filings |
| `id` | System-internal unique filing ID — use `id:*` to match all |
| `entities.cik` | CIK of an entity referenced in the filing |
| `entities.companyName` | Entity name as reported on the filing cover |
| `entities.irsNo` | IRS number of the entity |
| `entities.stateOfIncorporation` | State of incorporation, e.g. "DE" |
| `entities.fiscalYearEnd` | Fiscal year end (MMDD), e.g. "1231" |
| `entities.sic` | SIC industry code, e.g. "3714" |
| `entities.type` | Form type as recorded on the entity row |
| `entities.act` | SEC act under which the filing is filed, e.g. "34" |
| `entities.fileNo` | SEC file number of the entity, e.g. "001-36743" |
| `entities.filmNo` | EDGAR film number of the entity |
| `documentFormatFiles.type` | Document type — "10-K", "EX-21", "GRAPHIC", … |
| `documentFormatFiles.description` | Free-text document description |
| `documentFormatFiles.documentUrl` | URL to the document on sec.gov |
| `dataFiles.type` | XBRL data file type — "EX-101.INS", "EX-101.SCH", … |
| `dataFiles.description` | XBRL data file description |
| `dataFiles.documentUrl` | URL to the XBRL data file |
| `seriesAndClassesContractsInformation.series` | Fund series ID, e.g. "S000011051" |
| `seriesAndClassesContractsInformation.name` | Fund series name |
| `seriesAndClassesContractsInformation.classesContracts.classContract` | Class / contract ID, e.g. "C000120702" |
| `seriesAndClassesContractsInformation.classesContracts.name` | Class / contract name |
| `seriesAndClassesContractsInformation.classesContracts.ticker` | Class / contract ticker, e.g. "ABRZX" |
| `linkToFilingDetails` | URL of the filing document itself on sec.gov. Pass this to the Download API or the PDF Generator API. |
| `linkToHtml` | URL of the filing index page on sec.gov. |
| `linkToTxt` | URL of the complete submission text file, which holds the filing and every exhibit. Can exceed several hundred megabytes. |
| `linkToXbrl` | URL of the XBRL instance document, when the filing has one. |
| `documentFormatFiles.sequence` | Position of the file within the filing, as assigned by EDGAR. The filing document itself is normally 1. |
| `documentFormatFiles.size` | Size of the file in bytes. |
| `dataFiles.sequence` | Position of the file within the filing, as assigned by EDGAR. The filing document itself is normally 1. |
| `dataFiles.size` | Size of the file in bytes. |

## Response

A JSON object. Nested attributes are collapsed; expand one to see its fields.

total: object

How many filings matched the query.

value: integer

Number of matching filings, capped at 10000. A value of 10000 with relation gte means more than 10000 filings matched.

relation: string

Either eq, meaning value is exact, or gte, meaning value is a floor.

filings: array of object

The matching filings, at most size per response. Every field of a filing object is itself searchable.

id: string

Internal unique id of the filing record. One filing produces several records when it references several entities, as Form 4 does. They share an accessionNo but differ by id.

accessionNo: string

Accession number of the filing, for example 0000028917-20-000033.

formType: string

EDGAR form type, for example 10-K or 10-K/A. All 150+ types are covered, including SEC correspondence.

filedAt: string

Timestamp EDGAR accepted the filing, ISO 8601 in Eastern Time. The offset is -04:00 during daylight saving and -05:00 otherwise. This is the Accepted attribute, which does not always fall on the same date as Filing Date.

cik: string

CIK of the filing issuer, leading zeros removed.

ticker: optional string

Ticker of the filer. Absent for non-listed filers such as mutual funds and asset-backed securities.

companyName: string

Name of the primary filing company or person.

companyNameLong: string

Company name including the filer type, for example ALLIED MOTION TECHNOLOGIES INC (0000046129) (Issuer).

description: string

Form description. On 8-K, D, ABS-15G and 1-U filings it also carries the reported item numbers.

periodOfReport: optional string

Reporting period, YYYY-MM-DD. Its meaning depends on the form: fiscal year end on 10-K, transaction date on Form 4, quarter end on 13F.

linkToFilingDetails: string

URL of the filing document itself on sec.gov. Pass this to the Download API or the PDF Generator API.

linkToHtml: string

URL of the filing index page on sec.gov.

linkToTxt: string

URL of the complete submission text file, which holds the filing and every exhibit. Can exceed several hundred megabytes.

linkToXbrl: optional string

URL of the XBRL instance document, when the filing has one.

effectivenessDate: optional string

Effectiveness date, YYYY-MM-DD. Reported on EFFECT, 18-K, TA-1 and a few other forms.

effectivenessTime: optional string

Effectiveness time, HH:mm:ss. Reported on EFFECT forms only.

registrationForm: optional string

Registration form type reported on EFFECT forms, for example S-1.

referenceAccessionNo: optional string

Referenced accession number reported on EFFECT forms.

items: optional array of string

Item codes reported on 8-K, D, ABS-15G and 1-U filings, for example Item 9.01: Financial Statements and Exhibits.

groupMembers: optional array of string

Group member names reported on SC 13D and SC 13G filings.

entities: array of object

Every entity the filing refers to. The first item is always the filing issuer.

companyName: string

Entity name including its filer type.

cik: string

CIK of the entity, leading zeros kept.

irsNo: optional string

IRS number of the entity.

stateOfIncorporation: optional string

State of incorporation, for example AR.

fiscalYearEnd: optional string

Fiscal year end as MMDD, for example 0201.

sic: optional string

SIC code and label, for example 5311 Retail-Department Stores.

type: optional string

Form type being filed, matching formType.

act: optional string

SEC act the filing was made under, for example 34.

fileNo: optional string

File number of the entity, for example 001-06140.

filmNo: optional string

Film number of the entity.

documentFormatFiles: array of object

Primary files of the filing and its exhibits. The first item is the filing, the last is its .txt version. Everything between can be exhibits, press releases, graphics or XML.

sequence: string

Position of the file within the filing, as assigned by EDGAR. The filing document itself is normally 1.

description: optional string

Description of the file as reported by the filer, for example EXHIBIT 31.1.

documentUrl: string

URL of the file on sec.gov, including its extension: .htm, .pdf, .txt, .xml, .jpg and others.

type: optional string

Type of the file, for example 10-Q, EX-32.1 or GRAPHIC. Searchable through documentFormatFiles.type.

size: optional string

Size of the file in bytes.

dataFiles: array of object

Data files attached to the filing, primarily XBRL.

sequence: string

Position of the file within the filing, as assigned by EDGAR. The filing document itself is normally 1.

description: optional string

Description of the file as reported by the filer, for example EXHIBIT 31.1.

documentUrl: string

URL of the file on sec.gov, including its extension: .htm, .pdf, .txt, .xml, .jpg and others.

type: optional string

Type of the file, for example 10-Q, EX-32.1 or GRAPHIC. Searchable through documentFormatFiles.type.

size: optional string

Size of the file in bytes.

seriesAndClassesContractsInformation: optional array of object

Series and class or contract information, reported by funds.

series: string

Series ID, for example S000001297.

name: string

Name of the entity.

classesContracts: array of object

The classes or contracts under the series.

classContract: string

Class or contract ID, for example C000011787.

name: string

Name of the class or contract.

ticker: string

Ticker of the class or contract.

## Status codes

|  |  |
| --- | --- |
| `200` | Success. The response holds total, query and filings. |
| `400` | The request body could not be parsed, or the Lucene expression in query is malformed. |
| `403` | The API key is missing, or it is not valid. |
| `429` | Too many requests. Slow the request rate and retry. |
| `500` | Server error. Retry, and report it if it persists. |

## Request example

POST https://api.sec-api.io

```json
{
  "query": "ticker:TSLA AND formType:\"10-Q\"",
  "from": "0",
  "size": "10",
  "sort": [{ "filedAt": { "order": "desc" } }]
}
```

```python
from sec_api import QueryApi

queryApi = QueryApi("YOUR_API_KEY")

response = queryApi.get_filings({
    "query": "ticker:TSLA AND formType:\"10-Q\"",
    "from": "0",
    "size": "10",
    "sort": [{"filedAt": {"order": "desc"}}],
})
```

```javascript
import { queryApi } from "sec-api";

queryApi.setApiKey("YOUR_API_KEY");

const response = await queryApi.getFilings({
  query: 'ticker:TSLA AND formType:"10-Q"',
  from: "0",
  size: "10",
  sort: [{ filedAt: { order: "desc" } }],
});
```

```bash
curl -X POST https://api.sec-api.io \
  -H "Authorization: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "ticker:TSLA AND formType:\"10-Q\"",
    "from": "0",
    "size": "10",
    "sort": [{ "filedAt": { "order": "desc" } }]
  }'
```

## Response example

200 OK · application/json

```json
{
  "total": { "value": 3, "relation": "eq" },
  "filings": [
    {
      "id": "cd1c0d1b3d1f9b8a6b0e5e3e7c2a1f40",
      "accessionNo": "0001564590-20-047486",
      "formType": "10-Q",
      "filedAt": "2020-10-26T16:06:24-04:00",
      "cik": "1318605",
      "ticker": "TSLA",
      "companyName": "Tesla, Inc.",
      "companyNameLong": "Tesla, Inc. (Filer)",
      "description": "Form 10-Q - Quarterly report",
      "periodOfReport": "2020-09-30",
      "linkToFilingDetails": "https://www.sec.gov/Archives/edgar/data/1318605/000156459020047486/tsla-10q_20200930.htm",
      "linkToHtml": "https://www.sec.gov/Archives/edgar/data/1318605/000156459020047486/0001564590-20-047486-index.htm",
      "linkToTxt": "https://www.sec.gov/Archives/edgar/data/1318605/000156459020047486/0001564590-20-047486.txt",
      "linkToXbrl": "https://www.sec.gov/Archives/edgar/data/1318605/000156459020047486/tsla-20200930.xml",
      "entities": [
        {
          "companyName": "Tesla, Inc. (Filer)",
          "cik": "0001318605",
          "irsNo": "912197729",
          "stateOfIncorporation": "DE",
          "fiscalYearEnd": "1231",
          "sic": "3711 Motor Vehicles & Passenger Car Bodies",
          "type": "10-Q",
          "act": "34",
          "fileNo": "001-34756",
          "filmNo": "201051663"
        }
      ],
      "documentFormatFiles": [
        {
          "sequence": "1",
          "description": "10-Q",
          "documentUrl": "https://www.sec.gov/Archives/edgar/data/1318605/000156459020047486/tsla-10q_20200930.htm",
          "type": "10-Q",
          "size": "5097480"
        }
      ],
      "dataFiles": [
        {
          "sequence": "9",
          "description": "XBRL TAXONOMY EXTENSION SCHEMA",
          "documentUrl": "https://www.sec.gov/Archives/edgar/data/1318605/000156459020047486/tsla-20200930.xsd",
          "type": "EX-101.SCH",
          "size": "109528"
        }
      ],
      "seriesAndClassesContractsInformation": []
    }
  ]
}
```