Datasets API endpoint
Returns terms-aggregation counts for one facet of the SEC companies dataset, scoped to the same filters as search. Facet enum: `sic`, `sic_description`, `exchange`, `state_of_incorporation`, `entity_type`, `reporting_currency`, `revenue_band`, `forms_filed`. `revenue_band` buckets latest-annual revenue into: `unknown`, `under_1m`, `1m_10m`, `10m_100m`, `100m_1b`, `1b_10b`, `over_10b`.
/datasets/sec-companies/facetsQuery parameters:
facet: required. Facet enum: sic, sic_description, exchange, state_of_incorporation, entity_type, reporting_currency, revenue_band, forms_filed.q, ticker, cik, sic, sic_description, exchange, state_of_incorporation, entity_type, min_revenue, max_revenue, min_net_income, min_total_assets, form_filed, min_insider_txn_count_90d: same filters as search, applied before aggregating.Response behavior:
items array (not an error) when the dataset has no data yet.facet values return the standard invalid params envelope.| Field | Filled in, of 50 checked | Values in the sample |
|---|---|---|
| value | 49 | |
| count | 50 | 254 to 909,364, median 487 |
| Parameter | Type | Required | Default | Description | Example |
|---|---|---|---|---|---|
| facet | string | Yes | Facet enum: sic, sic_description, exchange, state_of_incorporation, entity_type, reporting_currency, revenue_band, forms_filed Allowed values: sic, sic_description, exchange, state_of_incorporation, entity_type, reporting_currency, revenue_band, forms_filed. | sic | |
| q | string | No | Full-text query over the company name, or an exact ticker match, max 256 characters | ||
| ticker | string | No | Exact ticker filter (case-insensitive), max 32 characters | ||
| sic | string | No | Exact SIC industry-code filter, max 32 characters | ||
| exchange | string | No | Exact exchange filter as reported by EDGAR, max 64 characters | ||
| state_of_incorporation | string | No | Exact state/country-of-incorporation filter, max 32 characters | ||
| entity_type | string | No | Exact entity-type filter, max 64 characters | ||
| reporting_currency | string | No | Exact reporting-currency filter, ISO-4217 code, e.g. USD, JPY, EUR | ||
| has_financials | boolean | No | When true, keep only companies that have XBRL financial statements | ||
| min_revenue | number | No | Minimum latest-annual revenue in USD (normalized at reference rates), 0 or greater | ||
| form_filed | string | No | Exact form-type filter, e.g. 10-K, 8-K | ||
| x-api-key (header) | string | Yes | API key required |
curl -X GET "https://api.crawlora.net/api/v1/datasets/sec-companies/facets?facet=sic&q=coffee&has_financials=true" \ -H "x-api-key: $CRAWLORA_API_KEY"
{
"code": 200,
"msg": "OK",
"data": {
"dataset": "sec-companies",
"facet": "sic_description",
"items": [
{
"value": "Electronic Computers",
"count": 18
},
{
"value": "Pharmaceutical Preparations",
"count": 152
},
{
"value": "State Commercial Banks",
"count": 640
}
]
}
}Request schema
No body schema
Response schema
#/definitions/datasets.secCompaniesFacetResponseDoc
| Field | Type | Required | Enum | Bounds | Example | Description |
|---|---|---|---|---|---|---|
| code | integer | No | 200 | |||
| data | datasets.SecCompanyFacetResponse | No | ||||
| data.dataset | string | No | ||||
| data.facet | string | No | ||||
| data.items | array | No | ||||
| data.items[].count | integer | No | ||||
| data.items[].value | string | No | ||||
| msg | string | No | OK |
| Status | Description | Schema |
|---|---|---|
| 400 | Bad Request | #/definitions/app.Response |
| 429 | Too Many Requests | #/definitions/app.Response |
| 500 | Internal Server Error | #/definitions/app.Response |
Use environment variables for secrets and keep Crawlora API keys server-side.
curl -X GET "https://api.crawlora.net/api/v1/datasets/sec-companies/facets?facet=sic&q=coffee&has_financials=true" \
-H "x-api-key: $CRAWLORA_API_KEY"