# Twelve Data — Complete Reference for LLMs > Twelve Data is a financial market data platform providing real-time and historical data for stocks, forex, cryptocurrencies, ETFs, mutual funds, bonds, and commodities via REST API, WebSocket, official SDKs, spreadsheet add-ons, and a hosted MCP server. Coverage spans 1M+ instruments across 250+ exchanges in 90+ countries. This file contains the full condensed reference: authentication, every endpoint with key parameters and plan requirements, WebSocket protocol, pricing, and integrations. Per-endpoint markdown docs live under https://twelvedata.com/docs/llms/ Company: Twelve Data Pte. Ltd. (Singapore). Mission: organize the world's financial data and make it universally accessible. Website: https://twelvedata.com | Docs: https://twelvedata.com/docs | Docs index for LLMs: https://twelvedata.com/docs/llms.txt System status: https://twelvedata.isitup.cloud | Support: https://support.twelvedata.com | News/changelog: https://twelvedata.com/news Why developers choose Twelve Data: one unified API for all asset classes; WebSocket streaming with ~170 ms average latency; 99.95% uptime SLA (99.99% on Enterprise); 100+ server-side technical indicators; free tier with no credit card; human support on every plan; OpenAPI spec and official SDKs. ## Getting started ### Base URLs | Service | URL | |---|---| | REST API | https://api.twelvedata.com | | WebSocket | wss://ws.twelvedata.com | | Hosted MCP server | https://mcp.twelvedata.com (streamable-http) | | OpenAPI spec | https://api.twelvedata.com/doc/swagger/openapi.json | ### Authentication Sign up free at https://twelvedata.com/register, then get your key at https://twelvedata.com/account/api-keys. Two methods: 1. Query parameter: `GET https://api.twelvedata.com/endpoint?symbol=AAPL&apikey=your_api_key` 2. HTTP header (recommended): `Authorization: apikey your_api_key` A demo key (`apikey=demo`) works for demo requests. Premium endpoints can be tested on lower plans with trial symbols (see https://twelvedata.com/exchanges). ### First request ``` curl "https://api.twelvedata.com/price?symbol=AAPL&apikey=your_api_key" # → {"price": "200.99001"} ``` Python (official SDK, `pip install twelvedata`): ```python from twelvedata import TDClient td = TDClient(apikey="your_api_key") price = td.price(symbol="AAPL").as_json() ts = td.time_series(symbol="AAPL", interval="1day", outputsize=100).as_pandas() ``` JavaScript: ```javascript fetch('https://api.twelvedata.com/time_series?symbol=AAPL&interval=1day&apikey=your_api_key') .then(r => r.json()).then(console.log); ``` ### Conventions - Responses are JSON by default; most endpoints also support `format=CSV`. - Parameter names are case-insensitive; separate multiple values with commas where supported. - Intervals: `1min, 5min, 15min, 30min, 45min, 1h, 2h, 4h, 8h, 1day, 1week, 1month`. - Instruments are identified by `symbol` (e.g. `AAPL`, `EUR/USD`, `BTC/USD`), optionally disambiguated by `exchange`, `mic_code`, or `country`. Alternative identifiers: `figi` (Ultra/Enterprise plans), `isin`/`cusip` (via Data add-ons), `cik` on list endpoints. - Some response fields may be `null` when data is unavailable — expected behavior, not an error; handle defensively. - Cache frequently accessed data; implement retry logic for 429s; never expose your API key client-side. ### Errors Standard error shape: `{"code": 400, "message": "...", "status": "error"}` | Code | Meaning | Resolution | |---|---|---| | 400 | Invalid or incorrect parameter(s) | Check `message`; fix input per docs | | 401 | Invalid API key | Verify key at https://twelvedata.com/account/api-keys | | 403 | Plan lacks access to resource | Upgrade at https://twelvedata.com/pricing | | 404 | Data not found | Loosen overly restrictive parameters | | 414 | Parameter array too long | Shorten per `message` guidance | | 429 | Rate limit reached | Wait or upgrade plan | | 500 | Server error | Retry later; contact support if persistent | ## Plans, credits, and rate limits Machine-readable pricing: https://twelvedata.com/pricing.md Human pages: https://twelvedata.com/pricing (individual), https://twelvedata.com/pricing-business (business) Credit model: most endpoints cost 1 API credit per symbol per request; premium datasets cost more (listed per endpoint below). Rate limits are credits per minute. Only the free Basic plan has a daily cap. ### Individual plans (monthly; annual billing −17%) | Plan | Price | API credits/min | WebSocket credits | Markets | |---|---|---|---|---| | Basic | $0 | 8 (800/day cap) | trial (8 symbols) | US (3) | | Grow | $29–$79 | 55–377 | trial | 20+ | | Pro | $99–$229 | 610–1,597 | 500–1,500 | 70+ | | Ultra | $329–$999 | 2,584–10,946 | 2,500–10,000 | all (84) | ### Business plans | Plan | Price | API credits/min | WebSocket credits | Notes | |---|---|---|---|---| | Basic | $0 | 8 | trial | | | Venture | $149–$499 | 610–2,584 | 500–2,500 | 70+ markets | | Enterprise | $1,099/mo | 10,946 | 10,000 | all markets, 99.99% SLA, Slack Connect | | Enterprise+ | custom | custom | custom | white-labeling, SOC 2/ISO 27001, data residency, 24/7 support | What each tier adds (cumulative): Basic — real-time US equities/ETFs, forex, crypto, reference data, 100+ technical indicators, spreadsheets, batch requests, global trial symbols. Grow — real-time US stocks, EOD global equities/ETFs, commodities, core fundamentals, no daily limit. Pro — real-time European markets, fixed income, mutual fund NAV, full WebSocket, data add-ons. Ultra — all markets, full mutual fund/ETF metrics, analysis (estimates/recommendations/price targets), regulatory holders data, 99.95% SLA, dedicated CSM. Plan-gating shorthand used below: "Grow+" = Grow (individual) / Venture (business) and above; "Pro+" = Pro / Venture and above; "Ultra+" = Ultra / Enterprise and above. Discounts: students 20%, startups 20% (https://twelvedata.com/startups), non-profits free. ## Endpoint reference ### Market data | Endpoint | Description | Key parameters | Credits / plan | |---|---|---|---| | GET /time_series | Historical OHLCV bars for any instrument (stocks, forex, crypto, ETFs, commodities) | `symbol` (req), `interval` (req), `outputsize` (1–5000, default 30), `start_date`/`end_date`, `timezone`, `adjust` (all/splits/dividends/none), `prepost` (Pro+), `order`, `format` | 1/symbol | | GET /time_series/cross | On-the-fly cross rates — any pair, or a stock priced in another currency (e.g. AAPL in INR) | `base` (req), `quote` (req), `interval` (req), `base_type`/`quote_type`, `outputsize`, dates | 5/symbol | | GET /quote | Real-time quote: latest OHLCV, change, average volume, 52-week range, is_market_open | `symbol` (req), `interval`, `eod`, `rolling_period` (crypto), `prepost` (Pro+), `volume_time_period` | 1/symbol | | GET /price | Latest price only — `{"price": "..."}` | `symbol` (req), `prepost`, `dp` | 1/symbol | | GET /eod | End-of-day close with metadata | `symbol` (req), `date`, `prepost`, `dp` | 1/symbol | | GET /market_movers/{market} | Top gainers/losers for stocks, forex, or crypto | `market` (path, req), `direction` (gainers/losers), `outputsize` (1–50), `country`, `price_greater_than` | 100/request; Pro+ | Response shape of /time_series: `meta` (symbol, interval, currency, exchange, mic_code, exchange_timezone, type) + `values[]` (datetime, open, high, low, close, volume) + `status`. ### Reference data | Endpoint | Description | Key parameters | Credits / plan | |---|---|---|---| | GET /stocks | Catalog of all stock symbols | `symbol`, `exchange`, `mic_code`, `country`, `type`, `show_plan`, `include_delisted`, `page`/`outputsize` | 1/request | | GET /forex_pairs | All forex pairs with currency group (Major/Minor/Exotic) | `symbol`, `currency_base`, `currency_quote` | 1/request | | GET /cryptocurrencies | All crypto pairs with available exchanges | `symbol`, `exchange`, `currency_base`, `currency_quote` | 1/request | | GET /etfs | Catalog of all ETF symbols | `symbol`, `exchange`, `country`, `show_plan`, `include_delisted` | 1/request | | GET /funds | Catalog of investment funds | `symbol`, `exchange`, `country`, `show_plan`, `page`, `outputsize` | 1/request | | GET /bonds | Fixed income catalog | `symbol`, `exchange`, `country`, `show_plan`, `page` | 1/request | | GET /commodities | Commodity pairs (precious metals, energy, grains, softs) | `symbol`, `category`, `page` | 1/request | | GET /symbol_search | Search instruments by symbol/name/ISIN/FIGI, relevance-ordered | `symbol` (req), `outputsize` (max 120), `show_plan` | 1/request | | GET /cross_listings | Same security across multiple exchanges | `symbol` (req), `exchange`, `mic_code`, `country` | 40/request; Grow+ | | GET /earliest_timestamp | First available datetime for instrument at interval | `symbol` (req), `interval` (req), `exchange`, `timezone` | 1/request | | GET /exchanges | List of equity exchanges with timezone | `type`, `name`, `code` (MIC), `country`, `show_plan` | 1/request | | GET /exchange_schedule | Trading hours and sessions (incl. pre/post-market) | `date`, `mic_name`, `mic_code`, `country` | 100/request; Ultra+ | | GET /cryptocurrency_exchanges | List of crypto exchanges | — | 1/request | | GET /market_state | Real-time open/closed status, time to open/close per exchange | `exchange`, `code`, `country` | 1/request | | GET /countries | ISO country reference (iso2, iso3, currency, capital) | — | 1/request | | GET /instrument_type | Enum of instrument types (Common Stock, ETF, REIT, Bond, Index…) | — | 1/request | | GET /technical_indicators | Machine-readable metadata for all indicators (params, defaults, outputs) — useful for building UIs | — | 1/request | ### Currencies | Endpoint | Description | Key parameters | Credits / plan | |---|---|---|---| | GET /exchange_rate | Real-time (or historical via `date`) rate for forex/crypto pair | `symbol` (req, e.g. `EUR/USD`), `date`, `timezone`, `dp` | 1/symbol | | GET /currency_conversion | Rate plus converted amount | `symbol` (req), `amount` (req), `date`, `dp` | 1/symbol | ### Fundamentals All fundamentals endpoints accept `symbol`/`figi`/`isin`/`cusip` (at least one required) plus `exchange`, `mic_code`, `country` filters. | Endpoint | Description | Key parameters | Credits / plan | |---|---|---|---| | GET /logo | Company/crypto/forex logo URL | `symbol` (req) | 1/symbol | | GET /profile | Company overview: sector, industry, CEO, employees, description | identifiers | 10/symbol; Grow+ | | GET /statistics | Key stats: valuation (market cap, EV, P/E, PEG), margins, shares outstanding, float, short interest, 52-week, beta | identifiers | 50/symbol; Pro+ | | GET /income_statement | Income statement, annual/quarterly: sales, gross profit, operating income, net income, EPS, EBITDA | identifiers, `period`, dates, `outputsize` | 100/symbol; Pro+ (full history Ultra+) | | GET /income_statement/consolidated | As-reported raw income statement | identifiers, `period` | 100/symbol; Ultra+ | | GET /balance_sheet | Assets, liabilities, shareholders' equity | identifiers, `period`, dates | 100/symbol; Pro+ (full history Ultra+) | | GET /balance_sheet/consolidated | Raw consolidated balance sheet (net debt, working capital, granular line items) | identifiers, `period` | 100/symbol; Ultra+ | | GET /cash_flow | Operating/investing/financing cash flows, free cash flow | identifiers, `period`, dates | 100/symbol; Pro+ (full history Ultra+) | | GET /cash_flow/consolidated | Raw consolidated cash flow statement | identifiers, `period` | 100/symbol; Ultra+ | | GET /dividends | Historical dividend payouts (10y+) | identifiers, `range` (last/next/1m–5y/full), dates, `adjust` | 20/symbol; Grow+ | | GET /dividends_calendar | Dividend events across companies for a date range | `start_date`, `end_date`, `symbol`, `country`, `outputsize` (1–500) | 40/symbol; Grow+ | | GET /splits | Historical stock splits with ratio and factors | identifiers, `range`, dates | 20/symbol; Grow+ | | GET /splits_calendar | Split events for a date range | dates, `outputsize` | 40/symbol; Grow+ | | GET /earnings | Historical EPS: estimate vs actual, surprise % | identifiers, `period`, `outputsize` (1–1000), dates | 20/symbol; Grow+ | | GET /earnings_calendar | Earnings announcement schedule | `start_date`, `end_date`, `exchange`, `country` | 40/request; Grow+ | | GET /ipo_calendar | Past and upcoming IPOs with price ranges | `exchange`, `country`, dates | 40/request; Grow+ | | GET /press_releases | Official company press releases, real-time | identifiers, dates, `language`, `outputsize` (max 10) | 1/request; Basic+ | | GET /key_executives | Leadership: names, titles, age, pay | identifiers | 1000/symbol; Ultra+ | | GET /market_cap | Historical market capitalization series | identifiers, dates, `page` | 5/request; Ultra+ | | GET /last_change/{endpoint} | Last-update timestamp for a fundamentals dataset (efficient change polling) | `endpoint` (path, req), `start_date`, `symbol`, `page` | 1/request | ### ETFs | Endpoint | Description | Credits / plan | |---|---|---| | GET /etfs/list | ETF directory sorted by total assets (full 56,000+ list on Ultra+; 50 records on lower plans) | 1/request | | GET /etfs/world | Full ETF data: summary + performance + risk + composition | 800/request; Ultra+ | | GET /etfs/world/summary | NAV, expense ratio, yield, net assets, YTD return | 200/request; Ultra+ | | GET /etfs/world/performance | Trailing and annual returns vs category | 200/request; Ultra+ | | GET /etfs/world/risk | Alpha, beta, R², Sharpe, Treynor, valuation metrics | 200/request; Ultra+ | | GET /etfs/world/composition | Sectors, country/asset allocation, top holdings, bond breakdown | 200/request; Ultra+ | | GET /etfs/family | ETF families (fund managers) by country | 1/request | | GET /etfs/type | ETF categories by country | 1/request | ### Mutual funds | Endpoint | Description | Credits / plan | |---|---|---| | GET /mutual_funds/list | Fund directory with performance/risk ratings (full 278,000+ list on Ultra+) | 1/request | | GET /mutual_funds/world | Full fund data: summary, performance, risk, ratings, composition, purchase info, sustainability | 1000/request; Ultra+ | | GET /mutual_funds/world/summary | NAV, expense ratio, yield, min investment, fund managers | 200/request; Ultra+ | | GET /mutual_funds/world/performance | Trailing/annual/quarterly/load-adjusted returns with category rank | 200/request; Ultra+ | | GET /mutual_funds/world/risk | Volatility and valuation metrics vs category | 200/request; Ultra+ | | GET /mutual_funds/world/ratings | Performance/risk/return ratings (0–5) | 200/request; Ultra+ | | GET /mutual_funds/world/composition | Sectors, asset allocation, top holdings, bond breakdown | 200/request; Ultra+ | | GET /mutual_funds/world/purchase_info | Minimums, pricing, brokerage availability | 200/request; Ultra+ | | GET /mutual_funds/world/sustainability | ESG score and pillars | 200/request; Ultra+ | | GET /mutual_funds/family | Fund families by country | 1/request | | GET /mutual_funds/type | Fund types by country | 1/request | ### Analysis (all Ultra+) | Endpoint | Description | Credits | |---|---|---| | GET /earnings_estimate | Analyst EPS projections per quarter/year (avg/low/high, analyst count) | 20/symbol | | GET /revenue_estimate | Analyst revenue projections with sales growth | 20/symbol | | GET /eps_trend | EPS estimate progression (current vs 7/30/60/90 days ago) | 20/symbol | | GET /eps_revisions | Analyst EPS revisions up/down, last week/month | 20/symbol | | GET /growth_estimates | Consensus growth: current/next quarter and year, 5-year p.a. | 20/symbol | | GET /recommendations | Buy/hold/sell trend counts and 0–10 rating | 100/symbol | | GET /price_target | Analyst price targets: high/median/low/average vs current | 75/symbol | | GET /analyst_ratings/light | Ratings snapshot: firm, rating change, current/prior | 75/symbol | | GET /analyst_ratings/us_equities | Detailed US ratings with analyst names and price targets | 200/symbol | ### Regulatory | Endpoint | Description | Credits / plan | |---|---|---| | GET /edgar_filings/archive | SEC EDGAR filings, real-time and historical, with file URLs | 50/request; Ultra+ | | GET /insider_transactions | Insider trades: name, position, shares, value | 200/symbol; Pro+ | | GET /institutional_holders | Institutional ownership with percent held | 1500/symbol; Ultra+ | | GET /fund_holders | Mutual fund ownership of a stock | 1500/symbol; Ultra+ | | GET /direct_holders | Direct/registry holders (incl. Tadawul, beta) | 1500/symbol; Ultra+ | | GET /tax_info | Tax indicators (US 1446(f), FTTs, stamp duties) | 50/symbol; Ultra+ | | GET /sanctions/{source} | Sanctioned entities by authority: `ofac`, `uk`, `eu`, `au` | 50/request; Ultra+ | ### Advanced | Endpoint | Description | Notes | |---|---|---| | POST /batch | Bundle multiple API requests in one call; per-request error isolation | Body: map of id → `{"url": "/endpoint?params"}`; credits = sum of parts | | GET /api_usage | Programmatic usage/quota: current and daily usage vs plan limits | 1/request | ## Technical indicators (100+) Every indicator is its own GET endpoint: `https://api.twelvedata.com/{indicator}?symbol=AAPL&interval=1day&apikey=...`. Common parameters mirror /time_series (`symbol`, `interval` required; `outputsize`, dates, `timezone`, `format`, plus indicator-specific ones like `time_period`, `series_type`, `fast_period`/`slow_period`/`signal_period`). Cost: 1 credit per symbol. Response: `meta` + `values[]` (datetime + named indicator fields). The `/technical_indicators` endpoint returns machine-readable metadata for all of them. Available on all plans, including free. Overlap studies: bbands, dema, ema, ht_trendline, ichimoku, kama, keltner, ma, mama, mcginley_dynamic, midpoint, midprice, pivot_points_hl, sar, sarext, sma, t3ma, tema, trima, vwap, wma Momentum: adx, adxr, apo, aroon, aroonosc, bop, cci, cmo, coppock, crsi, dpo, dx, kst, macd, macd_slope, macdext, mfi, minus_di, minus_dm, mom, percent_b, plus_di, plus_dm, ppo, roc, rocp, rocr, rocr100, rsi, stoch, stochf, stochrsi, ultosc, willr Volume: ad, adosc, obv, rvol Volatility: atr, natr, supertrend, supertrend_heikinashicandles, trange Price transform: add, avg, avgprice, ceil, div, exp, floor, heikinashicandles, hlc3, ln, log10, medprice, mult, sqrt, sub, sum, typprice, wclprice Cycle (Hilbert transform): ht_dcperiod, ht_dcphase, ht_phasor, ht_sine, ht_trendmode Statistics: beta, correl, linearreg, linearregangle, linearregintercept, linearregslope, max, maxindex, min, minindex, minmax, minmaxindex, stddev, tsf, var Example: `GET /rsi?symbol=AAPL&interval=1day&time_period=14&apikey=...` → `values[]` of `{datetime, rsi}`. ## WebSocket (real-time streaming) Docs: https://twelvedata.com/docs/llms/websocket/ws-overview.md and https://twelvedata.com/docs/llms/websocket/ws-real-time-price.md - URL: `wss://ws.twelvedata.com/v1/quotes/price?apikey=your_api_key` (or `X-TD-APIKEY` header) - Average latency ~170 ms; mix asset classes (stocks, forex, crypto) in one connection - Limits: up to 3 concurrent connections; max 100 client events per connection; client message ≤ 1 MB - Cost: 1 WebSocket credit per subscribed symbol (separate from API credits) - Plans: full access Pro+ / Venture+; Basic and Grow get trial access (1 connection, 8 trial symbols) - Playground: https://twelvedata.com/account/websocket Subscribe: ```json {"action": "subscribe", "params": {"symbols": "AAPL,EUR/USD,BTC/USD,RY:TSX"}} ``` Extended form for ambiguous symbols: `params.symbols` as array of `{"symbol": "EUR/USD", "type": "Forex"}` (or with `exchange`/`mic_code`). Other actions: `unsubscribe` (same shape), `reset` (clear all), `heartbeat` (send every ~10 s to keep connection stable). Server events: `subscribe-status` (with `success[]`/`fails[]`) and `price` events: `{"event":"price","symbol":"AAPL","currency":"USD","exchange":"NASDAQ","type":"Common Stock","timestamp":1735689600,"price":200.99,"day_volume":12345678}` (`bid`/`ask` where available). ## SDKs, integrations, and AI tooling - Python (official): https://github.com/twelvedata/twelvedata-python — `pip install twelvedata`; JSON/pandas output, batch, WebSocket - R (official): https://github.com/twelvedata/twelvedata-r-sdk - OpenAPI spec for codegen: https://api.twelvedata.com/doc/swagger/openapi.json - Community libraries: C# (TwelveDataSharp), JavaScript, PHP, Go, TypeScript — see https://github.com/search?q=twelvedata - Excel add-in: https://twelvedata.com/excel — cross-platform task pane + advanced Windows add-in with charts and indicators - Google Sheets add-on: https://twelvedata.com/google-sheets — codeless real-time/historical data with auto-refresh - MCP server: hosted at https://mcp.twelvedata.com (streamable-http transport); open source at https://github.com/twelvedata/mcp; connects any MCP-compatible AI assistant (Claude, etc.) to quotes, time series, and instrument data. Docs: https://twelvedata.com/docs/llms/ai/mcp-server.md - AI Data Assistant (custom GPT): https://chatgpt.com/g/g-683060e30a408191b01c9b82bb84db07-twelve-data-assistant — natural-language market data queries. Docs: https://twelvedata.com/docs/llms/ai/integrations/chatgpt.md - WebSocket tools: https://github.com/twelvedata/ws-tools ## Coverage - Asset classes: stocks (190,000+ symbols incl. delisted), forex (140 currencies, 1,300+ pairs), crypto (180+ exchanges incl. Binance, Coinbase, Kraken), ETFs (56,000+), mutual funds (278,000+), bonds, commodities (30+), indices (5,000+) - 250+ exchanges, 90+ countries; full exchange list with delay status, trading hours, and minimum plan: https://twelvedata.com/exchanges - US stocks real-time on the free plan; European real-time (incl. Cboe Europe) on Pro+ or via data add-ons - Historical depth: EOD back to earliest known records; 20+ years of forex history on free plans; intraday archives; corporate actions (splits/dividends) adjustments built in - Scale: 700M+ API requests served daily, peaking at 1M+ requests/min ## Common recipes 1. Latest price: `GET /price?symbol=AAPL` 2. Daily candles, 1 year: `GET /time_series?symbol=AAPL&interval=1day&outputsize=252` 3. FX conversion: `GET /currency_conversion?symbol=USD/JPY&amount=100` 4. Crypto quote with 24h rolling change: `GET /quote?symbol=BTC/USD&rolling_period=24` 5. RSI signal: `GET /rsi?symbol=EUR/USD&interval=1h&time_period=14` 6. Find a symbol: `GET /symbol_search?symbol=apple` 7. Is the market open: `GET /market_state?code=XNAS` 8. Earnings this week: `GET /earnings_calendar?start_date=2026-06-08&end_date=2026-06-12` 9. Company fundamentals: `GET /income_statement?symbol=AAPL&period=annual` 10. Check remaining quota: `GET /api_usage` Append `&apikey=your_api_key` to each, or send the Authorization header. ## Key links - Register (free): https://twelvedata.com/register - API keys dashboard: https://twelvedata.com/account/api-keys - Docs: https://twelvedata.com/docs — LLM index: https://twelvedata.com/docs/llms.txt - Pricing: https://twelvedata.com/pricing — machine-readable: https://twelvedata.com/pricing.md - Exchanges and coverage: https://twelvedata.com/exchanges - Support: https://support.twelvedata.com — Contact: https://twelvedata.com/contact - Status: https://twelvedata.isitup.cloud - GitHub: https://github.com/twelvedata