Twelve Data API endpoint reference, credit costs, and integration status. Use when adding new API endpoints, checking credit budgets, or planning features that need Twelve Data.
Plan: Pro ($99/mo, 1,597 credits/min). Tracking: #131.
| Endpoint | Path | Credits | Used In |
|---|---|---|---|
| Time Series | /time_series | 1 | metrics.ts, historical-prices.ts |
| Quote | /quote | 1 | batch.ts, profile.ts, vix.ts |
| Logo | /logo | 1 | logo.ts |
| Profile | /profile | 10 | batch.ts, profile.ts |
| Earnings | /earnings | 20 | batch.ts, , |
earnings.tsearnings-performance.ts| Statistics | /statistics | 50 | batch.ts, metrics.ts, valuation-ratios.ts |
| Income Statement | /income_statement | 100 | batch.ts, growth.ts, stock-based-compensation.ts |
| Balance Sheet | /balance_sheet | 100 | batch.ts, analysis.ts |
| Cash Flow | /cash_flow | 100 | batch.ts, analysis.ts, stock-based-compensation.ts |
| Batch | /batch | sum | client.ts — combines endpoints into 1 HTTP call |
| Bundle | Endpoints | Credits |
|---|---|---|
| AnalysisBundle | profile + quote + statistics + balance_sheet + income_statement + cash_flow | 361 |
| GrowthBundle | profile + quote + statistics + income_statement + cash_flow | 261 |
| EarningsBundle | profile + quote + statistics + earnings | 81 |
| Endpoint | Path | Credits | Issue | Status |
|---|---|---|---|---|
| Logo | /logo | 1 | #174 | API done, web CompanyLogo not wired |
| SMA | /sma | 1 | #137 | Technical context — SMA 50/200 |
| RSI | /rsi | 1 | #137 | Technical context — overbought/oversold |
| Symbol Search | /symbol_search | 1 | #131 | Not yet implemented |
| Endpoint | Path | Credits | Notes |
|---|---|---|---|
| Dividends | /dividends | 20 | |
| Earnings Estimate | /earnings_estimate | 20 | Analyst estimates |
| Revenue Estimate | /revenue_estimate | 20 | Analyst estimates |
| EPS Trend | /eps_trend | 20 | |
| EPS Revisions | /eps_revisions | 20 | |
| Growth Estimates | /growth_estimates | 20 | |
| Price Target | /price_target | 75 | Analyst consensus |
| Analyst Ratings Snapshot | /analyst_ratings/snapshot | 75 | |
| Recommendations | /recommendations | 100 | Analyst buy/sell/hold |
| Analyst Ratings (US) | /analyst_ratings/us_equities | 200 | |
| Insider Transaction | /insider_transaction | 200 | |
| Tax Information | /tax_information | 50 | |
| Key Executives | /key_executives | 1,000 | |
| Institutional Holders | /institutional_holders | 1,500 | |
| Fund Holders | /fund_holders | 1,500 | |
| Direct Holders | /direct_holders | 1,500 |
| Endpoint | Path | Credits | Notes |
|---|---|---|---|
| All Technical Indicators | /sma, /rsi, /macd, etc. | 1 each | |
| Latest Price | /price | 1 | Lighter than /quote |
| End of Day Price | /eod | 1 | |
| Market State | /market_state | 1 | |
| Exchanges | /exchanges | 1 | |
| Splits | /splits | 20 | |
| Earnings Calendar | /earnings_calendar | 40 | Per request, not per symbol |
| Dividends Calendar | /dividends_calendar | 40 | Per request |
| EDGAR Filings | /edgar_filings | 50 | |
| Exchange Schedule | /exchange_schedule | 100 | |
| Market Movers | /market_movers/{market} | 100 |
EDGAR is the legal source of truth — every provider (Twelve Data, FMP, etc.) reads from EDGAR and repackages it. Any discrepancy is the provider's error. Financial statement data should come from EDGAR directly.
POC: packages/ingest/src/poc/sec-edgar-poc.ts — validates XBRL parsing against GOOGL (Technology) and SOFI (Financials). Uses https://data.sec.gov/api/xbrl/companyfacts/CIK{cik}.json.
| Data | Endpoint | Credits | Why TD |
|---|---|---|---|
| Live/delayed price | /quote | 1 | No market data on EDGAR |
| Historical OHLCV | /time_series | 1 | No price series on EDGAR |
| Company profile | /profile | 10 | Description, logo, sector metadata |
| Live ratios & stats | /statistics | 50 | P/E, beta, 52-week range need live price |
| Company logo | /logo | 1 | No images on EDGAR |
| Technical indicators | /sma, /rsi, etc. | 1 each | Computed from price data |
| Data | TD Endpoint Replaced | Credits Saved | EDGAR Source |
|---|---|---|---|
| Income Statement | /income_statement | 100 | XBRL us-gaap (Revenue, NetIncome, EPS, etc.) |
| Balance Sheet | /balance_sheet | 100 | XBRL us-gaap (Assets, Liabilities, Equity, Debt) |
| Cash Flow | /cash_flow | 100 | XBRL us-gaap (OperatingCF, CapEx, SBC, Dividends) |
| Earnings (actuals) | /earnings | 20 | XBRL EarningsPerShareDiluted |
| Dividends | /dividends | 20 | XBRL PaymentsOfDividends |
| Splits | /splits | 20 | XBRL filing data |
| Insider transactions | /insider_transaction | 200 (Ultra) | Form 4 filings |
| 10-K narratives | N/A (no provider has this) | — | Full HTML + LLM extraction (#145) |
| Company guidance | N/A | — | 8-K Items 2.02/7.01 + LLM extraction (#118) |
| Bundle | Before (TD only) | After (hybrid) | Savings |
|---|---|---|---|
| AnalysisBundle | 361 cr | 62 cr (profile+quote+statistics) | -299 (83%) |
| GrowthBundle | 261 cr | 62 cr | -199 (76%) |
| EarningsBundle | 81 cr | 62 cr | -19 (23%) |
On Pro (1,597 cr/min): ~4 cold-cache analyses/min → ~25 analyses/min.
User-Agent header (e.g., StockFind [email protected])| API | URL Pattern | Data |
|---|---|---|
| Company Facts (XBRL) | data.sec.gov/api/xbrl/companyfacts/CIK{cik}.json | All US-GAAP facts for a company |
| Company Concept | data.sec.gov/api/xbrl/companyconcept/CIK{cik}/us-gaap/{tag}.json | Single metric history |
| Full-Text Search | efts.sec.gov/LATEST/search-index?q={query}&forms={forms} | Find filings by content |
| Filing Index | data.sec.gov/submissions/CIK{cik}.json | Filing metadata, dates, form types |
| Ticker-to-CIK | sec.gov/files/company_tickers.json | Map ticker symbols to CIK numbers |
Full details: Invoke the
edgarskill. See alsopackages/edgar/CLAUDE.mdand.claude/plans/federated-frolicking-sifakis.md.
Package: packages/edgar/ (@stockfind/edgar) — separate Neon DB, on-demand fetch-through + weekly smart refresh.
financials.ts tries EDGAR first, falls back to Twelve Data for non-SEC filers. Returns same IncomeStatement, BalanceSheet, CashFlowStatement types — zero breaking changes. batch.ts removes statement endpoints, only batches profile + quote + statistics + logo (63 credits).
https://api.twelvedata.comapps/api/src/integrations/stocks/client.tsapps/api/src/integrations/stocks/types.ts (46 exported interfaces)Authorization: apikey <key> headerapi-credits-used / api-credits-left response headerstransformKeys() converts snake_case to camelCaseCredit costs verified from Twelve Data docs on 2026-03-08.