> ## Documentation Index
> Fetch the complete documentation index at: https://docs.numi.sh/llms.txt
> Use this file to discover all available pages before exploring further.

# Bulk files

> Every company, filing, axis, segment and line item, as Parquet and as CSV.

The bulk files have every table of the API, each as `<table>.parquet` and `<table>.csv`. `GET /v1/bulk/latest` returns links to the files of the account's plan:

* **Sandbox plan:** the sample, which has the sandbox companies only. They are listed on the [plans](https://docs.numi.sh/plans.md#the-sandbox) page.
* **Builder plan:** the full set.

```bash theme={null}
curl https://api.numi.sh/v1/bulk/latest -H "X-API-Key: $NUMI_API_KEY"
```

The response has these fields:

* `kind`: `sample` or `full`.
* `generated_at`: when the files were built.
* `licence`: the [data licence](https://docs.numi.sh/licensing.md).
* `files`: one entry per file, with its `name`, its size in `bytes`, a download `url` and `expires_at`.

You can download from a link without an API key. Each link is valid for 15 minutes, to `expires_at`. When a link expires, call `GET /v1/bulk/latest` again for new links. The MCP tool `get_bulk_download` returns the same links.

The response is 404 `not_found` until the first files are built.

## Tables

| Table | Columns |
| - | - |
| `companies` | `cik`, `ticker`, `tickers`, `name`, `exchange` |
| `filings` | `filing_id`, `cik`, `form_type`, `filing_date`, `period_end`, `fiscal_year`, `fiscal_period`, `period_type`, `is_amendment` |
| `segment_axes` | `axis_id`, `filing_id`, `cik`, `axis`, `axis_qname`, `period_start`, `period_end`, `currency`, `revenue_concept`, `revenue_total`, `segment_revenue_sum`, `reconciling_revenue_sum`, `coverage_ratio`, `reconciliation` |
| `segments` | `axis_id`, `member`, `label`, `kind`, `revenue`, `operating_income`, `total_assets`, `depreciation_amortization`, `revenue_share`, `position` |
| `fundamentals` | `filing_id`, `metric`, `concept`, `value`, `unit`, `currency`, `period_start`, `period_end`, `decimals` |

You can join the tables on their ids: `filings.cik` to `companies.cik`, `segment_axes.filing_id` and `fundamentals.filing_id` to `filings.filing_id`, and `segments.axis_id` to `segment_axes.axis_id`. `position` is the order of a row within its axis. The fields have the same meaning as in the API: see [segments](https://docs.numi.sh/segments.md) and [fundamentals](https://docs.numi.sh/fundamentals.md).

The files have only the filings that numi has extracted. In the CSV files, the first line is the column names, lines end with CRLF, and an empty field is null.

## Licence

The `licence` field has the text of the [data licence](https://docs.numi.sh/licensing.md): you can use the data commercially on every plan, and you may not resell the bulk file, or a substantial part of it, as a dataset.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.