Documentation Index
Fetch the complete documentation index at: https://tradewatch.io/docs/llms.txt
Use this file to discover all available pages before exploring further.
Fundamental data is sourced from SEC EDGAR — the SEC’s public disclosure system for US-listed companies. This includes structured financial statements parsed from 10-K and 10-Q filings, company registration facts, a full filing index, and insider trading activity from Form 4 submissions.
Endpoints
| Endpoint | Summary | Key use case |
|---|
GET /stocks/income-statements | Income statements | Revenue, profit, EPS by period |
GET /stocks/balance-sheets | Balance sheets | Assets, liabilities, equity by period |
GET /stocks/cash-flow-statements | Cash flow statements | Operating, investing, and financing cash flows |
GET /stocks/company-facts | Company facts | SEC CIK, SIC code, fiscal year end |
GET /stocks/filings | SEC filings | Index of 10-K, 10-Q, 8-K, and other filings |
GET /stocks/insider-trades | Insider trades | Form 4 transactions by insiders |
Financial Statements
Endpoints: GET /stocks/income-statements · GET /stocks/balance-sheets · GET /stocks/cash-flow-statements
All three statement endpoints share the same filtering interface: ticker (required), period (annual for 10-K, quarterly for 10-Q), limit, and a set of report_date range filters (report_date_gte, report_date_lte, report_date_gt, report_date_lt). Results are ordered by report_date descending.
Income Statement
Revenue, profitability, and per-share metrics for each reporting period.
Key fields
| Field | What it means |
|---|
revenue | Total revenue (USD) |
cost_of_revenue | Cost of goods sold |
gross_profit | Revenue minus cost of revenue |
operating_expenses | Total operating expenses excluding cost of revenue |
operating_income | Gross profit minus operating expenses |
net_income | Net income attributable to the company |
eps | Basic earnings per share |
eps_diluted | Diluted EPS — accounts for stock options and convertibles |
Balance Sheet
Financial position at the end of each reporting period.
Key fields
| Field | What it means |
|---|
total_assets | Sum of all assets |
current_assets | Assets expected to be converted to cash within one year |
cash_and_equivalents | Cash and short-term liquid investments |
total_liabilities | Sum of all liabilities |
current_liabilities | Obligations due within one year |
total_equity | total_assets minus total_liabilities |
long_term_debt | Debt obligations due beyond one year |
retained_earnings | Cumulative net income retained after dividend payments |
Cash Flow Statement
Cash movements across operating, investing, and financing activities.
Key fields
| Field | What it means |
|---|
operating_cash_flow | Cash generated from core business operations |
capital_expenditures | Cash spent on property, plant, and equipment — typically stored as a negative number |
free_cash_flow | operating_cash_flow + capital_expenditures (computed field) |
investing_cash_flow | Net cash from investments and acquisitions |
financing_cash_flow | Net cash from debt and equity transactions |
dividends_paid | Cash dividends paid to shareholders — typically negative |
share_repurchases | Cash used to buy back shares — typically negative |
net_change_in_cash | Net increase or decrease in cash for the period |
free_cash_flow is a computed field. Because capital_expenditures is stored as a negative number (a cash outflow), the formula is addition: operating_cash_flow + capital_expenditures. A negative free_cash_flow is not unusual for companies in heavy investment phases.
When to use
- Screening stocks by revenue growth or profit margin across quarters
- Computing year-over-year changes in financial health metrics
- Verifying that a company generates sufficient cash to sustain operations or pay dividends
Example
# Last 4 quarterly income statements for AAPL
curl "https://api.tradewatch.io/stocks/income-statements?ticker=AAPL&period=quarterly&limit=4" \
-H "api-key: YOUR_API_KEY"
# Annual balance sheets for MSFT since 2020
curl "https://api.tradewatch.io/stocks/balance-sheets?ticker=MSFT&period=annual&report_date_gte=2020-01-01" \
-H "api-key: YOUR_API_KEY"
Company Facts
Endpoint: GET /stocks/company-facts
Returns static company registration information sourced from EDGAR. Useful as a lookup to resolve a ticker to its SEC identifiers or to understand the company’s industry classification.
Key fields
| Field | What it means |
|---|
cik | SEC Central Index Key — unique EDGAR identifier |
company_name | Legal name as registered with the SEC |
sic_code | Standard Industrial Classification code |
sic_description | Human-readable industry description |
state_of_incorporation | US state (or country) of legal incorporation |
fiscal_year_end | Month-day of fiscal year end in MM-DD format (e.g. 12-31) |
- Resolving a ticker to its SEC CIK for direct EDGAR lookups or cross-referencing with other SEC data sources
- Grouping companies by SIC industry in a screener
- Understanding whether a company’s fiscal year aligns with the calendar year when interpreting
report_date values
Example
curl "https://api.tradewatch.io/stocks/company-facts?ticker=AAPL" \
-H "api-key: YOUR_API_KEY"
SEC Filings
Endpoint: GET /stocks/filings
Returns an index of SEC EDGAR filings for a company. Includes 10-K (annual report), 10-Q (quarterly report), 8-K (current events/material news), and other filing types. Each record contains the accession number, dates, and a direct link to the document on EDGAR.
Key fields
| Field | What it means |
|---|
accession_number | Unique EDGAR filing identifier (e.g. 0000320193-23-000077) |
filing_type | SEC filing type: 10-K, 10-Q, 8-K, etc. |
filing_date | Date the document was submitted to the SEC |
report_date | End date of the period covered by the filing |
file_url | Direct URL to the filing document on SEC EDGAR |
- Linking to source documents from a financial analysis UI
- Filtering for 8-K filings to track material events such as earnings releases or acquisitions
- Auditing the completeness of structured statement data against the original source filing
Example
# All 10-K filings for AAPL
curl "https://api.tradewatch.io/stocks/filings?ticker=AAPL&filing_type=10-K" \
-H "api-key: YOUR_API_KEY"
Insider Trades
Endpoint: GET /stocks/insider-trades
Returns insider trading activity sourced from SEC Form 4 filings. Form 4 must be filed within two business days of a transaction by company officers, directors, and beneficial owners of more than 10% of a stock class. Results are ordered by filing_date descending.
Key fields
| Field | What it means |
|---|
insider_name | Name of the reporting insider |
transaction_date | Date the trade occurred |
filing_date | Date Form 4 was filed with the SEC |
transaction_type | Type code: P (purchase), S (sale), G (gift), A (conversion), F (exercise price payment) |
shares_transaction | Number of shares involved in the transaction |
price_per_share | Price per share at time of transaction (USD) |
transaction_value | Total value — computed as shares_transaction × price_per_share |
securities_owned | Total shares held by the insider after the transaction |
P) are generally viewed as a bullish signal — insiders are buying with personal capital. Insider sales (S) are more ambiguous; they are often pre-planned under 10b5-1 plans and may reflect personal liquidity needs rather than a negative outlook. Filter by transaction_type=P to isolate open-market purchases.
When to use
- Screening for unusual insider buying activity
- Alerting users when an executive makes a large open-market purchase
- Cross-referencing insider transactions with earnings announcement dates
Example
# Open-market purchases for AAPL in 2025
curl "https://api.tradewatch.io/stocks/insider-trades?ticker=AAPL&transaction_type=P&filing_date_gte=2025-01-01&filing_date_lte=2025-12-31" \
-H "api-key: YOUR_API_KEY"
