Downloading Filings
Company filings — regulatory reports, earnings transcripts, investor presentations, and related documents — are the raw material for fundamental research. In FIRE, each stock has a filings/ folder under its workspace directory (stocks/<Name>__<Ticker>/company_documents/). Explorer does not expect you to hunt these down manually: when you open that folder, built-in integrations search official and common web sources and save documents straight into your workspace.
Sources vary by listing market. US tickers pull from SEC EDGAR for 10-K and 10-Q filings; transcripts and presentations often come from financial data platforms. India (.NS), Hong Kong (.HK), Taiwan (.TW / .TWO), and Korea (.KS / .KQ) listings use region-specific fetchers tied to local exchanges and filing sites. The exact buttons you see depend on the ticker suffix — only sources whose trigger matches your stock appear in the overlay.
How the Filings overlay works
Explorer uses overlays — contextual panels that appear in the left sidebar when you navigate to certain folders. The Filings overlay activates whenever your path ends in /filings (the same pattern used for Models on /models).
The overlay does not replace the main workspace. Think of it as two panels working together:
| Area | What you see |
|---|---|
| Center panel | Files already saved in filings/ — sortable table with Name, Type, Period, and Event Date. Click a row to open the document. |
| Sidebar overlay | Download controls — a Search Filings button, plus a status line showing your last download (count and date). |
Clicking Search Filings in the sidebar opens a search dialog. You configure the query there, review results in a table, and download selected items. New files land in filings/ and the center panel refreshes automatically.
Getting to the filings folder
If you have not added the company yet, start with Adding Stocks.
- In the left sidebar, expand Stocks and select the company folder.
- Press F or click Filings in the sidebar quick-access row (the icon buttons below the folder tree).
- Explorer navigates to
…/company_documents/and opens the Filings overlay.
You can also browse there manually through the folder tree. Any path ending in /filings triggers the overlay.
Running a search
1. Open the search dialog
In the sidebar overlay, click Search Filings. A dialog opens with two stages: setup (filters) and results (the hit list).
2. Set the year range
At the top of the setup screen, choose which fiscal years to scan. The default is the current calendar year. Use the 1yr arrow buttons on either side to shift the window backward or forward — you can search a single year or a multi-year span (shown as e.g. 2022–2024).
For a full historical backfill, step the range back several years before searching. Large spans query more sources and take longer.
3. Choose document types
Below the year range, Document Types shows toggle badges for every filing source available for this ticker. All types are selected by default. Click a badge to include or exclude that source — useful when you only want 10-K/10-Q and not transcripts, or when narrowing a slow search.
Typical sources by market:
| Market (ticker suffix) | Document types |
|---|---|
US (.US or bare ticker) |
10-K, 10-Q, Investor Presentation, Earnings Transcript |
India (.NS) |
Annual Report, Investor Presentation, Earnings Transcript |
Hong Kong (.HK) |
Annual Report, Investor Presentation, Earnings Transcript |
Taiwan (.TW, .TWO) |
Annual Report, Investor Presentation, Earnings Transcript |
Korea (.KS, .KQ) |
Annual Report, Investor Presentation, Earnings Transcript |
If a badge is missing, that source is not configured for your listing — see Adding New Document Download Links to wire one in.
4. Start the scan
Click Search Filings at the bottom of the setup screen. The dialog switches to results view and streams hits as each source finishes. While scanning, the title bar shows elapsed time (Searching the web (12.3s)), and pending sources appear as rows with a spinner.
Search runs sources in parallel. Results accumulate in the table — you do not need to wait for every source to finish before reviewing early hits. Use the back arrow (top left) to return to setup and change filters; starting a new search clears the previous result set.
A notice at the bottom of the setup screen — Involves Web Scraping — explains that some sources fetch publicly available data from third-party sites. FIRE caches responses and throttles requests, but external providers may still rate-limit or block access. Click the notice for the full disclaimer.
Understanding search results
The results table has these columns:
| Column | Meaning |
|---|---|
| Checkbox | Include this item in the batch download. Already-downloaded and unavailable rows are disabled. |
| Icon | Document kind — spreadsheet icon for filings, microphone for transcripts. A green icon means the file is already on disk from a prior fetch. |
| Name | Suggested filename (before download). |
| Type | Document classification — 10-K Annual Report, Earnings Transcript, etc. |
| Period | Fiscal period slug (e.g. 1QCY25, FY24). |
| Event Date | Filing or event date. |
| Source | Where the hit came from — SEC, NSE, BSE, YFinance, GFinance, etc. |
| Filetype | Output format. When multiple formats exist (e.g. PDF and HTML for EDGAR filings), pick one with the radio buttons. |
| Status | Already Exists if the file is in your folder; Unavailable if the source reported an error; download progress once you start a batch. |
You can sort by clicking column headers and filter inline using the small text inputs under Name, Type, Period, and Event Date. Column order is draggable if you want to rearrange.
New search results are auto-selected. Uncheck rows you do not want before downloading.
Downloading selected filings
- Review the checkboxes — only selected, not-yet-downloaded rows are included.
- Click Download Selected (N) at the bottom of the results table.
- The dialog switches to Download Progress, showing per-file status: waiting, downloading, converting (for format transforms), saved, or failed.
When the batch finishes, the dialog closes and returns to the results view. The center-panel filings table refreshes with your new files. The sidebar overlay updates its Last: N filings, Mon DD status line.
Downloads are skipped for files that already exist — Explorer compares against filenames on disk, including alternate extensions for the same 10-K/10-Q period. You can safely re-run a search to find newly published documents without duplicating what you already have.
File naming
Saved files follow a consistent pattern so the table, indexer, and agent can parse them:
<report_type>__<period>__<YYYYMMDD>.<ext>
Examples:
10k__FY24__20240215.pdf— US annual report10q__1QCY25__20250508.html— US quarterly filing (HTML variant)earnings_transcript__1QCY25__20250510.smd— structured transcript
The center-panel table derives Type, Period, and Event Date from these names. Keeping files in filings/ (not subfolders) ensures they appear in the table and are indexed for search.
Reading filings
Click any row in the center-panel filings table to open the document:
| Format | Viewer | Notes |
|---|---|---|
| PDF viewer | Page navigation, zoom, text search with highlight | |
| HTML | HTML viewer | Rendered filing content with search highlight |
| SMD | Semantic markdown viewer | Block-level metadata for transcripts and structured docs |
Use ⌘/Ctrl + K to search across all indexed filings in your workspace, not just the open file. Search hits can jump you into the right document with highlights.
Add a filing to the agent context with the + control (same as other files) so the agent can reason over the document while you work.
Caching and performance
Explorer maintains two layers of cache under appdata/explorer/:
| Location | Purpose |
|---|---|
cache/filings_cache.db |
Metadata index of discovered documents per source |
cache/filings_cache_blobs/ |
Downloaded blob payloads from upstream sources |
Cache policies are set per source in Explorer's manifest:
edgar_hybrid(US 10-K / 10-Q) — recent quarters refresh every 24 hours; filings older than one year are treated as immutable and kept indefinitely.forever(most transcripts and presentations) — blobs are never expired.
Repeat searches against the same year range are fast because Explorer reuses cached discovery results and skips unchanged upstream documents. Only new or updated filings appear as fresh download candidates.
Large backfills — many years × many document types — can take several minutes. Progress streams live in the search dialog; you can cancel by closing the dialog before starting a download (not during an active download batch).
Tips
- Start narrow, then widen. Search one year and one document type first to confirm the source works for your ticker, then expand the year range.
- Check the Source column when results look wrong — a US stock showing only YFinance hits may mean EDGAR discovery failed; retry or check the overlay log for errors.
- Re-search after earnings. Transcripts and presentations publish on a lag; a quarterly re-fetch picks up new events without re-downloading older files.
- API keys. Some sources read credentials from the system keyring (
dart,eodhd,finxsight,ember). Missing keys usually surface as source errors in the results table rather than silent failures.
Adding custom sources
Built-in sources are declared in Explorer's manifest.json under filings_sources. Each entry maps a button label, document type, cache policy, path trigger, and Python fetcher module.
To add or override a source for a market, see Adding New Document Download Links.
Next steps
Once filings are on disk, wire them into your workbook with Creating Models — the Update from EDGAR action reads cached 10-K/10-Q data directly into the model.