NAV Navbar

Getting Started

Welcome to the Twelve Data! You can use this API to access world financial markets including stocks, forex, ETFs, indices, and cryptocurrencies. Most of the exchanges are available in real-time, while others have some delays. Over 20+ years of end-of-day data and a couple of years for intraday historical data.

If you are unfamiliar with APIs and requests, check this tutorial on how to make requests as part of the How-to tutorials.

code & output ${examples} can be found in this section

AuthenticationImportant

Twelve Data authenticates users by valid API keys for both API and WebSocket. It can be specified in two ways:

A demo API key is used for sample requests to familiarize yourself with the API format. Complete access to API is available with your API key, which can be obtained for free by signing up for the Basic plan. Specific endpoints are available starting only from Grow, Pro, or Enterprise plans. However, they all can be tested as trial symbols across all markets. API will return an error if the key is invalid or has insufficient permissions.

Endpoints

API endpoints are prefixed with https://api.twelvedata.com
WebSocket endpoints are prefixed with wss://ws.twelvedata.com

ParametersUseful

How to separate

Parameters are ampersand(&) separated.
E.g. ?symbol=AAPL&interval=5min&outputsize=200

Casting

Word casing doesn‘t matter when passing parameters.
E.g. ?symbol=AAPL, ?symbol=AaPl, or ?symbol=aapl will all correctly work.

Exchanges

Symbol might be also passed in the form symbol:exchange_name.
E.g. ?symbol=RY:TSX, ?symbol=AAPL:NASDAQ

CSV

When the format parameter is set to CSV, additional filename parameter might be used to specify the custom name of the output file. E.g. ?format=CSV&filename=my_own_csv_name

Dates

To get the most use of start_date, end_date, and outputsize parameters when accessing historical data, refer to this tutorial.

Batch RequestsUseful

Batch requests might be used on top of most endpoints including technical indicators. It allows requesting multiple symbols simultaneously.

HTTP request example

https://api.twelvedata.com/time_series?symbol=AAPL,EUR/USD,ETH/BTC:Huobi,TRP:TSX&interval=1min&apikey=your_api_key

This request will return JSON with the following structure

{
   "AAPL": {
      "meta": {
         "symbol": "AAPL",
         "interval": "1min",
         "currency": "USD",
         "exchange_timezone": "America/New_York",
         "exchange": "NASDAQ",
         "type": "Common Stock"
      },
      "values": [
         {
            "datetime": "2020-02-26 15:59:00",
            "open": "292.89001",
            "high": "293.10001",
            "low": "292.50000",
            "close": "292.64999",
            "volume": "385977"
         },
         {...}
      ],
      "status": "ok"
   },
   "EUR/USD": {
      {...}
   },
   "ETH/BTC:Huobi": {
      {...}
   }, 
   "TRP:TSX": {
      {...}
   }
}

Request

Basic call

All symbols should be comma delimited and provided in symbol parameter. E.g:
/time_series?symbol=AAPL,QQQ,EUR/USD,QBNK

Exchange specific call

In order to call symbol from the specific exchange, use symbol_ticker:exchange format. E.g:
/bbands?symbol=ETH/BTC:Huobi,TRP:TSX,INFY:BSE

General

All instruments might be called in an arbitrary order and mixes, such as stocks, forex, crypto, ETFs and indices.
Request count will be incremented according to the number of passed symbols.
Batch requests only support JSON format.
Limited to 120 symbols per request.

Response

The response consists of the main object where the key is the symbol passed and value is the normal object consisting of meta, values, status.
The response header will also include is_batch set to true if the request is batch with multiple returns symbols.

Error handling

In the case that there was an error during processing one of the symbols, the error will only be returned for that specific symbol without affecting other instrument responses.

JSON request example

https://api.twelvedata.com/time_series?symbol=AAPL,EUR/USD,QBNK&interval=1min&apikey=demo

https://api.twelvedata.com/time_series?symbol=ETH/BTC:Huobi,TRP:TSX,INFY:BSE&interval=30min&outputsize=12&apikey=demo

Errors

Twelve Data API uses a unified error response scheme. Consisting of a JSON object with code, message and status keys.

HTTP request example

https://api.twelvedata.com/time_series?symbol=AAPL&interval=0.99min&apikey=your_api_key

This request with incorrect interval set will return JSON with the following structure

{
  "code": 400,
  "message": "Invalid **interval** provided: 0.99min. Supported intervals: 1min, 5min, 15min, 30min, 45min, 1h, 2h, 4h, 8h, 1day, 1week, 1month",
  "status": "error"
}

Possible output error codes are:

Error Code Status Meaning
400 Bad Request There is an error with one or multiple parameters.
401 Unauthorized Your API key is wrong or not valid.
403 Forbidden Your API key is valid but has no permissions to make request available on the upper plans.
404 Not Found The specified data can not be found.
414 Parameter Too Long The parameter which accepts multiple values is out of range.
429 Too Many Requests You've reached your API request limits.
500 Internal Server Error There is an error on the server-side. Try again later.

How to overcome the errors:

Roadmap

We continuously make Twelve Data the only place where all users can obtain the necessary financial data. If you have any questions or ideas about improvement, contact us.

LibrariesUseful

Here, we publish libraries created to get the most of Twelve Data. We work towards making the industry the best SDKs for the most popular languages. Large releases are coming soon. A full list can be found on GitHub.

Official libraries and Add-ins

Language URL
Python twelvedata-python
R twelvedata-r-sdk
Excel Excel Add-in
Google Sheets Google Sheets Add-on

Third-party libraries

Language URL
C# TwelveDataSharp
JavaScript twelvedata
PHP twelvedata
Go twelvedata

The same list can also be accessed at the Support Center.

Support

Please refer to the Help Center for general assistance. If your question has not been answered yet drop a message to us.

Reference Data

Reference Data returns general data that can be used to enhance your project generalization.

Stocks List

This API call returns an array of symbols available at Twelve Data API. This list is updated daily.

HTTP request example

https://api.twelvedata.com/stocks

This request will return JSON with the following structure

[
  {
    "symbol": "AAPL",
    "name": "Apple Inc",
    "currency": "USD",
    "exchange": "NASDAQ",
    "mic_code": "XNGS",
    "country": "United States",
    "type": "Common Stock",
    "figi_code": "BBG000B9Y5X2"
  },
  {
    "symbol": "AAT",
    "name": "American Assets Trust Inc",
    "currency": "USD",
    "exchange": "NYSE",
    "mic_code": "XNYS",
    "country": "United States",
    "type": "Real Estate Investment Trust (REIT)",
    "figi_code": "BBG00161BCW4"
  },
  {...}
]

// with &show_plan=true
{
  "data": [
    {
      "symbol": "TCS",
      "name": "Tata Consultancy Services Limited",
      "currency": "INR",
      "exchange": "NSE",
      "mic_code": "XNSE",
      "country": "India",
      "type": "Common Stock",
      "figi_code": "BBG000Q0WGC6",
      "access": {
        "global": "Level A",
        "plan": "Grow"
      }
    },
    {
      "symbol": "TCS",
      "name": "Axon Enterprise Inc",
      "currency": "EUR",
      "exchange": "FSX",
      "mic_code": "XFRA",
      "country": "Germany",
      "type": "Common Stock",
      "figi_code": "BBG000FB37K7",
      "access": {
        "global": "Level A",
        "plan": "Grow"
      }
    },
    {...}
  ],
  "status": "ok"
}

HTTP route

/stocks

API credits

1 per request

API parameters

Parameter Details
symbol • Parameter is optional
• Filter by symbol
figi • Parameter is optional
• Filter by financial instrument global identifier (FIGI)
exchange • Parameter is optional
• Filter by exchange name or mic code
mic_code • Parameter is optional
• Filter by market identifier code (MIC) under ISO 10383 standard
country • Parameter is optional
• Filter by country name or alpha code
type • Parameter is optional
• Filter by instrument type
format • Parameter is optional
• Value can be JSON or CSV; Default JSON
delimiter • Parameter is optional
• Specify the delimiter used when downloading the CSV file
• Default semicolon ;
show_plan • Parameter is optional
• Adds info on which plan symbol is available
• Boolean; Default false
include_delisted • Parameter is optional
• Include delisted identifiers
• Boolean; Default false

Response

Key Description
symbol instrument symbol (ticker)
name full name of instrument
currency currency of the instrument according to the ISO 4217 standard
exchange exchange where instrument is traded
mic_code market identifier code (MIC) under ISO 10383 standard
country country where exchange is located
type common issue type
figi_code financial instrument global identifier (FIGI)

JSON request example

https://api.twelvedata.com/stocks

https://api.twelvedata.com/stocks?symbol=AAPL

Downloadable CSV example

https://api.twelvedata.com/stocks?format=CSV

Forex Pairs List

This API call return array of forex pairs available at Twelve Data API. This list is daily updated.

HTTP request example

https://api.twelvedata.com/forex_pairs

This request will return JSON with the following structure

[
  {
    "symbol": "EUR/USD",
    "currency_group": "Major",
    "currency_base": "Euro",
    "currency_quote": "US Dollar"
  },
  {
    "symbol": "XAU/USD",
    "currency_group": "Exotic",
    "currency_base": "Gold Spot",
    "currency_quote": "US Dollar"
  },
  {...}
]

HTTP route

/forex_pairs

API credits

1 per request

API parameters

Parameter Details
symbol • Parameter is optional
• Filter by symbol
currency_base • Parameter is optional
• Filter by currency base
currency_quote • Parameter is optional
• Filter by currency quote
format • Parameter is optional
• Value can be CSV or JSON; Default JSON
delimiter • Parameter is optional
• Specify the delimiter used when downloading the CSV file
• Default semicolon ;

Response

Key Description
symbol currency pair according to ISO 4217 standard codes with slash(/) delimiter
currency_group group to which currency pair belongs to, could be: Major, Minor, Exotic and Exotic-Cross
currency_base base currency name according to ISO 4217 standard
currency_quote quote currency name according to ISO 4217 standard

JSON request example

https://api.twelvedata.com/forex_pairs

https://api.twelvedata.com/forex_pairs?symbol=EUR/USD

Downloadable CSV example

https://api.twelvedata.com/forex_pairs?format=CSV

Cryptocurrencies List

This API call return array of cryptocurrency pairs available at Twelve Data API. This list is daily updated.

HTTP request example

https://api.twelvedata.com/cryptocurrencies

This request will return JSON with the following structure

[
  {
    "symbol": "BTC/USD",
    "available_exchanges": ["ABCC", "Allcoin", "BTC-Alpha", "BTCTurk", "Bibox", "BigONE", "Binance", "Bit-Z", "BitForex", "BitMEX", "BitMart", "BitMax", "BitStamp", "Bitex.la", "Bitfinex", "Bitibu", "Bitinka", "Bitlish", "Bitrue", "Bittrex", "Btcwinex", "C2CX", "CBX", "CEX.IO", "COINEGG", "Cobinhood", "CoinAll", "CoinField", "CoinHub", "CoinTiger", "Coinbase Pro", "Coinbene", "CoinsBank", "Coinsbit", "CryptalDash", "DragonEX", "EXX", "Exmo", "Exrates", "GDAX", "Gate.io", "Gemini", "HitBTC", "Huobi", "IDAX", "IDCM", "Independent Reserve", "Kraken", "Kryptono", "Kucoin", "LBank", "LakeBTC", "Livecoin", "OKCoin", "OKEx", "OOOBTC", "Panxora", "Poloniex", "QUOINE", "SIMEX", "Tidex", "Upbit", "YoBit", "ZB.COM", "bitFlyer", "itBit", "n.exchange", "p2pb2b", "xBTCe"],
    "currency_base": "Bitcoin",
    "currency_quote": "US Dollar"
  },
  {
    "symbol": "ETH/BTC",
    "available_exchanges": ["ABCC", "Allcoin", "BTC Indonesia", "BTC Markets", "BTC-Alpha", "BXThailand", "Bibox", "BigONE", "Bilaxy", "Binance", "Bit-Z", "BitBay", "BitForex", "BitMart", "BitStamp", "Bitbank", "Bitci.com", "BiteBTC", "Bitfinex", "Bitibu", "Bitlish", "Bittrex", "Btcwinex", "CBX", "CEX.IO", "COINEGG", "Cobinhood", "CoinAll", "CoinExchange", "CoinMex", "CoinTiger", "Coinbase Pro", "Coinbene", "Coinsbit", "EXX", "Exmo", "Exrates", "Fatbtc", "GDAX", "GOPAX", "Gate.io", "Gemini", "HitBTC", "Hotbit", "Huobi", "IDAX", "IDCM", "Kraken", "Kryptono", "Kucoin", "LBank", "LakeBTC", "Livecoin", "OKEx", "Panxora", "Poloniex", "QUOINE", "SIMEX", "STEX", "TOKOK", "Tidex", "Upbit", "Vebitcoin", "YoBit", "ZB.COM", "Zaif", "bitFlyer", "p2pb2b", "xBTCe"],
    "currency_base": "Ethereum",
    "currency_quote": "Bitcoin"
  },
  {...}
]

HTTP route

/cryptocurrencies

API credits

1 per request

API parameters

Parameter Details
symbol • Parameter is optional
• Filter by symbol
exchange • Parameter is optional
• Filter by exchange name
currency_base • Parameter is optional
• Filter by currency base
currency_quote • Parameter is optional
• Filter by currency quote
format • Parameter is optional
• Value can be CSV or JSON; Default JSON
delimiter • Parameter is optional
• Specify the delimiter used when downloading the CSV file
• Default semicolon ;

Response

Key Description
symbol cryptocurrency pair codes with slash(/) delimiter
available_exchanges array of exchanges where cryptocurrency is traded
currency_base base cryptocurrency name
currency_quote quote cryptocurrency name

JSON request example

https://api.twelvedata.com/cryptocurrencies

https://api.twelvedata.com/cryptocurrencies?symbol=BTC/USD

Downloadable CSV example

https://api.twelvedata.com/cryptocurrencies?format=CSV

Funds List

This API call return array of funds available at Twelve Data API. This list is daily updated.

HTTP request example

https://api.twelvedata.com/funds

This request will return JSON with the following structure

{
  "result": {
    "count": 84799,
    "list": [
        {
            "symbol": "DIVI",
            "name": "AdvisorShares Athena High Dividend ETF",
            "country": "United States",
            "currency": "USD",
            "exchange": "NYSE",
            "type": "ETF",
            "figi_code": "BBG00161BCW4"
        },
        {
            "symbol": "GBTC",
            "name": "Grayscale Bitcoin Trust (BTC)",
            "country": "United States",
            "currency": "USD",
            "exchange": "NYSE",
            "type": "ETF",
            "figi_code": "BBG00D0YL155"
        }
        {...}
    ],
  },
  "status": "ok"
}

// with &show_plan=true
{
  "result": {
    "count": 84799,
    "list": [
      {
        "symbol": "DIVI",
        "name": "AdvisorShares Athena High Dividend ETF",
        "country": "United States",
        "currency": "USD",
        "exchange": "NYSE",
        "type": "ETF",
        "figi_code": "BBG00161BCW4"
        "access": {
          "global": "Level A",
          "plan": "Grow"
        }
      },
      {
        "symbol": "GBTC",
        "name": "Grayscale Bitcoin Trust (BTC)",
        "country": "United States",
        "currency": "USD",
        "exchange": "NYSE",
        "type": "ETF",
        "figi_code": "BBG00D0YL155"
        "access": {
          "global": "Level A",
          "plan": "Grow"
        }
      },
      {...}
    ]
  },
  "status": "ok"
}

HTTP route

/funds

API credits

1 per request

API parameters

Parameter Details
symbol • Parameter is optional
• Filter by symbol
figi • Parameter is optional
• Filter by financial instrument global identifier (FIGI)
exchange • Parameter is optional
• Filter by exchange name or mic code
country • Parameter is optional
• Filter by country name or alpha code
type • The asset class to which the instrument belongs
• Supports American Depositary Receipt, Bond, Bond Fund, Closed-end Fund, Common Stock, Depositary Receipt, Digital Currency, ETF, Exchange-Traded Note, Global Depositary Receipt, Index, Limited Partnership, Mutual Fund, Physical Currency, Preferred Stock, REIT, Right, Structured Product, Trust, Unit, and Warrant
format • Parameter is optional
• Value can be CSV or JSON; Default JSON
delimiter • Parameter is optional
• Specify the delimiter used when downloading the CSV file
• Default semicolon ;
show_plan • Parameter is optional
• Adds info on which plan symbol is available
• Boolean; Default false
include_delisted • Parameter is optional
• Include delisted identifiers
• Boolean; Default false
page • Parameter is optional
• Page number; default 1
outputsize • Parameter is optional
• Number of records in response; default 5000

Response

Key Description
count total number of matching instruments
symbol instrument symbol (ticker)
name full name of instrument
country country where the index is located
currency currency in which instrument is traded by ISO 4217 standard
exchange exchange where instrument is traded
type group to which instrument belongs to
figi_code financial instrument global identifier (FIGI)

JSON request example

https://api.twelvedata.com/funds

https://api.twelvedata.com/funds?symbol=0P00000AMH

Downloadable CSV example

https://api.twelvedata.com/funds?format=CSV

Bonds List

This API call return array of bonds available at Twelve Data API. This list is daily updated.

HTTP request example

https://api.twelvedata.com/bonds

This request will return JSON with the following structure

{
  "result": {
    "count": 84799,
    "list": [
      {
        "symbol": "0P00000AMG",
        "name": "Morgan Stanley Investment Funds - Sustainable Asia Equity Fund B",
        "country": "United States",
        "currency": "USD",
        "exchange": "OTC",
        "type": "Mutual Fund"
      },
      {
        "symbol": "0P00000AMH",
        "name": "Morgan Stanley Investment Funds - Sustainable Emerging Markets Equity Fund B",
        "country": "United States",
        "currency": "USD",
        "exchange": "OTC",
        "type": "Mutual Fund"
      },
      {...}
    ],
    "status": "ok"
  }
}

// with &show_plan=true
{
  "result": {
    "count": 100,
    "list": [
      {
        "symbol": "AJXA",
        "name": "Great Ajax Corp",
        "country": "United States",
        "currency": "USD",
        "exchange": "NYSE",
        "type": "Exchange-Traded Note",
        "access": {
          "global": "Basic",
          "plan": "Basic"
        }
      },
      {
        "symbol": "AMJL",
        "name": "X-Links Monthly Pay 2xLeveraged Alerian MLP Index ETN",
        "country": "United States",
        "currency": "USD",
        "exchange": "NYSE",
        "type": "Exchange-Traded Note",
        "access": {
          "global": "Basic",
          "plan": "Basic"
        }
      },
      {...}
    ]
  },
  "status": "ok"
}

HTTP route

/bonds

API credits

1 per request

API parameters

Parameter Details
symbol • Parameter is optional
• Filter by symbol
exchange • Parameter is optional
• Filter by exchange name or mic code
country • Parameter is optional
• Filter by country name or alpha code
type • The asset class to which the instrument belongs
• Supports American Depositary Receipt, Bond, Bond Fund, Closed-end Fund, Common Stock, Depositary Receipt, Digital Currency, ETF, Exchange-Traded Note, Global Depositary Receipt, Index, Limited Partnership, Mutual Fund, Physical Currency, Preferred Stock, REIT, Right, Structured Product, Trust, Unit, and Warrant
format • Parameter is optional
• Value can be CSV or JSON; Default JSON
delimiter • Parameter is optional
• Specify the delimiter used when downloading the CSV file
• Default semicolon ;
show_plan • Parameter is optional
• Adds info on which plan symbol is available
• Boolean; Default false
include_delisted • Parameter is optional
• Include delisted identifiers
• Boolean; Default false
page • Parameter is optional
• Page number; default 1
outputsize • Parameter is optional
• Number of records in response; default 5000

Response

Key Description
count total number of matching instruments
symbol instrument symbol (ticker)
name full name of instrument
country country where the index is located
currency currency in which instrument is traded by ISO 4217 standard
exchange exchange where instrument is traded
type group to which instrument belongs to

JSON request example

https://api.twelvedata.com/bonds

https://api.twelvedata.com/bonds?symbol=AJXA

Downloadable CSV example

https://api.twelvedata.com/bonds?format=CSV

ETFs List

This API call return array of ETFs available at Twelve Data API. This list is daily updated.

HTTP request example

https://api.twelvedata.com/etfs

This request will return JSON with the following structure

[
  {
    "symbol": "SPY",
    "name": "SPDR S&P 500 ETF Trust",
    "currency": "USD",
    "exchange": "NYSE",
    "mic_code": "XNYS",
    "country": "United States",
    "figi_code": "BBG000BDTF76"
  },
  {
    "symbol": "VTI",
    "name": "Vanguard Total Stock Market Index Fund ETF Shares",
    "currency": "USD",
    "exchange": "NYSE",
    "mic_code": "XNYS",
    "country": "Unites States",
    "figi_code": "BBG000HRBDF4"
  },
  {...}
]

// with &show_plan=true
{
  "data": [
    {
      "symbol": "SPY",
      "name": "SPDR S&P 500 ETF Trust",
      "currency": "MXN",
      "exchange": "BMV",
      "mic_code": "XMEX",
      "country": "Mexico",
      "figi_code": ""
      "access": {
        "global": "Level B",
        "plan": "Pro"
      }
    },
    {
      "symbol": "SPY",
      "name": "SPDR S&P 500 ETF Trust",
      "currency": "USD",
      "exchange": "NYSE",
      "mic_code": "XNYS",
      "country": "United States",
      "figi_code": "BBG000BDTF76",
      "access": {
        "global": "Basic",
        "plan": "Basic"
      }
    },
    {...}
  ],
  "status": "ok"
}

HTTP route

/etfs

API credits

1 per request

API parameters

Parameter Details
symbol • Parameter is optional
• Filter by symbol
figi • Parameter is optional
• Filter by financial instrument global identifier (FIGI)
exchange • Parameter is optional
• Filter by exchange name or mic code
mic_code • Parameter is optional
• Filter by market identifier code (MIC) under ISO 10383 standard
country • Parameter is optional
• Filter by country name or alpha code
format • Parameter is optional
• Value can be CSV or JSON; Default JSON
delimiter • Parameter is optional
• Specify the delimiter used when downloading the CSV file
• Default semicolon ;
show_plan • Parameter is optional
• Adds info on which plan symbol is available
• Boolean; Default false
include_delisted • Parameter is optional
• Include delisted identifiers
• Boolean; Default false

Response

Key Description
symbol instrument symbol (ticker)
name full name of instrument
currency currency in which instrument is traded by ISO 4217 standard
exchange exchange where ETF is traded
mic_code market identifier code (MIC) under ISO 10383 standard
figi_code financial instrument global identifier (FIGI)

JSON request example

https://api.twelvedata.com/etfs

https://api.twelvedata.com/etfs?symbol=QQQ

Downloadable CSV example

https://api.twelvedata.com/etfs?format=CSV

Indices List

This API call return array of indices available at Twelve Data API. This list is daily updated.

HTTP request example

https://api.twelvedata.com/indices

This request will return JSON with the following structure

[
  {
    "symbol": "QBNK",
    "name": "QE Banks and Financial Services",
    "country": "Qatar",
    "currency": "QAR"
    "exchange": "QE",
    "mic_code": "DSMD",
  },
  {
    "symbol": "HSI",
    "name": "HANG SENG INDEX",
    "country": "Hong Kong",
    "currency": "HKD"
    "exchange": "HKEX",
    "mic_code": "XHKG",
  },
  {...}
]

// with &show_plan=true
{
  "data": [
    {
      "symbol": "STI",
      "name": "STI Index",
      "country": "Singapore",
      "currency": "SGD",
      "exchange": "SGX",
      "mic_code": "XSES",
      "access": {
        "global": "Level B",
        "plan": "Pro"
      }
    }
  ],
  "status": "ok"
}

HTTP route

/indices

API credits

1 per request

API parameters

Parameter Details
symbol • Parameter is optional
• Filter by symbol
figi • Parameter is optional
• Filter by financial instrument global identifier (FIGI)
exchange • Parameter is optional
• Filter by exchange name or mic code
mic_code • Parameter is optional
• Filter by market identifier code (MIC) under ISO 10383 standard
country • Parameter is optional
• Filter by country name or alpha code
format • Parameter is optional
• Value can be CSV or JSON; Default JSON
delimiter • Parameter is optional
• Specify the delimiter used when downloading the CSV file
• Default semicolon ;
show_plan • Parameter is optional
• Adds info on which plan symbol is available
• Boolean; Default false
include_delisted • Parameter is optional
• Include delisted identifiers
• Boolean; Default false

Response

Key Description
symbol instrument symbol (ticker)
name full name of instrument
country country where the index is located
currency currency in which instrument is traded by ISO 4217 standard
exchange exchange where instrument is traded
mic_code market identifier code (MIC) under ISO 10383 standard

JSON request example

https://api.twelvedata.com/indices

https://api.twelvedata.com/indices?symbol=QBNK

Downloadable CSV example

https://api.twelvedata.com/indices?format=CSV

Commodities List

This API call return array of commodity pairs available at Twelve Data API. This list is daily updated.

HTTP request example

https://api.twelvedata.com/commodities

This request will return JSON with the following structure

[
    {
        "symbol": "XAG/AUD",
        "name": "Silver Spot",
        "category": "Precious Metal",
        "description": ""
    },
    {
        "symbol": "XAG/CAD",
        "name": "Silver Spot",
        "category": "Precious Metal",
        "description": ""
    },
    {...}
]

HTTP route

/commodities

API credits

1 per request

API parameters

Parameter Details
symbol • Parameter is optional
• Filter by symbol
category • Parameter is optional
• Filter by category of commodity
format • Parameter is optional
• Value can be CSV or JSON; Default JSON
delimiter • Parameter is optional
• Specify the delimiter used when downloading the CSV file
• Default semicolon ;

Response

Key Description
symbol currency pair according to ISO 4217 standard codes with slash(/) delimiter
name full name of the instrument
category category of commodity
description short description of the commodity

JSON request example

https://api.twelvedata.com/commodities

https://api.twelvedata.com/commodities?symbol=XAU/USD

Downloadable CSV example

https://api.twelvedata.com/commodities?format=CSV

Cross listings

This API call return array of cross listed symbols. This list is daily updated.

HTTP request example

https://api.twelvedata.com/cross_listings?symbol=NVDA&mic_code=XNGS&apikey=your_api_key

This request will return JSON with the following structure

{
    "result": {
        "count": 7,
        "list": [
            {
                "symbol": "NVDA",
                "name": "NVIDIA Corp",
                "exchange": "NASDAQ",
                "mic_code": "XNGS",
            },
            {
                "symbol": "0R1I",
                "name": "NVIDIA Corp",
                "exchange": "LSE",
                "mic_code": "XLON",
            }
        ]
    }
}

HTTP route

/cross_listings

API credits

40 per request

API parameters

Parameter Details
symbol ticker symbol of instrument
exchange • Parameter is optional
• exchange where instrument is traded
mic_code • Parameter is optional
• market identifier code (MIC) under ISO 10383 standard
country • Parameter is optional
• country to which stock exchange belongs to

Response

Key Description
symbol ticker symbol of instrument
name name of exchange
exchange exchange where instrument is traded
mic_code market identifier code (MIC) under ISO 10383 standard

JSON request example

https://api.twelvedata.com/cross_listings?symbol=NVDA&mic_code=XNGS&apikey=your_api_key

ExchangesHigh Demand

This API call return array of stock, ETF or index exchanges available at Twelve Data API. This list is daily updated.

HTTP request example

https://api.twelvedata.com/exchanges

This request will return JSON with the following structure

[
  {
    "name": "NASDAQ",
    "code": "XNGS",
    "country": "United States",
    "timezone": "America/New_York"
  },
  {
    "name": "NYSE",
    "code": "XNYS",
    "country": "United States",
    "timezone": "America/New_York"
  },
  {
    "name": "SGX",
    "code": "XSES",
    "country": "Singapore",
    "timezone": "Asia/Singapore"
    },
  {...}
]

// with &show_plan=true
{
  "data": [
    {
      "name": "SSE",
      "code": "XSHG",
      "country": "China",
      "timezone": "Asia/Shanghai",
      "access": {
        "global": "Level B",
        "plan": "Pro"
      }
    },
    {
      "name": "SZSE",
      "code": "XSHE",
      "country": "China",
      "timezone": "Asia/Shanghai",
      "access": {
        "global": "Level B",
        "plan": "Pro"
      }
    }
  ],
  "status": "ok"
}

HTTP route

/exchanges

API credits

1 per request

API parameters

Parameter Details
type • The asset class to which the instrument belongs
• Supports American Depositary Receipt, Bond, Bond Fund, Closed-end Fund, Common Stock, Depositary Receipt, Digital Currency, ETF, Exchange-Traded Note, Global Depositary Receipt, Index, Limited Partnership, Mutual Fund, Physical Currency, Preferred Stock, REIT, Right, Structured Product, Trust, Unit, and Warrant
name • Parameter is optional
• Filter by exchange name
code • Parameter is optional
• Filter by market identifier code (MIC) under ISO 10383 standard
country • Parameter is optional
• Filter by country name or alpha code
format • Parameter is optional
• Value can be CSV or JSON; Default JSON
delimiter • Parameter is optional
• Specify the delimiter used when downloading the CSV file
• Default semicolon ;
show_plan • Parameter is optional
• Adds info on which plan symbol is available
• Boolean; Default false

Response

Key Description
name name of exchange
code market identifier code (MIC) under ISO 10383 standard
country country to which stock exchange belongs to
timezone time zone where exchange is located

JSON request example

https://api.twelvedata.com/exchanges

https://api.twelvedata.com/exchanges?type=etf

Downloadable CSV example

https://api.twelvedata.com/exchanges?format=CSV

Exchange schedule

This API call return exchanges details and trading hours.

HTTP request example

https://api.twelvedata.com/exchange_schedule?apikey=your_api_key

This request will return JSON with the following structure

{
    "data": [
        {
          "title": "NASDAQ/NGS (Global Select Market)",
          "name": "NASDAQ",
          "code": "XNYS",
          "country": "United states",
          "time_zone": "America/New_York",
          "sessions": [
            {"open_time": "04:00:00", "close_time": "09:30:00", "session_name": "Pre market", "session_type": "pre"},
            {"open_time": "09:30:00", "close_time": "16:00:00", "session_name": "Market", "session_type": "quotes"},
            {"open_time": "16:00:00", "close_time": "20:00:00", "session_name": "Post market", "session_type": "post"}
          ]
        },
        {...}
    ]
}

HTTP route

/exchange_schedule

API credits

100 per request

API parameters

Parameter Details
date • Parameter is optional
• If present, return schedule for the selected date, else - common schedule. Could be the exact date, e.g. 2021-10-27, or in human language today or yesterday.
mic_name • Parameter is optional
• Filter by exchange name
mic_code • Parameter is optional
• Filter by market identifier code (MIC) under ISO 10383 standard
country • Parameter is optional
• Filter by country name or alpha code

Response

Key Description
title official name of exchange
name name of exchange
code market identifier code (MIC) under ISO 10383 standard
country country to which stock exchange belongs to
timezone time zone where exchange is located
sessions exchange trading hours

JSON request example

https://api.twelvedata.com/exchange_schedule?apikey=your_api_key

https://api.twelvedata.com/exchange_schedule?date=today&apikey=your_api_key

Cryptocurrency Exchanges

This API call return array of cryptocurrency exchanges available at Twelve Data API. This list is daily updated.

HTTP request example

https://api.twelvedata.com/cryptocurrency_exchanges

This request will return JSON with the following structure

[
  {
    "name": "Binance",
  },
  {
    "name": "Upbit",
  },
  {
    "name": "Huobi",
  },
  {
    "name": "Bittrex",
  },
  {
    "name": "Bithumb",
  },
  {...}
]

HTTP route

/cryptocurrency_exchanges

API credits

1 per request

API parameters

Parameter Details
format • Parameter is optional
• Value can be CSV or JSON; Default JSON
delimiter • Parameter is optional
• Specify the delimiter used when downloading the CSV file
• Default semicolon ;

Response

Key Description
name name of cryptocurrency exchange

JSON request example

https://api.twelvedata.com/cryptocurrency_exchanges

Downloadable CSV example

https://api.twelvedata.com/cryptocurrency_exchanges?format=CSV

Market State

Check the state of all available exchanges, time to open, and time to close.

Returns all available stock exchanges by default

HTTP request example

https://api.twelvedata.com/market_state?apikey=your_api_key

This request will return JSON with the following structure

[
  {
    "name": "NYSE",
    "code": "XNYS",
    "country": "United States",
    "is_market_open": true,
    "time_after_open": "02:39:03",
    "time_to_open": "00:00:00",
    "time_to_close": "05:20:57"
  },
  {
    "name": "NYSE",
    "code": "XASE",
    "country": "United States",
    "is_market_open": true,
    "time_after_open": "02:39:03",
    "time_to_open": "00:00:00",
    "time_to_close": "05:20:57"
  },
  {
    "name": "NYSE",
    "code": "ARCX",
    "country": "United States",
    "is_market_open": true,
    "time_after_open": "02:39:03",
    "time_to_open": "00:00:00",
    "time_to_close": "05:20:57"
  },
  {
    "name": "NASDAQ",
    "code": "XNGS",
    "country": "United States",
    "is_market_open": true,
    "time_after_open": "02:39:03",
    "time_to_open": "00:00:00",
    "time_to_close": "05:20:57"
  },
  {
    "name": "NASDAQ",
    "code": "XNMS",
    "country": "United States",
    "is_market_open": true,
    "time_after_open": "02:39:03",
    "time_to_open": "00:00:00",
    "time_to_close": "05:20:57"
  },
  {...}
]

HTTP route

/market_state

API credits

1 per request

API parameters

Key Type Description
exchange string • Parameter is optional
• Takes exchange name or alpha code
code string • Parameter is optional
• Takes MIC code of exchange
country string • Parameter is optional
• Takes country name or alpha code
apikey string • Required parameter
• Your API key, which you can obtain for free here

Response

Key Description
name the full name of exchange
code Market Identifier Codes (MIC) under ISO 10383 standard
country country where exchange is located
is_market_open true if market is open; false if closed
time_after_open time after market opening HH:MM:SS format; if currently closed - returns 00:00:00
time_to_open time to market opening in HH:MM:SS format; if currently open - returns 00:00:00
time_to_close time to market closing in HH:MM:SS format; if currently closed - returns 00:00:00

JSON request example

https://api.twelvedata.com/market_state?exchange=NYSE&apikey=demo

https://api.twelvedata.com/market_state?exchange=XMAD&apikey=demo

https://api.twelvedata.com/market_state?country=India&apikey=demo

Instrument Type

Returns a list of instrument types

HTTP request example

https://api.twelvedata.com/instrument_type?apikey=your_api_key

This request will return JSON with the following structure

{
    "result": [
        "Agricultural Product",
        "American Depositary Receipt",
        "Bond",
        "Bond Fund",
        "Closed-end Fund",
        "Common Stock",
        "Depositary Receipt",
        "Digital Currency",
        "Energy Resource",
        "ETF",
        "Exchange-Traded Note",
        "Global Depositary Receipt",
        "Index",
        "Industrial Metal",
        "Limited Partnership",
        "Livestock",
        "Mutual Fund",
        "Physical Currency",
        "Precious Metal",
        "Preferred Stock",
        "REIT",
        "Right",
        "Structured Product",
        "Trust",
        "Unit",
        "Warrant"
    ],
    "status": "ok"
}

HTTP route

/instrument_type

API credits

1 per request

JSON request example

https://api.twelvedata.com/instrument_type?apikey=your_api_key

Countries

Returns a list of countries

HTTP request example

https://api.twelvedata.com/countries?apikey=your_api_key

This request will return JSON with the following structure

{
  "data": [
    {
      "iso2": "AF",
      "iso3": "AFG",
      "numeric": 4,
      "name": "Afghanistan",
      "official_name": "The Islamic Republic of Afghanistan",
      "capital": "Kabul",
      "currency": "AFN"
    },
    {
      "iso2": "AX",
      "iso3": "ALA",
      "numeric": 248,
      "name": "Åland Islands",
      "official_name": "Åland",
      "capital": "Mariehamn",
      "currency": "EUR"
    },
    {
      "iso2": "AL",
      "iso3": "ALB",
      "numeric": 8,
      "name": "Albania",
      "official_name": "The Republic of Albania",
      "capital": "Tirana",
      "currency": "ALL"
    }
  ]
}

HTTP route

/countries

API credits

1 per request

Response

Key Description
iso2 two-letter country code defined in ISO 3166
iso3 three-letter country code defined in ISO 3166
numeric numeric country code defined in ISO 3166
name the full name of country
official_name official name of country
capital capital of country
currency currency of country

JSON request example

https://api.twelvedata.com/countries?apikey=your_api_key

Technical Indicators Interface

This API call return array of objects with available technical indicators. This endpoint might be used to build an abstract interface to make more convenient API calls from the application.

HTTP request example

https://api.twelvedata.com/technical_indicators

This request will return JSON with the following structure

[
  {
    "macd": {
      "enable": true,
      "full_name": "Moving Average Convergence Divergence",
      "description": "Moving Average Convergence Divergence(MACD) is a trend following momentum indicator, which works by subtracting the longer moving average from the shorter one. MACD has an unstable period ~ 100.",
      "type": "Momentum Indicators",
      "overlay": false,
      "parameters": {
        "series_type": {
          "default": "close",
          "range": ["open", "high", "low", "close"],
          "type": "string"
        },
        "fast_period": {
          "default": 12,
          "min_range": 1,
          "type": "int"
        },
        "slow_period": {
          "default": 26,
          "min_range": 1,
          "type": "int"
        },
        "signal_period": {
          "default": 9,
          "min_range": 1,
          "type": "int"
        }
      },
      "output_values": {
        "macd": {
          "default_color": "#2708A0",
          "display": "line"
        },
        "macd_signal": {
          "default_color": "#B80C09",
          "display": "line"
        },
        "macd_hist": {
          "default_color": "#B80C09",
          "display": "histogram"
        }
      }
    }
  },
  {...}
]

HTTP route

/technical_indicators

API credits

1 per request

API parameters

no input parameters

Response

Key Description
enable if the indicator is tested, approved and is recommended for use returns true, otherwise returns false
full_name full indicator name
description brief description of the indicator
type group to which indicator belongs to
overlay if indicator should be plotted over price bars returns true, otherwise returns false
parameters an array of input parameters where each object might contain:
default: specifies parameter value set by default
range: an array of available parameter values
min_range: if the parameter has lower bound in order to ensure correct calculation
max_range: if the parameter has upper bound in order to ensure correct calculation
type: type of parameter might be string, int, float or array
output_values an array of output values where each object might contain:
default_color: suggested color for displaying returns hex color code
display: how output value should be rendered, might be line, histogram, candle or points
min_range: if output value has minimum bound
max_range: if output value has maximum bound
tinting an array of tinting values used for proper indicator coloring
display: render pattern
color: returns hex color code
transparency: transparency level returns float value from 0 to 1 level
lower_bound: lower bound of tinting might be either number or one of the return parameters
upper_bound: upper bound of tinting might be either number or one of the return parameters

JSON request example

https://api.twelvedata.com/technical_indicators

Earliest Timestamp

This method returns the first available DateTime for a given instrument at the specific interval.

HTTP request example

https://api.twelvedata.com/earliest_timestamp?symbol=AAPL&interval=1day&apikey=your_api_key

This request will return JSON with the following structure

{
  "datetime": "1980-12-12",
  "unix_time": 345427200
}

HTTP route

/earliest_timestamp

API credits

1 per request

API parameters

Key Type Description
symbol string • Required parameter
• Symbol ticker of the instrument
E.g. AAPL, EUR/USD, ETH/BTC, ...
figi string • Parameter is optional
• Filter by financial instrument global identifier (FIGI)
interval string • Required parameter
• Interval between two consecutive points in time series
• Supports: 1min, 5min, 15min, 30min, 45min, 1h, 2h, 4h, 1day, 1week, 1month
exchange string • Parameter is optional
• Exchange where instrument is traded
mic_code string • Parameter is optional
• Market Identifier Code (MIC) under ISO 10383 standard
apikey string • Required parameter
• Your API key, which you can obtain for free here

Response

Key Description
datetime earliest datetime, the format depends on interval
unix_time datetime converted to UNIX timestamp

JSON request example

https://api.twelvedata.com/earliest_timestamp?symbol=AAPL&interval=1day&apikey=demo

https://api.twelvedata.com/earliest_timestamp?symbol=AAPL,MSFT&interval=1day&apikey=demo

https://api.twelvedata.com/earliest_timestamp?symbol=EUR/USD&interval=1min&apikey=demo

This method helps to find the best matching symbol. It can be used as the base for custom lookups. The response is returned in descending order, with the most relevant instrument at the beginning.

HTTP request example

https://api.twelvedata.com/symbol_search?symbol=AA

This request will return JSON with the following structure

{
  "data": [
    {
      "symbol": "AA",
      "instrument_name": "Alcoa Corp",
      "exchange": "NYSE",
      "mic_code": "XNYS",
      "exchange_timezone": "America/New_York",
      "instrument_type": "Common Stock",
      "country": "United States",
      "currency": "USD"
    },
    {
      "symbol": "AAA",
      "instrument_name": "BetaShares Australian High Interest Cash ETF",
      "exchange": "ASX",
      "mic_code": "XASX",
      "exchange_timezone": "Australia/Sydney",
      "instrument_type": "ETF",
      "country": "Australia",
      "currency": "AUD"
    },
    {...}
  ],
  "status": "ok"
}

// with &show_plan=true
{
  "data": [
    {
      "symbol": "AA",
      "instrument_name": "Alcoa Corp",
      "exchange": "NYSE",
      "mic_code": "XNYS",
      "exchange_timezone": "America/New_York",
      "instrument_type": "Common Stock",
      "country": "United States",
      "currency": "USD",
      "access": {
        "global": "Basic",
        "plan": "Basic"
      }
    },
    {
      "symbol": "AAA",
      "instrument_name": "Listed Funds Trust - AAF First Priority CLO Bond ETF",
      "exchange": "NYSE",
      "mic_code": "XNYS",
      "exchange_timezone": "America/New_York",
      "instrument_type": "ETF",
      "country": "United States",
      "currency": "USD",
      "access": {
        "global": "Basic",
        "plan": "Basic"
      }
    },
    {...}
  ],
  "status": "ok"
}

HTTP route

/symbol_search

API credits

1 per request

API parameters

Parameter Details
symbol • Required parameter
• Symbol to search
figi • Parameter is optional
• Filter by financial instrument global identifier (FIGI)
outputsize • Parameter is optional
• Number of matches in response
• Default 30, Max 120;
show_plan • Parameter is optional
• Adds info on which plan symbol is available
• Boolean; Default false

Response

Key Description
symbol ticker symbol of instrument
instrument_name name of exchange
exchange exchange where instrument is traded
mic_code market identifier code (MIC) under ISO 10383 standard
exchange_timezone time zone where exchange is located
instrument_type type of instrument
country country to which stock exchange belongs to

JSON request example

https://api.twelvedata.com/symbol_search?symbol=AA

https://api.twelvedata.com/symbol_search?symbol=XAU/

https://api.twelvedata.com/symbol_search?symbol=RY&show_plan=true

Core Data

Core data return time series, quotes, rates, and other prices across equities, forex, cryptocurrencies, ETFs, indices along with other data types.

Time SeriesHigh Demand

This API call returns meta and time series for the requested instrument. Metaobject consists of general information about the requested symbol. Time series is the array of objects ordered by time descending with Open, High, Low, Close prices. Non-currency instruments also include volume information.

HTTP request example

https://api.twelvedata.com/time_series?symbol=AAPL&interval=1min&apikey=your_api_key

This request will return JSON with the following structure

{
  "meta": {
    "symbol": "AAPL",
    "interval": "1min",
    "currency": "USD",
    "exchange_timezone": "America/New_York",
    "exchange": "NASDAQ",
    "mic_code": "XNAS",
    "type": "Common Stock"
  },
  "values": [
    {
      "datetime": "2021-09-16 15:59:00",
      "open": "148.73500",
      "high": "148.86000",
      "low": "148.73000",
      "close": "148.85001",
      "volume": "624277"
    },
    {
      "datetime": "2021-09-16 15:58:00",
      "open": "148.72000",
      "high": "148.78000",
      "low": "148.70000",
      "close": "148.74001",
      "volume": "274622"
    },
    {
      "datetime": "2021-09-16 15:57:00",
      "open": "148.77499",
      "high": "148.79500",
      "low": "148.71001",
      "close": "148.72501",
      "volume": "254725"
    },
    {
      "datetime": "2021-09-16 15:56:00",
      "open": "148.76500",
      "high": "148.78999",
      "low": "148.72000",
      "close": "148.78000",
      "volume": "230758"
    },
    {
      "datetime": "2021-09-16 15:55:00",
      "open": "148.80000",
      "high": "148.80000",
      "low": "148.70000",
      "close": "148.76230",
      "volume": "348577"
    }
  ],
  "status": "ok"
}

HTTP route

/time_series

API credits

1 per symbol

API parameters

Key Type Description
symbol string • Required parameter
• Symbol ticker of the instrument
E.g. AAPL, EUR/USD, ETH/BTC, ...
figi string • Parameter is optional
• Filter by financial instrument global identifier (FIGI)
interval string • Required parameter
• Interval between two consecutive points in time series
• Supports: 1min, 5min, 15min, 30min, 45min, 1h, 2h, 4h, 1day, 1week, 1month
exchange string • Parameter is optional
• Exchange where instrument is traded
mic_code string • Parameter is optional
• Market Identifier Code (MIC) under ISO 10383 standard
country string • Parameter is optional
• Country where instrument is traded
type string • Parameter is optional
• The asset class to which the instrument belongs
• Supports American Depositary Receipt, Bond, Bond Fund, Closed-end Fund, Common Stock, Depositary Receipt, Digital Currency, ETF, Exchange-Traded Note, Global Depositary Receipt, Index, Limited Partnership, Mutual Fund, Physical Currency, Preferred Stock, REIT, Right, Structured Product, Trust, Unit, and Warrant
outputsize number • Parameter is optional
• Number of data points to retrieve
• Supports values in the range from 1 to 5000
• Default 30 when no date parameters are set, otherwise set to maximum
format string • Parameter is optional
• Value can be JSON or CSV
• Default JSON
delimiter string • Parameter is optional
• Specify the delimiter used when downloading the CSV file
• Default semicolon ;
apikey string • Required parameter
• Your API key, which you can obtain for free here
prepost string • Parameter is optional. Only for Pro and above plans.
• Available at the 1min, 5min, 15min, and 30min intervals for all US equities.
• Open, high, low, close values are supplied without volume.
• Default false

Response

Key Description
meta json object with request general information
datetime datetime at local exchange time referring to when the bar with specified interval was opened
open price at the opening of current bar
high highest price which occurred during the current bar
low lowest price which occurred during the current bar
close close price at the end of the bar
volume trading volume which occurred during the current bar

JSON request example

https://api.twelvedata.com/time_series?symbol=AAPL&interval=1min&apikey=demo

https://api.twelvedata.com/time_series?symbol=EUR/USD&interval=1day&outputsize=12&apikey=demo

Downloadable CSV example

https://api.twelvedata.com/time_series?symbol=BTC/USD&interval=5min&format=CSV&apikey=demo

Exchange Rate

This API call returns real-time exchange rate for currency pair. Works with forex and cryptocurrency.

HTTP request example

https://api.twelvedata.com/exchange_rate?symbol=USD/JPY&apikey=your_api_key

This request will return JSON with the following structure

{
   "symbol": "USD/JPY",
   "rate": 105.12,
   "timestamp": 1602714051
}

HTTP route

/exchange_rate

API credits

1 per symbol

API parameters

Key Type Description
symbol string • Required parameter
• The currency pair you want to request can be either forex or cryptocurrency
• Slash(/) delimiter is used
E.g. EUR/USD or BTC/ETH will be correct
date string • Parameter is optional
• If not null, will use exchange rate from a specific date or time
• Format 2006-01-02 or 2006-01-02 15:04:05
format string • Parameter is optional
• Value can be JSON or CSV
• Default JSON
delimiter string • Parameter is optional
• Specify the delimiter used when downloading the CSV file
• Default semicolon ;
apikey string • Required parameter
• Your API key, which you can obtain for free here

Response

Key Description
symbol requested currency symbol
rate real-time exchange rate for the corresponding symbol
timestamp unix timestamp of the rate

JSON request example

https://api.twelvedata.com/exchange_rate?symbol=USD/JPY&apikey=demo

https://api.twelvedata.com/exchange_rate?symbol=USD/JPY&date=2022-02-22&apikey=demo

Downloadable CSV example

https://api.twelvedata.com/exchange_rate?symbol=EUR/USD&format=CSV&apikey=demo

Currency ConversionUseful

This API call returns real-time exchange rate and converted amount for currency pair. Works with forex and cryptocurrency.

HTTP request example

https://api.twelvedata.com/currency_conversion?symbol=USD/JPY&amount=122&apikey=your_api_key

This request will return JSON with the following structure

{
   "symbol": "USD/JPY",
   "rate": 105.12,
   "amount": 12824.64,
   "timestamp": 1602714051
}

HTTP route

/currency_conversion

API credits

1 per symbol

API parameters

Key Type Description
symbol string • Required parameter
• The currency pair you want to request can be either forex or cryptocurrency
• Slash(/) delimiter is used
E.g. EUR/USD or BTC/ETH will be correct
amount number • Required parameter
• Amount of base currency to be converted into quote currency.
• Supports values in the range from 0 and above
date string • Parameter is optional
• If not null, will use exchange rate from a specific date or time
• Format 2006-01-02 or 2006-01-02 15:04:05
format string • Parameter is optional
• Value can be JSON or CSV
• Default JSON
delimiter string • Parameter is optional
• Specify the delimiter used when downloading the CSV file
• Default semicolon ;
apikey string • Required parameter
• Your API key, which you can obtain for free here

Response

Key Description
symbol requested currency symbol
rate real-time exchange rate for the corresponding symbol
amount amount of converted currency
timestamp unix timestamp of the rate

JSON request example

https://api.twelvedata.com/currency_conversion?symbol=USD/JPY&amount=122&apikey=demo

https://api.twelvedata.com/currency_conversion?symbol=USD/JPY&amount=122&date=2022-02-22&apikey=demo

Downloadable CSV example

https://api.twelvedata.com/currency_conversion?symbol=EUR/USD&amount=15&format=CSV&apikey=demo

QuoteHigh Demand

Quote endpoint is an efficient method to retrieve the latest quote of the selected instrument.

HTTP request example

https://api.twelvedata.com/quote?symbol=AAPL&apikey=your_api_key

This request will return JSON with the following structure

{
  "symbol": "AAPL",
  "name": "Apple Inc",
  "exchange": "NASDAQ",
  "mic_code": "XNAS",
  "currency": "USD",
  "datetime": "2021-09-16",
  "timestamp": 1631772000,
  "open": "148.44000",
  "high": "148.96840",
  "low": "147.22099",
  "close": "148.85001",
  "volume": "67903927",
  "previous_close": "149.09000",
  "change": "-0.23999",
  "percent_change": "-0.16097",
  "average_volume": "83571571",
  "rolling_1d_change": "123.123",
  "rolling_7d_change": "123.123",
  "rolling_period_change": "123.123"
  "is_market_open": false,
  "fifty_two_week": {
    "low": "103.10000",
    "high": "157.25999",
    "low_change": "45.75001",
    "high_change": "-8.40999",
    "low_change_percent": "44.37440",
    "high_change_percent": "-5.34782",
    "range": "103.099998 - 157.259995"
  },
  "extended_change": "0.09",
  "extended_percent_change": "0.05",
  "extended_price": "125.22",
  "extended_timestamp": 1649845281
}

HTTP route

/quote

API credits

1 per symbol

API parameters

Key Type Description
symbol string • Required parameter
• Symbol ticker of the instrument
E.g. AAPL, EUR/USD, ETH/BTC, ...
figi string • Parameter is optional
• Filter by financial instrument global identifier (FIGI)
interval string • Optional parameter
• Interval of the quote
• Supports: 1min, 5min, 15min, 30min, 45min, 1h, 2h, 4h, 1day, 1week, 1month; Default 1day
exchange string • Parameter is optional
• Exchange where instrument is traded
mic_code string • Parameter is optional
• Market Identifier Code (MIC) under ISO 10383 standard
country string • Parameter is optional
• Country where instrument is traded
volume_time_period string • Optional parameter
• Number of periods for Average Volume
• Default 9
type string • Parameter is optional
• The asset class to which the instrument belongs
• Supports American Depositary Receipt, Bond, Bond Fund, Closed-end Fund, Common Stock, Depositary Receipt, Digital Currency, ETF, Exchange-Traded Note, Global Depositary Receipt, Index, Limited Partnership, Mutual Fund, Physical Currency, Preferred Stock, REIT, Right, Structured Product, Trust, Unit, and Warrant
format string • Parameter is optional
• Value can be JSON or CSV
• Default JSON
delimiter string • Parameter is optional
• Specify the delimiter used when downloading the CSV file
• Default semicolon ;
apikey string • Required parameter
• Your API key, which you can obtain for free here
prepost string • Parameter is optional. Only for Pro and above plans.
• Available at the 1min, 5min, 15min, and 30min intervals for all US equities.
• Open, high, low, close values are supplied without volume.
• Default false
eod string • Optional parameter
• If true, then return data for closed day
rolling_period string • Optional parameter
• Number of hours for calculate rolling change at period. By default set to 24, it can be in range [1, 168].

Response

Key Description
symbol symbol passed
name name of the instrument
exchange exchange where instrument is traded
mic_code market identifier code (MIC) under ISO 10383 standard
currency currency in which the equity is denominated
timestamp unix timestamp of the last price
datetime datetime in defined timezone referring to when the bar with specified interval was opened
open price at the opening of current bar
high highest price which occurred during the current bar
low lowest price which occurred during the current bar
close close price at the end of the bar
volume trading volume during the bar
previous_close close price at the end of the previous bar
change close - previous_close
percent_change (close - previous_close) / previous_close * 100
average_volume average volume of the specified period
rolling_1d_change percent change in price between the current and the backward one, where period is 1 day, available for crypto
rolling_7d_change percent change in price between the current and the backward one, where period is 7 days, available for crypto
rolling_period_change percent change in price between the current and the backward one, where period specified in request param rolling_period, available for crypto
is_market_open true if market is open; false if closed
fifty_two_week collection of 52-week metrics
extended_change diff between the regular close price and the latest extended price
extended_percent_change percent change in price between the regular close price and the latest extended price
extended_price latest extended price
extended_timestamp unix timestamp of the last extended price

JSON request example

https://api.twelvedata.com/quote?symbol=AAPL&apikey=demo

https://api.twelvedata.com/quote?symbol=EUR/USD&interval=30min&apikey=demo

Downloadable CSV example

https://api.twelvedata.com/quote?symbol=QBNK&type=Index&interval=5min&format=CSV&apikey=demo

Real-Time PriceHigh Demand

This endpoint is a lightweight method that allows retrieving only the real-time price of the selected instrument.

HTTP request example

https://api.twelvedata.com/price?symbol=AAPL&apikey=your_api_key

This request will return JSON with the following structure

{
    "price": "200.99001"
}

HTTP route

/price

API credits

1 per symbol

API parameters

Key Type Description
symbol string • Required parameter
• Symbol ticker of the instrument
E.g. AAPL, EUR/USD, ETH/BTC, ...
figi string • Parameter is optional
• Filter by financial instrument global identifier (FIGI)
exchange string • Parameter is optional
• Exchange where instrument is traded
mic_code string • Parameter is optional
• Market Identifier Code (MIC) under ISO 10383 standard
country string • Parameter is optional
• Country where instrument is traded
type string • Parameter is optional
• The asset class to which the instrument belongs
• Supports American Depositary Receipt, Bond, Bond Fund, Closed-end Fund, Common Stock, Depositary Receipt, Digital Currency, ETF, Exchange-Traded Note, Global Depositary Receipt, Index, Limited Partnership, Mutual Fund, Physical Currency, Preferred Stock, REIT, Right, Structured Product, Trust, Unit, and Warrant
format string • Parameter is optional
• Value can be JSON or CSV
• Default JSON
delimiter string • Parameter is optional
• Specify the delimiter used when downloading the CSV file
• Default semicolon ;
apikey string • Required parameter
• Your API key, which you can obtain for free here
prepost string • Parameter is optional. Only for Pro and above plans.
• Available at the 1min, 5min, 15min, and 30min intervals for all US equities.
• Open, high, low, close values are supplied without volume.
• Default false
dp string • Parameter is optional
• Specifies the number of decimal places for floating values
• Should be in range [0,11] inclusive; default 5

Response

Key Description
price real-time or the latest available price

JSON request example

https://api.twelvedata.com/price?symbol=AAPL&apikey=demo

https://api.twelvedata.com/price?symbol=TRP&country=Canada&apikey=demo

Downloadable CSV example

https://api.twelvedata.com/price?symbol=USD/JPY&format=CSV&apikey=demo

End of Day Price

This endpoint returns the latest End of Day (EOD) price of an instrument.

HTTP request example

https://api.twelvedata.com/eod?symbol=AAPL&apikey=your_api_key

This request will return JSON with the following structure

{
  "symbol": "AAPL",
  "exchange": "NASDAQ",
  "mic_code": "XNAS",
  "currency": "USD",
  "datetime": "2021-09-16",
  "close": "148.79"
}

HTTP route

/eod

API credits

1 per symbol

API parameters

Key Type Description
symbol string • Required parameter
• Symbol ticker of the instrument
E.g. AAPL, EUR/USD, ETH/BTC, ...
figi string • Parameter is optional
• Filter by financial instrument global identifier (FIGI)
exchange string • Parameter is optional
• Exchange where instrument is traded
mic_code string • Parameter is optional
• Market Identifier Code (MIC) under ISO 10383 standard
country string • Parameter is optional
• Country where instrument is traded
type string • Parameter is optional
• The asset class to which the instrument belongs
• Supports American Depositary Receipt, Bond, Bond Fund, Closed-end Fund, Common Stock, Depositary Receipt, Digital Currency, ETF, Exchange-Traded Note, Global Depositary Receipt, Index, Limited Partnership, Mutual Fund, Physical Currency, Preferred Stock, REIT, Right, Structured Product, Trust, Unit, and Warrant
date string • Parameter is optional
• If not null, then return data from a specific date
• Format 2006-01-02
apikey string • Required parameter
• Your API key, which you can obtain for free here
prepost string • Parameter is optional. Only for Pro and above plans.
• Available at the 1min, 5min, 15min, and 30min intervals for all US equities.
• Open, high, low, close values are supplied without volume.
• Default false
dp string • Parameter is optional
• Specifies the number of decimal places for floating values
• Should be in range [0,11] inclusive; default 5

Response

Key Description
symbol symbol passed
exchange exchange where instrument is traded
mic_code market identifier code (MIC) under ISO 10383 standard
currency currency in which instrument is denominated
datetime datetime in defined timezone referring to when the bar with specified interval was opened
close the most recent end of day close price

JSON request example

https://api.twelvedata.com/eod?symbol=AAPL&apikey=demo

https://api.twelvedata.com/eod?symbol=TRP&country=Canada&apikey=demo

Market Movers

Get the list of the top gaining or losing stocks today.

Top gainers are ordered by the highest rate of price increase since the previous day''s close. Top losers are ordered by the highest percentage of price decrease since the last day.

Data is available for all international equities, forex, crypto.

HTTP request example

https://api.twelvedata.com/market_movers/stocks?apikey=your_api_key

This request will return JSON with the following structure

{
  "values": [
    {
      "symbol": "BSET",
      "name": "Bassett Furniture Industries Inc",
      "exchange": "NASDAQ",
      "mic_code": "XNAS",
      "datetime": "2022-01-31 09:34:00",
      "last": 17.25,
      "high": 17.35,
      "low": 15.90999,
      "volume": 108297,
      "change": 3.31,
      "percent_change": 23.74462
    },
    {
      "symbol": "TWKS",
      "name": "Thoughtworks Holding, Inc.",
      "exchange": "NASDAQ",
      "mic_code": "XNAS",
      "datetime": "2022-01-31 09:34:40",
      "last": 20.09,
      "high": 19.62999,
      "low": 18.29999,
      "volume": 392376,
      "change": 3.98,
      "percent_change": 20.84861
    },
    {
      "symbol": "RMED",
      "name": "RA Medical Systems Inc",
      "exchange": "NYSE",
      "mic_code": "XNAS",
      "datetime": "2022-01-31 09:33:50",
      "last": 0.984,
      "high": 0.98519,
      "low": 0.984,
      "volume": 4480,
      "change": 0.159,
      "percent_change": 17.84511
    }
  ],
  "status": "ok"
}

HTTP routes

/market_movers/stocks
/market_movers/etf
/market_movers/mutual_funds
/market_movers/forex
/market_movers/crypto

API credits

100 per request

API parameters

Key Type Description
direction string • Parameter is optional
• Specifies direction of the snapshot gainers or losers
• By default gainers
outputsize string • Parameter is optional
• Specifies the size of the snapshot
• Can be in a range from 1 to 50; default 30
country string • Parameter is optional
• Country of the snapshot, applicable to non-currencies only
• Takes country name or alpha code; default USA
price_greater_than string Parameter is optional
• Takes values with price grater than specified value
apikey string • Required parameter
• Your API key, which you can obtain for free here
dp string • Parameter is optional
• Specifies the number of decimal places for floating values
• Should be in range [0,11] inclusive; default 5

Response

Key Description
symbol the exchange symbol ticker
name the official name of the instrument
exchange exchange where instrument is traded
mic_code market identifier code (MIC) under ISO 10383 standard
datetime the last updated datetime timestamp
last the latest available price for the symbol today
high the highest price for the symbol today
low the lowest price for the symbol today
volume the trading volume of the symbol today
change the value of the change since the previous day
percent_change the percentage change since the previous day

JSON request example

https://api.twelvedata.com/market_movers/stocks?country=india&outputsize=20&apikey=demo

https://api.twelvedata.com/market_movers/forex?direction=losers&apikey=demo

Mutual Funds

MFs ListUseful

This API request returns a list of mutual funds available at Twelve Data. Sorting is in descending order by total assets value. The list is updated daily.

HTTP request example

https://api.twelvedata.com/mutual_funds/list?apikey=your_api_key

This request will return JSON with the following structure

{
  "result": {
    "count": 1000,
    "list": [
      {
        "symbol": "VFIAX",
        "name": "Vanguard 500 Index Admiral",
        "country": "United States",
        "fund_family": "Vanguard",
        "fund_type": "Large Blend",
        "performance_rating": 5,
        "risk_rating": 4,
        "exchange": "NASDAQ",
        "mic_code": "XNAS"
      },
      {
        "symbol": "0P00016LWW",
        "name": "RBC Select Balanced Portfolio O",
        "country": "Canada",
        "fund_family": "RBC Global Asset Management Inc.",
        "fund_type": "Global Neutral Balanced",
        "performance_rating": 3,
        "risk_rating": 3,
        "exchange": "TSX",
        "mic_code": "XTSE"
      },
      {
        "symbol": "0P00005WT4",
        "name": "Kotak Savings Fund Monthly Dividend Payout",
        "country": "India",
        "fund_family": "Kotak Mahindra Asset Management Co Ltd",
        "fund_type": "Ultrashort Bond",
        "performance_rating": 3,
        "risk_rating": 3,
        "exchange": "BSE",
        "mic_code": "XBOM"
      },
      {...}
    ]
  },
  "status": "ok"
}

HTTP route

/mutual_funds/list

API credits

1 per request

API parameters

Parameter Details
symbol • Parameter is optional
• Filter by symbol
figi • Parameter is optional
• Filter by financial instrument global identifier (FIGI)
country • Parameter is optional
• Filter by country name or alpha code
fund_family • Parameter is optional
• Filter by investment company that manages the fund
fund_type • Parameter is optional
• Filter by the type of fund
performance_rating • Parameter is optional
• Filter by performance rating from 0 to 5
risk_rating • Parameter is optional
• Filter by risk rating from 0 to 5
page • Parameter is optional
• Page number; default 1
outputsize • Parameter is optional
• Number of records in response; default 100
apikey • Required parameter
• Your API key at the Basic plan or above

Response

Key Description
count total number of matching funds
symbol fund symbol ticker
name fund name
country country of fund incorporation
fund_family investment company that manages the fund
fund_type type of fund
performance_rating performance rating from 0 to 5
risk_rating risk rating from 0 to 5
exchange exchange name where the fund is listed
mic_code market identifier code (MIC) under ISO 10383 standard

JSON request example

https://api.twelvedata.com/mutual_funds/list?apikey=demo

https://api.twelvedata.com/mutual_funds/list?fund_family=Vanguard&apikey=demo

Downloadable CSV example

https://api.twelvedata.com/mutual_funds/list?format=CSV&apikey=demo

MFs Family List

This API request returns a list of mutual funds families.

HTTP request example

https://api.twelvedata.com/mutual_funds/family?apikey=your_api_key

This request will return JSON with the following structure

{
  "result": {
    "India": [
      "Aberdeen Standard Fund Managers Limited",
      "Aditya Birla Sun Life AMC Ltd",
      "Aditya Birla Sun Life Insurance Company Limited",
      "Aegon Life Insurance Company Ltd.",
      "Aviva Life Insur Co. India Pvt. Ltd.",
      "Axis Asset Management Company Limited",
      "Bajaj Allianz Life Insurance Company Ltd",
      "Baring International Fund Mgrs (Ireland) Limited",
      "Baroda Asset Management India Limited"
    ],
    "United States": [
      "Aegon Asset Management UK PLC",
      "Ampega Investment GmbH",
      "Aviva SpA",
      "BBVA Asset Management SA SGIIC",
      "Caser Pensiones EGFP",
      "HSBC Investment Funds (HK) Limited",
      "Premier Portfolio Managers Limited",
      "SEI Investments Global Limited",
      "Vanguard"
    ]
  },
  "status": "ok"
}

HTTP route

/mutual_funds/family

API credits

1 per request

API parameters

Parameter Details
country • Parameter is optional
• Filter by country name or alpha code
fund_family • Parameter is optional
• Filter by investment company that manages the fund
apikey • Required parameter
• Your API key at the Basic plan or above

Response

Key Description
result all available fund families segmented by country

JSON request example

https://api.twelvedata.com/mutual_funds/family?apikey=demo

https://api.twelvedata.com/mutual_funds/family?country=US&apikey=demo

Downloadable CSV example

https://api.twelvedata.com/mutual_funds/family?format=CSV&apikey=demo

MFs Type List

This API request returns a list of mutual funds types.

HTTP request example

https://api.twelvedata.com/mutual_funds/type?apikey=your_api_key

This request will return JSON with the following structure

{
  "result": {
    "Singapore": [
      "Property - Indirect Asia",
      "Sector Equity Water",
      "SGD Bond",
      "Singapore Equity",
      "Taiwan Large-Cap Equity"
    ],
    "United States": [
      "Asia-Pacific ex-Japan Equity",
      "EUR Flexible Allocation - Global",
      "Euro Short Bond PP",
      "Large Blend",
      "Other Allocation"
    ]
  },
  "status": "ok"
}

HTTP route

/mutual_funds/type

API credits

1 per request

API parameters

Parameter Details
country • Parameter is optional
• Filter by country name or alpha code
fund_type • Parameter is optional
• Filter by the type of fund
apikey • Required parameter
• Your API key at the Basic plan or above

Response

Key Description
result all available fund types segmented by country

JSON request example

https://api.twelvedata.com/mutual_funds/type?apikey=demo

https://api.twelvedata.com/mutual_funds/type?country=US&apikey=demo

Downloadable CSV example

https://api.twelvedata.com/mutual_funds/type?format=CSV&apikey=demo

All dataHigh Demand

This API request returns a complete breakdown of a mutual fund, including summary, performance, risk, ratings, composition, purchase_info, and sustainability.

HTTP request example

https://api.twelvedata.com/mutual_funds/world?symbol=VFIAX&apikey=your_api_key

This request will return JSON with the following structure

{
  "mutual_fund": {
    "summary": {
      "symbol": "VFIAX",
      "name": "Vanguard 500 Index Fund Admiral Shares",
      "fund_family": "Vanguard",
      "fund_type": "Large Blend",
      "currency": "USD",
      "share_class_inception_date": "2000-11-13",
      "ytd_return": -0.05036,
      "expense_ratio_net": 0.0004,
      "yield": 0.0133,
      "nav": 411.2,
      "min_investment": 3000,
      "turnover_rate": 0.04,
      "net_assets": 753409982464,
      "overview": "The investment seeks to track the performance of the Standard & Poor's 500 Index that measures the investment return of large-capitalization stocks.  The fund employs an indexing investment approach designed to track the performance of the Standard & Poor's 500 Index, a widely recognized benchmark of U.S. stock market performance that is dominated by the stocks of large U.S. companies. The advisor attempts to replicate the target index by investing all, or substantially all, of its assets in the stocks that make up the index, holding each stock in approximately the same proportion as its weighting in the index.",
      "people": [
        {
          "name": "Michelle M. Louie",
          "tenure_since": "2017-11-30"
        }
      ]
    },
    "performance": {
      "trailing_returns": [
        {
          "period": "ytd",
          "share_class_return": -0.05036,
          "category_return": 0.1484,
          "rank_in_category": 42
        },
        {
          "period": "1_month",
          "share_class_return": 0.04934,
          "category_return": 0.0165,
          "rank_in_category": 31
        },
        {
          "period": "3_month",
          "share_class_return": -0.03611,
          "category_return": 0.0755,
          "rank_in_category": 27
        },
        {
          "period": "1_year",
          "share_class_return": 0.16053,
          "category_return": 0.4047,
          "rank_in_category": 51
        },
        {
          "period": "3_year",
          "share_class_return": 0.19197,
          "category_return": 0.1677,
          "rank_in_category": 27
        },
        {
          "period": "5_year",
          "share_class_return": 0.1616,
          "category_return": 0.16149,
          "rank_in_category": 26
        },
        {
          "period": "10_year",
          "share_class_return": 0.1468,
          "category_return": 0.1321,
          "rank_in_category": 0
        }
      ],
      "annual_total_returns": [
        {
          "year": 2021,
          "share_class_return": 0.28664,
          "category_return": null
        },
        {
          "year": 2020,
          "share_class_return": 0.18366,
          "category_return": 0.15827
        },
        {
          "year": 2019,
          "share_class_return": 0.31455,
          "category_return": 0.28776
        },
        {
          "year": 2018,
          "share_class_return": -0.04427,
          "category_return": -0.06269
        },
        {
          "year": 2017,
          "share_class_return": 0.21785,
          "category_return": 0.20438
        },
        {
          "year": 2016,
          "share_class_return": 0.11926,
          "category_return": 0.1036891
        },
        {
          "year": 2015,
          "share_class_return": 0.01362,
          "category_return": -0.01069
        },
        {
          "year": 2014,
          "share_class_return": 0.13642,
          "category_return": 0.1096
        },
        {
          "year": 2013,
          "share_class_return": 0.32333,
          "category_return": 0.315
        },
        {
          "year": 2012,
          "share_class_return": 0.15964,
          "category_return": 0.14961
        },
        {
          "year": 2011,
          "share_class_return": 0.02084,
          "category_return": -0.01271
        },
        {
          "year": 2010,
          "share_class_return": 0.1505,
          "category_return": 0.14006
        },
        {
          "year": 2009,
          "share_class_return": 0.2662,
          "category_return": 0.2817
        },
        {
          "year": 2008,
          "share_class_return": -0.36969,
          "category_return": -0.37791
        },
        {
          "year": 2007,
          "share_class_return": 0.0547,
          "category_return": 0.0616
        },
        {
          "year": 2006,
          "share_class_return": 0.15747,
          "category_return": 0.14167
        },
        {
          "year": 2005,
          "share_class_return": 0.04869,
          "category_return": 0.05877
        },
        {
          "year": 2004,
          "share_class_return": 0.10823,
          "category_return": 0.10024
        },
        {
          "year": 2003,
          "share_class_return": 0.28593,
          "category_return": 0.27046
        },
        {
          "year": 2002,
          "share_class_return": -0.22097,
          "category_return": -0.2225
        },
        {
          "year": 2001,
          "share_class_return": -0.11976,
          "category_return": -0.13502
        }
      ],
      "quarterly_total_returns": [
        {
          "year": 2021,
          "q1": 0.06175,
          "q2": 0.08537,
          "q3": 0.0057,
          "q4": 0.11015
        },
        {
          "year": 2020,
          "q1": -0.19611,
          "q2": 0.20543,
          "q3": 0.08918,
          "q4": 0.12146
        },
        {
          "year": 2019,
          "q1": 0.13645,
          "q2": 0.04298,
          "q3": 0.01691,
          "q4": 0.0906
        },
        {
          "year": 2018,
          "q1": -0.00768,
          "q2": 0.03422,
          "q3": 0.07699,
          "q4": -0.13532
        },
        {
          "year": 2017,
          "q1": 0.06052,
          "q2": 0.03073,
          "q3": 0.04475,
          "q4": 0.06638
        },
        {
          "year": 2016,
          "q1": 0.01337,
          "q2": 0.02445,
          "q3": 0.03844,
          "q4": 0.03821
        },
        {
          "year": 2015,
          "q1": 0.00944,
          "q2": 0.00282,
          "q3": -0.0645,
          "q4": 0.07036
        },
        {
          "year": 2014,
          "q1": 0.01794,
          "q2": 0.05221,
          "q3": 0.01120,
          "q4": 0.04922
        },
        {
          "year": 2013,
          "q1": 0.106,
          "q2": 0.02897,
          "q3": 0.05234,
          "q4": 0.10495
        },
        {
          "year": 2012,
          "q1": 0.12572,
          "q2": -0.02751,
          "q3": 0.0634,
          "q4": -0.00388
        },
        {
          "year": 2011,
          "q1": 0.05901,
          "q2": 0.00098,
          "q3": -0.13878,
          "q4": 0.11819
        },
        {
          "year": 2010,
          "q1": 0.05379,
          "q2": -0.11426,
          "q3": 0.11291,
          "q4": 0.10755
        },
        {
          "year": 2009,
          "q1": -0.10974,
          "q2": 0.15992,
          "q3": 0.15613,
          "q4": 0.06059
        },
        {
          "year": 2008,
          "q1": -0.09452,
          "q2": -0.02733,
          "q3": -0.08339,
          "q4": -0.21921
        },
        {
          "year": 2007,
          "q1": 0.00627,
          "q2": 0.06258,
          "q3": 0.0205,
          "q4": -0.03343
        },
        {
          "year": 2006,
          "q1": 0.04212,
          "q2": -0.01451,
          "q3": 0.05646,
          "q4": 0.06680
        },
        {
          "year": 2005,
          "q1": -0.02143,
          "q2": 0.01354,
          "q3": 0.03590,
          "q4": 0.02068
        },
        {
          "year": 2004,
          "q1": 0.0167,
          "q2": 0.01705,
          "q3": -0.01875,
          "q4": 0.09222
        },
        {
          "year": 2003,
          "q1": -0.03172,
          "q2": 0.15403,
          "q3": 0.02615,
          "q4": 0.12147
        },
        {
          "year": 2002,
          "q1": 0.00249,
          "q2": -0.1342,
          "q3": -0.17203,
          "q4": 0.08403
        },
        {
          "year": 2001,
          "q1": -0.11883,
          "q2": 0.05824,
          "q3": -0.14704,
          "q4": 0.10669
        }
      ],
      "load_adjusted_return": [
        {
          "period": "1_year",
          "return": 0.4076
        },
        {
          "period": "3_year",
          "return": 0.1864
        },
        {
          "period": "5_year",
          "return": 0.1761
        },
        {
          "period": "10_year",
          "return": 0.148
        }
      ]
    },
    "risk": {
      "volatility_measures": [
        {
          "period": "3_year",
          "alpha": -0.03,
          "alpha_category": -0.0158,
          "beta": 1,
          "beta_category": 0.01,
          "mean_annual_return": 1.58,
          "mean_annual_return_category": 0.0145,
          "r_squared": 100,
          "r_squared_category": 0.9547,
          "std": 18.52,
          "std_category": 0.19,
          "sharpe_ratio": 0.95,
          "sharpe_ratio_category": 0.0085,
          "treynor_ratio": 17.41,
          "treynor_ratio_category": 0.1559
        },
        {
          "period": "5_year",
          "alpha": -0.03,
          "alpha_category": -0.01289,
          "beta": 1,
          "beta_category": 0.01,
          "mean_annual_return": 1.45,
          "mean_annual_return_category": 0.0135,
          "r_squared": 100,
          "r_squared_category": 0.9492,
          "std": 14.99,
          "std_category": 0.1547,
          "sharpe_ratio": 1.08,
          "sharpe_ratio_category": 0.0098,
          "treynor_ratio": 16.46,
          "treynor_ratio_category": 0.1499
        },
        {
          "period": "10_year",
          "alpha": -0.03,
          "alpha_category": -0.0156,
          "beta": 1,
          "beta_category": 0.0101,
          "mean_annual_return": 1.23,
          "mean_annual_return_category": 0.0112,
          "r_squared": 100,
          "r_squared_category": 0.9489,
          "std": 13.59,
          "std_category": 0.1417,
          "sharpe_ratio": 1.04,
          "sharpe_ratio_category": 0.0091,
          "treynor_ratio": 14.19,
          "treynor_ratio_category": 0.125
        }
      ],
      "valuation_metrics": {
        "price_to_earnings": 26.46,
        "price_to_earnings_category": 26.32,
        "price_to_book": 4.42,
        "price_to_book_category": 4.98,
        "price_to_sales": 2.96,
        "price_to_sales_category": 2.79,
        "price_to_cashflow": 17.57,
        "price_to_cashflow_category": 17.61,
        "median_market_capitalization": 197452,
        "median_market_capitalization_category": 265875,
        "3_year_earnings_growth": 18.72,
        "3_year_earnings_growths_category": 19.53
      }
    },
    "ratings": {
      "performance_rating": 5,
      "risk_rating": 3,
      "return_rating": 4
    },
    "composition": {
      "major_market_sectors": [
        {
          "sector": "Technology",
          "weight": 0.24239
        },
        {
          "sector": "Financial Services",
          "weight": 0.142
        },
        {
          "sector": "Healthcare",
          "weight": 0.131
        },
        {
          "sector": "Consumer Cyclical",
          "weight": 0.1201
        },
        {
          "sector": "Communication Services",
          "weight": 0.1114
        },
        {
          "sector": "Industrials",
          "weight": 0.08859
        },
        {
          "sector": "Consumer Defensive",
          "weight": 0.06320
        },
        {
          "sector": "Energy",
          "weight": 0.02839
        },
        {
          "sector": "Realestate",
          "weight": 0.02579
        },
        {
          "sector": "Utilities",
          "weight": 0.0243
        },
        {
          "sector": "Basic Materials",
          "weight": 0.0227
        }
      ],
      "asset_allocation": {
        "cash": 0.0004,
        "stocks": 0.9996,
        "preferred_stocks": 0,
        "convertables": 0,
        "bonds": 0,
        "others": 0
      },
      "top_holdings": [
        {
          "symbol": "AAPL",
          "name": "Apple Inc",
          "weight": 0.0592
        },
        {
          "symbol": "MSFT",
          "name": "Microsoft Corp",
          "weight": 0.05619
        },
        {
          "symbol": "AMZN",
          "name": "Amazon.com Inc",
          "weight": 0.04059
        },
        {
          "symbol": "FB",
          "name": "Facebook Inc Class A",
          "weight": 0.0229
        },
        {
          "symbol": "GOOGL",
          "name": "Alphabet Inc Class A",
          "weight": 0.0202
        },
        {
          "symbol": "GOOG",
          "name": "Alphabet Inc Class C",
          "weight": 0.0197
        },
        {
          "symbol": "BRK.B",
          "name": "Berkshire Hathaway Inc Class B",
          "weight": 0.0144
        },
        {
          "symbol": "TSLA",
          "name": "Tesla Inc",
          "weight": 0.0144
        },
        {
          "symbol": "NVDA",
          "name": "NVIDIA Corp",
          "weight": 0.0137
        },
        {
          "symbol": "JPM",
          "name": "JPMorgan Chase & Co",
          "weight": 0.01299
        }
      ],
      "bond_breakdown": {
        "average_maturity": {
          "fund": null,
          "category": null
        },
        "average_duration": {
          "fund": null,
          "category": -1.15
        },
        "credit_quality": [
          {
            "grade": "U.S. Government",
            "weight": 0
          },
          {
            "grade": "AAA",
            "weight": 0
          },
          {
            "grade": "AA",
            "weight": 0
          },
          {
            "grade": "A",
            "weight": 0
          },
          {
            "grade": "BBB",
            "weight": 0
          },
          {
            "grade": "BB",
            "weight": 0
          },
          {
            "grade": "B",
            "weight": 0
          },
          {
            "grade": "Below B",
            "weight": 0
          },
          {
            "grade": "Not Rated",
            "weight": 0
          }
        ]
      }
    },
    "purchase_info": {
      "expenses": {
        "expense_ratio_gross": 0.0004,
        "expense_ratio_net": 0.0004
      },
      "minimums": {
        "initial_investment": 3000,
        "additional_investment": 1,
        "initial_ira_investment": null,
        "additional_ira_investment": null
      },
      "pricing": {
        "nav": 411.2,
        "12_month_low": 360.14,
        "12_month_high": 442.63,
        "last_month": 404.56
      },
      "brokerages": [
        "ADP Access",
        "ADP Access IPS Z",
        "ADP Access Open Fund Architecture",
        "ADP Access Tier 0",
        "ADP Advisor Access 3(21) Tier 0",
        "ADP Advisor Access Tier 0",
        "Allowab (non-advisory)",
        "Ameriprise Brokerage",
        "Avantax",
        "Bear Stearns",
        "Bear Stearns No-Load Transaction Fee",
        "Cetera Advisor Networks LLC",
        "Cetera Advisor Networks LLC- PAM, PRIME, Premier",
        "Cetera Advisors LLC",
        "Cetera Advisors LLC- PAM, PRIME, Premier",
        "Cetera Financial Specialists LLC- Premier",
        "Comerica Bank",
        "CommonWealth PPS",
        "Commonwealth (PPS Access Program)",
        "Commonwealth (PPS/Advisory)",
        "Commonwealth Universe",
        "DailyAccess Corporation FRIAG",
        "DailyAccess Corporation MATC",
        "DailyAccess Corporation Matrix",
        "DailyAccess Corporation Mid-Atlantic",
        "DailyAccess Corporation RTC",
        "DATALynx",
        "DWS Retirement Sevs Investment Offerings",
        "E TRADE Financial",
        "ETrade No Load Fee",
        "Federated TrustConnect",
        "Fidelity Institutional FundsNetwork",
        "Fidelity Retail FundsNetwork",
        "H Beck Inc.",
        "HD Vest",
        "HD Vest - Vest Advisor",
        "H&R Block Financial Advisors Inc",
        "JPMorgan",
        "JPMorgan INVEST",
        "JP MORGAN LOAD",
        "JP MORGAN NO-LOAD NTF",
        "JP MORGAN NO-LOAD TRANSACTION FEE",
        "Lincoln Investment Planning",
        "LPL SAM Eligible - 6.18.2020",
        "LPL SWM - 6.18.2020",
        "Matrix Financial Solutions",
        "Merrill Lynch",
        "Met Life Resources MFSP Alliance List",
        "Mid Atlantic Capital Corp",
        "Mid Atlantic Capital Group",
        "Mony Securities Corp",
        "Morgan Stanley - Brokerage Accounts",
        "Morgan Stanley Consulting Group Advisor",
        "Morgan Stanley Portfolio Management",
        "MSSB PlanPremier",
        "MSSB PlanPremierTPA",
        "MSWM Brokerage",
        "Nationwide Retirement Clear Adva",
        "Nationwide Retirement Flexible Advantage",
        "Nationwide Retirement Resource",
        "NM WMC",
        "Northwestern Mutual Inv Srvc, LLC",
        "NYLIM 401(k) Complete",
        "Pershing Retirement Plan Network",
        "Principal Advantage",
        "Protected Investors of America",
        "Pruco Securities LLC -PruUMA’s Mutual Funds",
        "Raymond James",
        "Raymond James WRAP Eligible",
        "RBC Wealth Management-Network Eligible",
        "RBC Wealth Management-Wrap Eligible",
        "Robert W. Baird & Co.",
        "Schwab All (Retail, Instl, Retirement)",
        "Schwab Existing Shareholders Only",
        "Schwab Institutional",
        "Schwab Institutional Only",
        "Schwab Retail",
        "Scottrade Load",
        "Scottrade NTF",
        "Scottrade TF",
        "Securities America Advisors",
        "Securities America Inc.",
        "Sterne, Agee & Leach, Inc.,",
        "SunGard Transaction Network",
        "Td Ameritrade, Inc.",
        "TD Ameritrade Institutional",
        "TD Ameritrade Institutional NTF",
        "TD Ameritrade Retail",
        "TD Ameritrade Retail NTF",
        "TD Ameritrade Trust Company",
        "Thrivent   Advisory Eligible",
        "Thrivent   Retail Eligible",
        "Trade PMR NTF",
        "Trade PMR Transaction Fee",
        "TradeStation Securities",
        "TRUSTlynx",
        "Vanguard Load",
        "Vanguard NTF",
        "Vanguard TF",
        "Waddell & Reed Choice MAP Flex",
        "WFA Fdntl Choice/PIM Updated 6.1.21",
        "WFA MF Advisory Updated 6.1.21",
        "WR Hambrecht Co LLC"
      ]
    },
    "sustainability": {
      "score": 22,
      "corporate_esg_pillars": {
        "environmental": 3.73,
        "social": 10.44,
        "governance": 7.86
      },
      "sustainable_investment": false,
      "corporate_aum": 0.99486
    }
  },
  "status": "ok"
}

HTTP route

/mutual_funds/world

API credits

1000 per request

API parameters

Parameter Details
symbol • Required parameter
• Symbol ticker of mutual fund
figi • Parameter is optional
• Filter by financial instrument global identifier (FIGI)
country • Parameter is optional
• Filter by country name or alpha code
dp • Parameter is optional
• Number of decimal places for floating values
• Accepts value in range [0,11]; default 5
apikey • Required parameter
• Your API key upgraded to the Enterprise plan or above

Response

Key Description
symbol all available fund types segmented by country
name fund name
fund_family investment company that manages the fund
fund_type type of the fund
currency currency of fund price
share_class_inception_date the date from which the fund started operations and the returns are calculated
ytd_return percentage of profit of the fund since the first trading day of the current calendar year
expense_ratio_net percentage of mutual fund assets steered toward a fund's operating expenses and fund management fees
yield income returned to its investors through interest and dividends generated by the fund's investments
nav last price of the fund
min_investment investment minimum
turnover_rate percentage rate at which mutual fund replaces its holdings on investment every year
net_assets total assets of a fund minus its total liabilities
overview description of the fund
people.name manager name
people.tenure_since manager tenuring date
trailing_returns.period period of trailing returns
trailing_returns.share_class_return fund returns (%) generated over a given period
trailing_returns.category_return same category average returns (%) generated over a given period
trailing_returns.rank_in_category rank of a fund in category by total returns
annual_total_returns.year year of total returns
annual_total_returns.share_class_return fund total returns (%) generated over a given year
annual_total_returns.category_return same category average total returns (%) generated over a given year
quarterly_total_returns.year year of a fund quarter return
quarterly_total_returns.q1 total return (%) of a fund in the first quarter
quarterly_total_returns.q2 total return (%) of a fund in the second quarter
quarterly_total_returns.q3 total return (%) of a fund in the third quarter
quarterly_total_returns.q4 total return (%) of a fund in the forth quarter
load_adjusted_return.period period of a load adjusted return
load_adjusted_return.return actual return (%) an investor sees after accounting for fees and sales charges are deducted from a mutual fund's performance
volatility_measures.period period of a measure
volatility_measures.alpha alpha score of a fund
volatility_measures.alpha_category average alpha score of a fund's category
volatility_measures.beta beta score of a fund
volatility_measures.beta_category average beta score of a fund's category
volatility_measures.mean_annual mean annual return of a fund
volatility_measures.mean_annual_category average mean annual return of a fund's category
volatility_measures.r_squared r-squared metric of a fund
volatility_measures.r_squared_category average r-squared metric of a fund's category
volatility_measures.std standard deviation of a fund
volatility_measures.std_category average standard deviation of a fund's category
volatility_measures.sharpe_ratio sharpe ratio of a fund
volatility_measures.sharpe_ratio_category average sharpe ratio of a fund's category
volatility_measures.treynor_ratio treynor ratio of a fund
volatility_measures.treynor_ratio_category average treynor ratio of a fund's category
valuation_metrics.price_to_earnings fund price to earnings metric
valuation_metrics.price_to_earnings_category average price to earnings metric of funds in the same category
valuation_metrics.price_to_book fund price to book metric
valuation_metrics.price_to_book_category average price to book metric of funds in the same category
valuation_metrics.price_to_sales fund price to sales metric
valuation_metrics.price_to_sales_category average price to sales metric of funds in the same category
valuation_metrics.price_to_cashflow fund price to cashflow metric
valuation_metrics.price_to_cashflow_category average price to cashflow metric of funds in the same category
valuation_metrics.median_market_capitalization median market capitalization of a fund
valuation_metrics.median_market_capitalization_category median market capitalization of funds in the same category
valuation_metrics.3_year_earnings_growth earnings growth over the last three years
valuation_metrics.3_year_earnings_growth_category earnings growth over the last three years of funds in the same category
performance_rating performance rating from 0 to 5
risk_rating risk rating from 0 to 5
return_rating return rating from 0 to 5
major_market_sectors.sector sector category of a fund exposure
major_market_sectors.weight weight (%) of a fund exposure in a sector
asset_allocation.cash percentage of overall portfolio composition in cash
asset_allocation.stocks percentage of overall portfolio composition in stocks
asset_allocation.preferred_stocks percentage of overall portfolio composition in preferred stocks
asset_allocation.convertables percentage of overall portfolio composition in convertable securities
asset_allocation.bonds percentage of overall portfolio composition in bond
asset_allocation.others percentage of overall portfolio composition in other forms of holding
top_holdings.symbol symbol ticker of a holding instrument
top_holdings.name name of a holding instrument
top_holdings.weight weight (%) of a holding instrument in overall portfolio composition
bond_breakdown.average_maturity.fund average maturity of bond holding of a fund
bond_breakdown.average_maturity.category average maturity of bond holding of funds in the same category
bond_breakdown.average_duration.fund average duration of bond holding of a fund
bond_breakdown.average_duration.category average duration of bond holding of funds in the same category
bond_breakdown.credit_quality.grade rating of bond holding of a fund from AAA to below B
bond_breakdown.credit_quality.weight weight of bond holding in fund portfolio
expenses.expense_ratio_gross annual cost of investing in a mutual fund
expenses.expense_ratio_net percentage of mutual fund assets steered toward a fund's operating expenses and fund management fees
minimums.initial_investment investment minimum
minimums.additional_investment minimum amount of additional investment
minimums.initial_ira_investment investment minimum for IRA
minimums.additional_ira_investment minimum amount of additional investment for IRA
pricing.nav last price of the fund
pricing.12_month_low lowest price of the fund over the last year
pricing.12_month_high highest price of the fund over the last year
pricing.last_month fund price at the end of the last month
brokerages list of brokerages where mutual fund can be purchased
sustainability.score asset-weighted average of normalized company-level ESG Scores for the covered holdings in the portfolio from 0 to 100
corporate_esg_pillars.environmental ESG environmental score
corporate_esg_pillars.social ESG social score
corporate_esg_pillars.governance ESG governance score
sustainable_investment indication that the fund discloses in their prospectus that they employ socially responsible or ESG principles in their investment selection processes
corporate_aum percentage of AUM used to calculate sustainability score

JSON request example

https://api.twelvedata.com/mutual_funds/world?symbol=VFIAX&apikey=demo

Summary

This API request returns a brief summary of a mutual fund.

HTTP request example

https://api.twelvedata.com/mutual_funds/world/summary?symbol=VFIAX&apikey=your_api_key

This request will return JSON with the following structure

{
  "mutual_fund": {
    "summary": {
      "symbol": "VFIAX",
      "name": "Vanguard 500 Index Fund Admiral Shares",
      "fund_family": "Vanguard",
      "fund_type": "Large Blend",
      "currency": "USD",
      "share_class_inception_date": "2000-11-13",
      "ytd_return": -0.05036,
      "expense_ratio_net": 0.0004,
      "yield": 0.0133,
      "nav": 411.2,
      "min_investment": 3000,
      "turnover_rate": 0.04,
      "net_assets": 753409982464,
      "overview": "The investment seeks to track the performance of the Standard & Poor's 500 Index that measures the investment return of large-capitalization stocks.  The fund employs an indexing investment approach designed to track the performance of the Standard & Poor's 500 Index, a widely recognized benchmark of U.S. stock market performance that is dominated by the stocks of large U.S. companies. The advisor attempts to replicate the target index by investing all, or substantially all, of its assets in the stocks that make up the index, holding each stock in approximately the same proportion as its weighting in the index.",
      "people": [
        {
          "name": "Michelle M. Louie",
          "tenure_since": "2017-11-30"
        }
      ]
    }
  },
  "status": "ok"
}

HTTP route

/mutual_funds/world/summary

API credits

200 per request

API parameters

Parameter Details
symbol • Required parameter
• Symbol ticker of mutual fund
figi • Parameter is optional
• Filter by financial instrument global identifier (FIGI)
country • Parameter is optional
• Filter by country name or alpha code
dp • Parameter is optional
• Number of decimal places for floating values
• Accepts value in range [0,11]; default 5
apikey • Required parameter
• Your API key upgraded to the Enterprise plan or above

Response

Key Description
symbol all available fund types segmented by country
name fund name
fund_family investment company that manages the fund
fund_type type of the fund
currency currency of fund price
share_class_inception_date the date from which the fund started operations and the returns are calculated
ytd_return percentage of profit of the fund since the first trading day of the current calendar year
expense_ratio_net percentage of mutual fund assets steered toward a fund's operating expenses and fund management fees
yield income returned to its investors through interest and dividends generated by the fund's investments
nav last price of the fund
min_investment investment minimum
turnover_rate percentage rate at which mutual fund replaces its holdings on investment every year
net_assets total assets of a fund minus its total liabilities
overview description of the fund
people.name manager name
people.tenure_since manager tenuring date

JSON request example

https://api.twelvedata.com/mutual_funds/world/summary?symbol=VFIAX&apikey=demo

PerformanceHigh Demand

This API request returns detailed performance of a mutual fund, including trailing, annual, quarterly, and load-adjusted returns.

HTTP request example

https://api.twelvedata.com/mutual_funds/world/performance?symbol=VFIAX&apikey=your_api_key

This request will return JSON with the following structure

{
  "mutual_fund": {
    "performance": {
      "trailing_returns": [
        {
          "period": "ytd",
          "share_class_return": -0.05036,
          "category_return": 0.1484,
          "rank_in_category": 42
        },
        {
          "period": "1_month",
          "share_class_return": 0.04934,
          "category_return": 0.0165,
          "rank_in_category": 31
        },
        {
          "period": "3_month",
          "share_class_return": -0.03611,
          "category_return": 0.0755,
          "rank_in_category": 27
        },
        {
          "period": "1_year",
          "share_class_return": 0.16053,
          "category_return": 0.4047,
          "rank_in_category": 51
        },
        {
          "period": "3_year",
          "share_class_return": 0.19197,
          "category_return": 0.1677,
          "rank_in_category": 27
        },
        {
          "period": "5_year",
          "share_class_return": 0.1616,
          "category_return": 0.16149,
          "rank_in_category": 26
        },
        {
          "period": "10_year",
          "share_class_return": 0.1468,
          "category_return": 0.1321,
          "rank_in_category": 0
        }
      ],
      "annual_total_returns": [
        {
          "year": 2021,
          "share_class_return": 0.28664,
          "category_return": null
        },
        {
          "year": 2020,
          "share_class_return": 0.18366,
          "category_return": 0.15827
        },
        {
          "year": 2019,
          "share_class_return": 0.31455,
          "category_return": 0.28776
        },
        {
          "year": 2018,
          "share_class_return": -0.04427,
          "category_return": -0.06269
        },
        {
          "year": 2017,
          "share_class_return": 0.21785,
          "category_return": 0.20438
        },
        {
          "year": 2016,
          "share_class_return": 0.11926,
          "category_return": 0.1036891
        },
        {
          "year": 2015,
          "share_class_return": 0.01362,
          "category_return": -0.01069
        },
        {
          "year": 2014,
          "share_class_return": 0.13642,
          "category_return": 0.1096
        },
        {
          "year": 2013,
          "share_class_return": 0.32333,
          "category_return": 0.315
        },
        {
          "year": 2012,
          "share_class_return": 0.15964,
          "category_return": 0.14961
        },
        {
          "year": 2011,
          "share_class_return": 0.02084,
          "category_return": -0.01271
        },
        {
          "year": 2010,
          "share_class_return": 0.1505,
          "category_return": 0.14006
        },
        {
          "year": 2009,
          "share_class_return": 0.2662,
          "category_return": 0.2817
        },
        {
          "year": 2008,
          "share_class_return": -0.36969,
          "category_return": -0.37791
        },
        {
          "year": 2007,
          "share_class_return": 0.0547,
          "category_return": 0.0616
        },
        {
          "year": 2006,
          "share_class_return": 0.15747,
          "category_return": 0.14167
        },
        {
          "year": 2005,
          "share_class_return": 0.04869,
          "category_return": 0.05877
        },
        {
          "year": 2004,
          "share_class_return": 0.10823,
          "category_return": 0.10024
        },
        {
          "year": 2003,
          "share_class_return": 0.28593,
          "category_return": 0.27046
        },
        {
          "year": 2002,
          "share_class_return": -0.22097,
          "category_return": -0.2225
        },
        {
          "year": 2001,
          "share_class_return": -0.11976,
          "category_return": -0.13502
        }
      ],
      "quarterly_total_returns": [
        {
          "year": 2021,
          "q1": 0.06175,
          "q2": 0.08537,
          "q3": 0.0057,
          "q4": 0.11015
        },
        {
          "year": 2020,
          "q1": -0.19611,
          "q2": 0.20543,
          "q3": 0.08918,
          "q4": 0.12146
        },
        {
          "year": 2019,
          "q1": 0.13645,
          "q2": 0.04298,
          "q3": 0.01691,
          "q4": 0.0906
        },
        {
          "year": 2018,
          "q1": -0.00768,
          "q2": 0.03422,
          "q3": 0.07699,
          "q4": -0.13532
        },
        {
          "year": 2017,
          "q1": 0.06052,
          "q2": 0.03073,
          "q3": 0.04475,
          "q4": 0.06638
        },
        {
          "year": 2016,
          "q1": 0.01337,
          "q2": 0.02445,
          "q3": 0.03844,
          "q4": 0.03821
        },
        {
          "year": 2015,
          "q1": 0.00944,
          "q2": 0.00282,
          "q3": -0.0645,
          "q4": 0.07036
        },
        {
          "year": 2014,
          "q1": 0.01794,
          "q2": 0.05221,
          "q3": 0.01120,
          "q4": 0.04922
        },
        {
          "year": 2013,
          "q1": 0.106,
          "q2": 0.02897,
          "q3": 0.05234,
          "q4": 0.10495
        },
        {
          "year": 2012,
          "q1": 0.12572,
          "q2": -0.02751,
          "q3": 0.0634,
          "q4": -0.00388
        },
        {
          "year": 2011,
          "q1": 0.05901,
          "q2": 0.00098,
          "q3": -0.13878,
          "q4": 0.11819
        },
        {
          "year": 2010,
          "q1": 0.05379,
          "q2": -0.11426,
          "q3": 0.11291,
          "q4": 0.10755
        },
        {
          "year": 2009,
          "q1": -0.10974,
          "q2": 0.15992,
          "q3": 0.15613,
          "q4": 0.06059
        },
        {
          "year": 2008,
          "q1": -0.09452,
          "q2": -0.02733,
          "q3": -0.08339,
          "q4": -0.21921
        },
        {
          "year": 2007,
          "q1": 0.00627,
          "q2": 0.06258,
          "q3": 0.0205,
          "q4": -0.03343
        },
        {
          "year": 2006,
          "q1": 0.04212,
          "q2": -0.01451,
          "q3": 0.05646,
          "q4": 0.06680
        },
        {
          "year": 2005,
          "q1": -0.02143,
          "q2": 0.01354,
          "q3": 0.03590,
          "q4": 0.02068
        },
        {
          "year": 2004,
          "q1": 0.0167,
          "q2": 0.01705,
          "q3": -0.01875,
          "q4": 0.09222
        },
        {
          "year": 2003,
          "q1": -0.03172,
          "q2": 0.15403,
          "q3": 0.02615,
          "q4": 0.12147
        },
        {
          "year": 2002,
          "q1": 0.00249,
          "q2": -0.1342,
          "q3": -0.17203,
          "q4": 0.08403
        },
        {
          "year": 2001,
          "q1": -0.11883,
          "q2": 0.05824,
          "q3": -0.14704,
          "q4": 0.10669
        }
      ],
      "load_adjusted_return": [
        {
          "period": "1_year",
          "return": 0.4076
        },
        {
          "period": "3_year",
          "return": 0.1864
        },
        {
          "period": "5_year",
          "return": 0.1761
        },
        {
          "period": "10_year",
          "return": 0.148
        }
      ]
    }
  },
  "status": "ok"
}

HTTP route

/mutual_funds/world/performance

API credits

200 per request

API parameters

Parameter Details
symbol • Required parameter
• Symbol ticker of mutual fund
figi • Parameter is optional
• Filter by financial instrument global identifier (FIGI)
country • Parameter is optional
• Filter by country name or alpha code
dp • Parameter is optional
• Number of decimal places for floating values
• Accepts value in range [0,11]; default 5
apikey • Required parameter
• Your API key upgraded to the Enterprise plan or above

Response

Key Description
trailing_returns.period period of trailing returns
trailing_returns.share_class_return fund returns (%) generated over a given period
trailing_returns.category_return same category average returns (%) generated over a given period
trailing_returns.rank_in_category rank of a fund in category by total returns
annual_total_returns.year year of total returns
annual_total_returns.share_class_return fund total returns (%) generated over a given year
annual_total_returns.category_return same category average total returns (%) generated over a given year
quarterly_total_returns.year year of a fund quarter return
quarterly_total_returns.q1 total return (%) of a fund in the first quarter
quarterly_total_returns.q2 total return (%) of a fund in the second quarter
quarterly_total_returns.q3 total return (%) of a fund in the third quarter
quarterly_total_returns.q4 total return (%) of a fund in the forth quarter
load_adjusted_return.period period of a load adjusted return
load_adjusted_return.return actual return (%) an investor sees after accounting for fees and sales charges are deducted from a mutual fund's performance

JSON request example

https://api.twelvedata.com/mutual_funds/world/performance?symbol=VFIAX&apikey=demo

Risk

This API request returns core metrics to measure the risk of investing in a mutual fund.

HTTP request example

https://api.twelvedata.com/mutual_funds/world/risk?symbol=VFIAX&apikey=your_api_key

This request will return JSON with the following structure

{
  "mutual_fund": {
    "risk": {
      "volatility_measures": [
        {
          "period": "3_year",
          "alpha": -0.03,
          "alpha_category": -0.0158,
          "beta": 1,
          "beta_category": 0.01,
          "mean_annual_return": 1.58,
          "mean_annual_return_category": 0.0145,
          "r_squared": 100,
          "r_squared_category": 0.9547,
          "std": 18.52,
          "std_category": 0.19,
          "sharpe_ratio": 0.95,
          "sharpe_ratio_category": 0.0085,
          "treynor_ratio": 17.41,
          "treynor_ratio_category": 0.1559
        },
        {
          "period": "5_year",
          "alpha": -0.03,
          "alpha_category": -0.01289,
          "beta": 1,
          "beta_category": 0.01,
          "mean_annual_return": 1.45,
          "mean_annual_return_category": 0.0135,
          "r_squared": 100,
          "r_squared_category": 0.9492,
          "std": 14.99,
          "std_category": 0.1547,
          "sharpe_ratio": 1.08,
          "sharpe_ratio_category": 0.0098,
          "treynor_ratio": 16.46,
          "treynor_ratio_category": 0.1499
        },
        {
          "period": "10_year",
          "alpha": -0.03,
          "alpha_category": -0.0156,
          "beta": 1,
          "beta_category": 0.0101,
          "mean_annual_return": 1.23,
          "mean_annual_return_category": 0.0112,
          "r_squared": 100,
          "r_squared_category": 0.9489,
          "std": 13.59,
          "std_category": 0.1417,
          "sharpe_ratio": 1.04,
          "sharpe_ratio_category": 0.0091,
          "treynor_ratio": 14.19,
          "treynor_ratio_category": 0.125
        }
      ],
      "valuation_metrics": {
        "price_to_earnings": 26.46,
        "price_to_earnings_category": 26.32,
        "price_to_book": 4.42,
        "price_to_book_category": 4.98,
        "price_to_sales": 2.96,
        "price_to_sales_category": 2.79,
        "price_to_cashflow": 17.57,
        "price_to_cashflow_category": 17.61,
        "median_market_capitalization": 197452,
        "median_market_capitalization_category": 265875,
        "3_year_earnings_growth": 18.72,
        "3_year_earnings_growths_category": 19.53
      }
    }
  },
  "status": "ok"
}

HTTP route

/mutual_funds/world/risk

API credits

200 per request

API parameters

Parameter Details
symbol • Required parameter
• Symbol ticker of mutual fund
figi • Parameter is optional
• Filter by financial instrument global identifier (FIGI)
country • Parameter is optional
• Filter by country name or alpha code
dp • Parameter is optional
• Number of decimal places for floating values
• Accepts value in range [0,11]; default 5
apikey • Required parameter
• Your API key upgraded to the Enterprise plan or above

Response

Key Description
volatility_measures.period period of a measure
volatility_measures.alpha alpha score of a fund
volatility_measures.alpha_category average alpha score of a fund's category
volatility_measures.beta beta score of a fund
volatility_measures.beta_category average beta score of a fund's category
volatility_measures.mean_annual mean annual return of a fund
volatility_measures.mean_annual_category average mean annual return of a fund's category
volatility_measures.r_squared r-squared metric of a fund
volatility_measures.r_squared_category average r-squared metric of a fund's category
volatility_measures.std standard deviation of a fund
volatility_measures.std_category average standard deviation of a fund's category
volatility_measures.sharpe_ratio sharpe ratio of a fund
volatility_measures.sharpe_ratio_category average sharpe ratio of a fund's category
volatility_measures.treynor_ratio treynor ratio of a fund
volatility_measures.treynor_ratio_category average treynor ratio of a fund's category
valuation_metrics.price_to_earnings fund price to earnings metric
valuation_metrics.price_to_earnings_category average price to earnings metric of funds in the same category
valuation_metrics.price_to_book fund price to book metric
valuation_metrics.price_to_book_category average price to book metric of funds in the same category
valuation_metrics.price_to_sales fund price to sales metric
valuation_metrics.price_to_sales_category average price to sales metric of funds in the same category
valuation_metrics.price_to_cashflow fund price to cashflow metric
valuation_metrics.price_to_cashflow_category average price to cashflow metric of funds in the same category
valuation_metrics.median_market_capitalization median market capitalization of a fund
valuation_metrics.median_market_capitalization_category median market capitalization of funds in the same category
valuation_metrics.3_year_earnings_growth earnings growth over the last three years
valuation_metrics.3_year_earnings_growth_category earnings growth over the last three years of funds in the same category

JSON request example

https://api.twelvedata.com/mutual_funds/world/risk?symbol=VFIAX&apikey=demo

Ratings

This API request returns ratings of a mutual fund.

HTTP request example

https://api.twelvedata.com/mutual_funds/world/ratings?symbol=VFIAX&apikey=your_api_key

This request will return JSON with the following structure

{
  "mutual_fund": {
    "ratings": {
      "performance_rating": 5,
      "risk_rating": 3,
      "return_rating": 4
    }
  },
  "status": "ok"
}

HTTP route

/mutual_funds/world/ratings

API credits

1000 per request

API parameters

Parameter Details
symbol • Required parameter
• Symbol ticker of mutual fund
figi • Parameter is optional
• Filter by financial instrument global identifier (FIGI)
country • Parameter is optional
• Filter by country name or alpha code
dp • Parameter is optional
• Number of decimal places for floating values
• Accepts value in range [0,11]; default 5
apikey • Required parameter
• Your API key upgraded to the Enterprise plan or above

Response

Key Description
performance_rating performance rating from 0 to 5
risk_rating risk rating from 0 to 5
return_rating return rating from 0 to 5

JSON request example

https://api.twelvedata.com/mutual_funds/world/ratings?symbol=VFIAX&apikey=demo

CompositionHigh Demand

This API request returns portfolio composition of a mutual fund, including sectors, holding details, weighted exposure, and others.

HTTP request example

https://api.twelvedata.com/mutual_funds/world/composition?symbol=VFIAX&apikey=your_api_key

This request will return JSON with the following structure

{
  "mutual_fund": {
    "composition": {
      "major_market_sectors": [
        {
          "sector": "Technology",
          "weight": 0.24239
        },
        {
          "sector": "Financial Services",
          "weight": 0.142
        },
        {
          "sector": "Healthcare",
          "weight": 0.131
        },
        {
          "sector": "Consumer Cyclical",
          "weight": 0.1201
        },
        {
          "sector": "Communication Services",
          "weight": 0.1114
        },
        {
          "sector": "Industrials",
          "weight": 0.08859
        },
        {
          "sector": "Consumer Defensive",
          "weight": 0.06320
        },
        {
          "sector": "Energy",
          "weight": 0.02839
        },
        {
          "sector": "Realestate",
          "weight": 0.02579
        },
        {
          "sector": "Utilities",
          "weight": 0.0243
        },
        {
          "sector": "Basic Materials",
          "weight": 0.0227
        }
      ],
      "asset_allocation": {
        "cash": 0.0004,
        "stocks": 0.9996,
        "preferred_stocks": 0,
        "convertables": 0,
        "bonds": 0,
        "others": 0
      },
      "top_holdings": [
        {
          "symbol": "AAPL",
          "name": "Apple Inc",
          "weight": 0.0592
        },
        {
          "symbol": "MSFT",
          "name": "Microsoft Corp",
          "weight": 0.05619
        },
        {
          "symbol": "AMZN",
          "name": "Amazon.com Inc",
          "weight": 0.04059
        },
        {
          "symbol": "FB",
          "name": "Facebook Inc Class A",
          "weight": 0.0229
        },
        {
          "symbol": "GOOGL",
          "name": "Alphabet Inc Class A",
          "weight": 0.0202
        },
        {
          "symbol": "GOOG",
          "name": "Alphabet Inc Class C",
          "weight": 0.0197
        },
        {
          "symbol": "BRK.B",
          "name": "Berkshire Hathaway Inc Class B",
          "weight": 0.0144
        },
        {
          "symbol": "TSLA",
          "name": "Tesla Inc",
          "weight": 0.0144
        },
        {
          "symbol": "NVDA",
          "name": "NVIDIA Corp",
          "weight": 0.0137
        },
        {
          "symbol": "JPM",
          "name": "JPMorgan Chase & Co",
          "weight": 0.01299
        }
      ],
      "bond_breakdown": {
        "average_maturity": {
          "fund": null,
          "category": null
        },
        "average_duration": {
          "fund": null,
          "category": -1.15
        },
        "credit_quality": [
          {
            "grade": "U.S. Government",
            "weight": 0
          },
          {
            "grade": "AAA",
            "weight": 0
          },
          {
            "grade": "AA",
            "weight": 0
          },
          {
            "grade": "A",
            "weight": 0
          },
          {
            "grade": "BBB",
            "weight": 0
          },
          {
            "grade": "BB",
            "weight": 0
          },
          {
            "grade": "B",
            "weight": 0
          },
          {
            "grade": "Below B",
            "weight": 0
          },
          {
            "grade": "Not Rated",
            "weight": 0
          }
        ]
      }
    }
  },
  "status": "ok"
}

HTTP route

/mutual_funds/world/composition

API credits

200 per request

API parameters

Parameter Details
symbol • Required parameter
• Symbol ticker of mutual fund
figi • Parameter is optional
• Filter by financial instrument global identifier (FIGI)
country • Parameter is optional
• Filter by country name or alpha code
dp • Parameter is optional
• Number of decimal places for floating values
• Accepts value in range [0,11]; default 5
apikey • Required parameter
• Your API key upgraded to the Enterprise plan or above

Response

Key Description
major_market_sectors.sector sector category of a fund exposure
major_market_sectors.weight weight (%) of a fund exposure in a sector
asset_allocation.cash percentage of overall portfolio composition in cash
asset_allocation.stocks percentage of overall portfolio composition in stocks
asset_allocation.preferred_stocks percentage of overall portfolio composition in preferred stocks
asset_allocation.convertables percentage of overall portfolio composition in convertable securities
asset_allocation.bonds percentage of overall portfolio composition in bond
asset_allocation.others percentage of overall portfolio composition in other forms of holding
top_holdings.symbol symbol ticker of a holding instrument
top_holdings.name name of a holding instrument
top_holdings.weight weight (%) of a holding instrument in overall portfolio composition
bond_breakdown.average_maturity.fund average maturity of bond holding of a fund
bond_breakdown.average_maturity.category average maturity of bond holding of funds in the same category
bond_breakdown.average_duration.fund average duration of bond holding of a fund
bond_breakdown.average_duration.category average duration of bond holding of funds in the same category
bond_breakdown.credit_quality.grade rating of bond holding of a fund from AAA to below B
bond_breakdown.credit_quality.weight weight of bond holding in fund portfolio

JSON request example

https://api.twelvedata.com/mutual_funds/world/composition?symbol=VFIAX&apikey=demo

Purchase Info

This API request returns essential information on purchasing a mutual fund, including minimums, pricing, and available brokerages.

HTTP request example

https://api.twelvedata.com/mutual_funds/world/purchase_info?symbol=VFIAX&apikey=your_api_key

This request will return JSON with the following structure

{
  "mutual_fund": {
    "purchase_info": {
      "expenses": {
        "expense_ratio_gross": 0.0004,
        "expense_ratio_net": 0.0004
      },
      "minimums": {
        "initial_investment": 3000,
        "additional_investment": 1,
        "initial_ira_investment": null,
        "additional_ira_investment": null
      },
      "pricing": {
        "nav": 411.2,
        "12_month_low": 360.14,
        "12_month_high": 442.63,
        "last_month": 404.56
      },
      "brokerages": [
        "ADP Access",
        "ADP Access IPS Z",
        "ADP Access Open Fund Architecture",
        "ADP Access Tier 0",
        "ADP Advisor Access 3(21) Tier 0",
        "ADP Advisor Access Tier 0",
        "Allowab (non-advisory)",
        "Ameriprise Brokerage",
        "Avantax",
        "Bear Stearns",
        "Bear Stearns No-Load Transaction Fee",
        "Cetera Advisor Networks LLC",
        "Cetera Advisor Networks LLC- PAM, PRIME, Premier",
        "Cetera Advisors LLC",
        "Cetera Advisors LLC- PAM, PRIME, Premier",
        "Cetera Financial Specialists LLC- Premier",
        "Comerica Bank",
        "CommonWealth PPS",
        "Commonwealth (PPS Access Program)",
        "Commonwealth (PPS/Advisory)",
        "Commonwealth Universe",
        "DailyAccess Corporation FRIAG",
        "DailyAccess Corporation MATC",
        "DailyAccess Corporation Matrix",
        "DailyAccess Corporation Mid-Atlantic",
        "DailyAccess Corporation RTC",
        "DATALynx",
        "DWS Retirement Sevs Investment Offerings",
        "E TRADE Financial",
        "ETrade No Load Fee",
        "Federated TrustConnect",
        "Fidelity Institutional FundsNetwork",
        "Fidelity Retail FundsNetwork",
        "H Beck Inc.",
        "HD Vest",
        "HD Vest - Vest Advisor",
        "H&R Block Financial Advisors Inc",
        "JPMorgan",
        "JPMorgan INVEST",
        "JP MORGAN LOAD",
        "JP MORGAN NO-LOAD NTF",
        "JP MORGAN NO-LOAD TRANSACTION FEE",
        "Lincoln Investment Planning",
        "LPL SAM Eligible - 6.18.2020",
        "LPL SWM - 6.18.2020",
        "Matrix Financial Solutions",
        "Merrill Lynch",
        "Met Life Resources MFSP Alliance List",
        "Mid Atlantic Capital Corp",
        "Mid Atlantic Capital Group",
        "Mony Securities Corp",
        "Morgan Stanley - Brokerage Accounts",
        "Morgan Stanley Consulting Group Advisor",
        "Morgan Stanley Portfolio Management",
        "MSSB PlanPremier",
        "MSSB PlanPremierTPA",
        "MSWM Brokerage",
        "Nationwide Retirement Clear Adva",
        "Nationwide Retirement Flexible Advantage",
        "Nationwide Retirement Resource",
        "NM WMC",
        "Northwestern Mutual Inv Srvc, LLC",
        "NYLIM 401(k) Complete",
        "Pershing Retirement Plan Network",
        "Principal Advantage",
        "Protected Investors of America",
        "Pruco Securities LLC -PruUMA’s Mutual Funds",
        "Raymond James",
        "Raymond James WRAP Eligible",
        "RBC Wealth Management-Network Eligible",
        "RBC Wealth Management-Wrap Eligible",
        "Robert W. Baird & Co.",
        "Schwab All (Retail, Instl, Retirement)",
        "Schwab Existing Shareholders Only",
        "Schwab Institutional",
        "Schwab Institutional Only",
        "Schwab Retail",
        "Scottrade Load",
        "Scottrade NTF",
        "Scottrade TF",
        "Securities America Advisors",
        "Securities America Inc.",
        "Sterne, Agee & Leach, Inc.,",
        "SunGard Transaction Network",
        "Td Ameritrade, Inc.",
        "TD Ameritrade Institutional",
        "TD Ameritrade Institutional NTF",
        "TD Ameritrade Retail",
        "TD Ameritrade Retail NTF",
        "TD Ameritrade Trust Company",
        "Thrivent   Advisory Eligible",
        "Thrivent   Retail Eligible",
        "Trade PMR NTF",
        "Trade PMR Transaction Fee",
        "TradeStation Securities",
        "TRUSTlynx",
        "Vanguard Load",
        "Vanguard NTF",
        "Vanguard TF",
        "Waddell & Reed Choice MAP Flex",
        "WFA Fdntl Choice/PIM Updated 6.1.21",
        "WFA MF Advisory Updated 6.1.21",
        "WR Hambrecht Co LLC"
      ]
    }
  },
  "status": "ok"
}

HTTP route

/mutual_funds/world/purchase_info

API credits

200 per request

API parameters

Parameter Details
symbol • Required parameter
• Symbol ticker of mutual fund
figi • Parameter is optional
• Filter by financial instrument global identifier (FIGI)
country • Parameter is optional
• Filter by country name or alpha code
dp • Parameter is optional
• Number of decimal places for floating values
• Accepts value in range [0,11]; default 5
apikey • Required parameter
• Your API key upgraded to the Enterprise plan or above

Response

Key Description
expenses.expense_ratio_gross annual cost of investing in a mutual fund
expenses.expense_ratio_net percentage of mutual fund assets steered toward a fund's operating expenses and fund management fees
minimums.initial_investment investment minimum
minimums.additional_investment minimum amount of additional investment
minimums.initial_ira_investment investment minimum for IRA
minimums.additional_ira_investment minimum amount of additional investment for IRA
pricing.nav last price of the fund
pricing.12_month_low lowest price of the fund over the last year
pricing.12_month_high highest price of the fund over the last year
pricing.last_month fund price at the end of the last month
brokerages list of brokerages where mutual fund can be purchased

JSON request example

https://api.twelvedata.com/mutual_funds/world/purchase_info?symbol=VFIAX&apikey=demo

Sustainability

This API request returns brief information on mutual fund sustainability and ESG.

HTTP request example

https://api.twelvedata.com/mutual_funds/world/sustainability?symbol=VFIAX&apikey=your_api_key

This request will return JSON with the following structure

{
  "mutual_fund": {
    "sustainability": {
      "score": 22,
      "corporate_esg_pillars": {
        "environmental": 3.73,
        "social": 10.44,
        "governance": 7.86
      },
      "sustainable_investment": false,
      "corporate_aum": 0.99486
    }
  },
  "status": "ok"
}

HTTP route

/mutual_funds/world/sustainability

API credits

200 per request

API parameters

Parameter Details
symbol • Required parameter
• Symbol ticker of mutual fund
figi • Parameter is optional
• Filter by financial instrument global identifier (FIGI)
country • Parameter is optional
• Filter by country name or alpha code
dp • Parameter is optional
• Number of decimal places for floating values
• Accepts value in range [0,11]; default 5
apikey • Required parameter
• Your API key upgraded to the Enterprise plan or above

Response

Key Description
sustainability.score asset-weighted average of normalized company-level ESG Scores for the covered holdings in the portfolio from 0 to 100
corporate_esg_pillars.environmental ESG environmental score
corporate_esg_pillars.social ESG social score
corporate_esg_pillars.governance ESG governance score
sustainable_investment indication that the fund discloses in their prospectus that they employ socially responsible or ESG principles in their investment selection processes
corporate_aum percentage of AUM used to calculate sustainability score

JSON request example

https://api.twelvedata.com/mutual_funds/world/sustainability?symbol=VFIAX&apikey=demo

ETFs

ETFs ListUseful

This API request returns a list of exchange traded funds available at Twelve Data. Sorting is in descending order by total assets value. The list is updated daily.

HTTP request example

https://api.twelvedata.com/etfs/list?apikey=your_api_key

This request will return JSON with the following structure

{
  "result": {
    "count": 1000,
    "list": [
        {
          "symbol": "IVV",
          "name": "iShares Core S&P 500 ETF",
          "country": "United States",
          "mic_code": "XNAS",
          "fund_family": "iShares",
          "fund_type": "Large Blend",
        },
        {...}
    ]
  },
  "status": "ok"
}

HTTP route

/etfs/list

API credits

1 per request

API parameters

Parameter Details
symbol • Parameter is optional
• Filter by symbol
figi • Parameter is optional
• Filter by financial instrument global identifier (FIGI)
country • Parameter is optional
• Filter by country name or alpha code
fund_family • Parameter is optional
• Filter by investment company that manages the fund
fund_type • Parameter is optional
• Filter by the type of fund
page • Parameter is optional
• Page number; default 1
outputsize • Parameter is optional
• Number of records in response; default 50
apikey • Required parameter
• Your API key at the Basic plan or above

Response

Key Description
count total number of matching funds
symbol fund symbol ticker
name fund name
country country of fund incorporation
mic_code market identifier code (MIC) under ISO 10383 standard
fund_family investment company that manages the fund
fund_type type of fund

JSON request example

https://api.twelvedata.com/etfs/list?apikey=demo

https://api.twelvedata.com/etfs/list?fund_family=Vanguard&apikey=demo

Downloadable CSV example

https://api.twelvedata.com/etfs/list?format=CSV&apikey=demo

ETFs Family List

This API request returns a list of exchange traded funds families.

HTTP request example

https://api.twelvedata.com/etfs/family?apikey=your_api_key

This request will return JSON with the following structure

{
  "result": {
    "India": [
      "Aberdeen Standard Fund Managers Limited",
      "Aditya Birla Sun Life AMC Ltd",
      "Aditya Birla Sun Life Insurance Company Limited",
      "Aegon Life Insurance Company Ltd.",
      "Aviva Life Insur Co. India Pvt. Ltd.",
      "Axis Asset Management Company Limited",
      "Bajaj Allianz Life Insurance Company Ltd",
      "Baring International Fund Mgrs (Ireland) Limited",
      "Baroda Asset Management India Limited"
    ],
    "United States": [
      "Aegon Asset Management UK PLC",
      "Ampega Investment GmbH",
      "Aviva SpA",
      "BBVA Asset Management SA SGIIC",
      "Caser Pensiones EGFP",
      "HSBC Investment Funds (HK) Limited",
      "Premier Portfolio Managers Limited",
      "SEI Investments Global Limited",
      "Vanguard"
    ]
  },
  "status": "ok"
}

HTTP route

/etfs/family

API credits

1 per request

API parameters

Parameter Details
country • Parameter is optional
• Filter by country name or alpha code
fund_family • Parameter is optional
• Filter by investment company that manages the fund
apikey • Required parameter
• Your API key at the Basic plan or above

Response

Key Description
result all available fund families segmented by country

JSON request example

https://api.twelvedata.com/etfs/family?apikey=demo

https://api.twelvedata.com/etfs/family?country=US&apikey=demo

Downloadable CSV example

https://api.twelvedata.com/etfs/family?format=CSV&apikey=demo

ETFs Type List

This API request returns a list of exchange traded funds types.

HTTP request example

https://api.twelvedata.com/etfs/type?apikey=your_api_key

This request will return JSON with the following structure

{
  "result": {
    "Singapore": [
      "Property - Indirect Asia",
      "Sector Equity Water",
      "SGD Bond",
      "Singapore Equity",
      "Taiwan Large-Cap Equity"
    ],
    "United States": [
      "Asia-Pacific ex-Japan Equity",
      "EUR Flexible Allocation - Global",
      "Euro Short Bond PP",
      "Large Blend",
      "Other Allocation"
    ]
  },
  "status": "ok"
}

HTTP route

/etfs/type

API credits

1 per request

API parameters

Parameter Details
country • Parameter is optional
• Filter by country name or alpha code
fund_type • Parameter is optional
• Filter by the type of fund
apikey • Required parameter
• Your API key at the Basic plan or above

Response

Key Description
result all available fund types segmented by country

JSON request example

https://api.twelvedata.com/etfs/type?apikey=demo

https://api.twelvedata.com/etfs/type?country=US&apikey=demo

Downloadable CSV example

https://api.twelvedata.com/etfs/type?format=CSV&apikey=demo

All dataHigh Demand

This API request returns a complete breakdown of a etf, including summary, performance, risk and composition.

HTTP request example

https://api.twelvedata.com/etfs/world?symbol=IVV&apikey=your_api_key

This request will return JSON with the following structure

{
  "etf": {
    "summary": {
      "symbol": "IVV",
      "name": "iShares Core S&P 500 ETF",
      "fund_family": "iShares",
      "fund_type": "Large Blend",
      "currency": "USD",
      "share_class_inception_date": "2000-11-13",
      "ytd_return": -0.0537,
      "expense_ratio_net": -0.004,
      "yield": 0.0133,
      "nav": 413.24,
      "last_price": 413.24,
      "turnover_rate": 0.04,
      "net_assets": 753409982464,
      "overview": "The investment seeks to track the performance of the Standard & Poor's 500 Index that measures the investment return of large-capitalization stocks.  The fund employs an indexing investment approach designed to track the performance of the Standard & Poor's 500 Index, a widely recognized benchmark of U.S. stock market performance that is dominated by the stocks of large U.S. companies. The advisor attempts to replicate the target index by investing all, or substantially all, of its assets in the stocks that make up the index, holding each stock in approximately the same proportion as its weighting in the index."
    },
    "performance": {
      "trailing_returns": [
        {
          "period": "ytd",
          "share_class_return": -0.0751,
          "category_return": 0.1484
        }
      ],
      "annual_total_returns": [
        {
          "year": "2021",
          "share_class_return": 0.2866,
          "category_return": null
        }
      ]
    },
    "risk": {
      "volatility_measures": [
        {
          "period": "3_year",
          "alpha": -0.03,
          "alpha_category": -0.02,
          "beta": 1,
          "beta_category": 0.01,
          "mean_annual_return": 1.58,
          "mean_annual_return_category": 0.01,
          "r_squared": 100,
          "r_squared_category": 0.95,
          "std": 18.52,
          "std_category": 0.19,
          "sharpe_ratio": 0.95,
          "sharpe_ratio_category": 0.01,
          "treynor_ratio": 17.41,
          "treynor_ratio_category": 0.16
        }
      ],
      "valuation_metrics": {
        "price_to_earnings": 26.46,
        "price_to_book": 4.42,
        "price_to_sales": 2.96,
        "price_to_cashflow": 17.57
      }
    },
    "composition": {
      "major_market_sectors": [
        {
          "sector": "Technology",
          "weight": 0.2424
        }
      ],
      "country_allocation": [
        {
          "country": "United Kingdom",
          "allocation": 0.9855
        },
        {
          "country": "India",
          "allocation": 0.0045
        }
      ],
      "asset_allocation": {
        "cash": 0.0004,
        "stocks": 0.9996,
        "preferred_stocks": 0,
        "convertables": 0,
        "bonds": 0,
        "others": 0
      },
      "top_holdings": [
        {
          "symbol": "AAPL",
          "name": "Apple Inc",
          "weight": 0.0592
        }
      ],
      "bond_breakdown": {
        "average_maturity": {
          "fund": 6.65,
          "category": 7.81
        },
        "average_duration": {
          "fund": 5.72,
          "category": 5.64
        },
        "credit_quality": [
          {
            "grade": "AAA",
            "weight": 0
          }
        ]
      }
    }
  },
  "status": "ok"
}

HTTP route

/etfs/world

API credits

800 per request

API parameters

Parameter Details
symbol • Required parameter
• Symbol ticker of etf
figi • Parameter is optional
• Filter by financial instrument global identifier (FIGI)
country • Parameter is optional
• Filter by country name or alpha code
dp • Parameter is optional
• Number of decimal places for floating values
• Accepts value in range [0,11]; default 5
apikey • Required parameter
• Your API key upgraded to the Enterprise plan or above

Response

Key Description
symbol all available fund types segmented by country
name fund name
fund_family investment company that manages the fund
fund_type type of the fund
currency currency of fund price
share_class_inception_date the date from which the fund started operations and the returns are calculated
ytd_return percentage of profit of the fund since the first trading day of the current calendar year
expense_ratio_net percentage of etf assets steered toward a fund's operating expenses and fund management fees
yield income returned to its investors through interest and dividends generated by the fund's investments
nav last price of the fund
last_price last price of the fund
min_investment investment minimum
turnover_rate percentage rate at which etf replaces its holdings on investment every year
net_assets total assets of a fund minus its total liabilities
overview description of the fund
people.name manager name
people.tenure_since manager tenuring date
trailing_returns.period period of trailing returns
trailing_returns.share_class_return fund returns (%) generated over a given period
trailing_returns.category_return same category average returns (%) generated over a given period
annual_total_returns.year year of total returns
annual_total_returns.share_class_return fund total returns (%) generated over a given year
annual_total_returns.category_return same category average total returns (%) generated over a given year
volatility_measures.period period of a measure
volatility_measures.alpha alpha score of a fund
volatility_measures.alpha_category average alpha score of a fund's category
volatility_measures.beta beta score of a fund
volatility_measures.beta_category average beta score of a fund's category
volatility_measures.mean_annual mean annual return of a fund
volatility_measures.mean_annual_category average mean annual return of a fund's category
volatility_measures.r_squared r-squared metric of a fund
volatility_measures.r_squared_category average r-squared metric of a fund's category
volatility_measures.std standard deviation of a fund
volatility_measures.std_category average standard deviation of a fund's category
volatility_measures.sharpe_ratio sharpe ratio of a fund
volatility_measures.sharpe_ratio_category average sharpe ratio of a fund's category
volatility_measures.treynor_ratio treynor ratio of a fund
volatility_measures.treynor_ratio_category average treynor ratio of a fund's category
valuation_metrics.price_to_earnings fund price to earnings metric
valuation_metrics.price_to_earnings_category average price to earnings metric of funds in the same category
valuation_metrics.price_to_book fund price to book metric
valuation_metrics.price_to_book_category average price to book metric of funds in the same category
valuation_metrics.price_to_sales fund price to sales metric
valuation_metrics.price_to_sales_category average price to sales metric of funds in the same category
valuation_metrics.price_to_cashflow fund price to cashflow metric
valuation_metrics.price_to_cashflow_category average price to cashflow metric of funds in the same category
valuation_metrics.median_market_capitalization median market capitalization of a fund
valuation_metrics.median_market_capitalization_category median market capitalization of funds in the same category
valuation_metrics.3_year_earnings_growth earnings growth over the last three years
valuation_metrics.3_year_earnings_growth_category earnings growth over the last three years of funds in the same category
major_market_sectors.sector sector category of a fund exposure
major_market_sectors.weight weight (%) of a fund exposure in a sector
country_allocation.country country name
country_allocation.allocation percentages of a fund's net assets distributed to securities of the country
asset_allocation.cash percentage of overall portfolio composition in cash
asset_allocation.stocks percentage of overall portfolio composition in stocks
asset_allocation.preferred_stocks percentage of overall portfolio composition in preferred stocks
asset_allocation.convertables percentage of overall portfolio composition in convertable securities
asset_allocation.bonds percentage of overall portfolio composition in bond
asset_allocation.others percentage of overall portfolio composition in other forms of holding
top_holdings.symbol symbol ticker of a holding instrument
top_holdings.name name of a holding instrument
top_holdings.weight weight (%) of a holding instrument in overall portfolio composition
bond_breakdown.average_maturity.fund average maturity of bond holding of a fund
bond_breakdown.average_maturity.category average maturity of bond holding of funds in the same category
bond_breakdown.average_duration.fund average duration of bond holding of a fund
bond_breakdown.average_duration.category average duration of bond holding of funds in the same category
bond_breakdown.credit_quality.grade rating of bond holding of a fund from AAA to below B
bond_breakdown.credit_quality.weight weight of bond holding in fund portfolio

JSON request example

https://api.twelvedata.com/etfs/world?symbol=QQQ&apikey=demo

Summary

This API request returns a brief summary of a etf.

HTTP request example

https://api.twelvedata.com/etfs/world/summary?symbol=IVV&apikey=your_api_key

This request will return JSON with the following structure

{
  "etf": {
    "summary": {
      "symbol": "IVV",
      "name": "iShares Core S&P 500 ETF",
      "fund_family": "iShares",
      "fund_type": "Large Blend",
      "currency": "USD",
      "share_class_inception_date": "2000-11-13",
      "ytd_return": -0.0537,
      "expense_ratio_net": -0.004,
      "yield": 0.0133,
      "nav": 413.24,
      "last_price": 413.24,
      "turnover_rate": 0.04,
      "net_assets": 753409982464,
      "overview": "The investment seeks to track the performance of the Standard & Poor's 500 Index that measures the investment return of large-capitalization stocks.  The fund employs an indexing investment approach designed to track the performance of the Standard & Poor's 500 Index, a widely recognized benchmark of U.S. stock market performance that is dominated by the stocks of large U.S. companies. The advisor attempts to replicate the target index by investing all, or substantially all, of its assets in the stocks that make up the index, holding each stock in approximately the same proportion as its weighting in the index."
    }
  },
  "status": "ok"
}

HTTP route

/etfs/world/summary

API credits

200 per request

API parameters

Parameter Details
symbol • Required parameter
• Symbol ticker of etf
figi • Parameter is optional
• Filter by financial instrument global identifier (FIGI)
country • Parameter is optional
• Filter by country name or alpha code
dp • Parameter is optional
• Number of decimal places for floating values
• Accepts value in range [0,11]; default 5
apikey • Required parameter
• Your API key upgraded to the Enterprise plan or above

Response

Key Description
symbol all available fund types segmented by country
name fund name
fund_family investment company that manages the fund
fund_type type of the fund
currency currency of fund price
share_class_inception_date the date from which the fund started operations and the returns are calculated
ytd_return percentage of profit of the fund since the first trading day of the current calendar year
expense_ratio_net percentage of etf assets steered toward a fund's operating expenses and fund management fees
yield income returned to its investors through interest and dividends generated by the fund's investments
nav last price of the fund
last_price last price of the fund
min_investment investment minimum
turnover_rate percentage rate at which etf replaces its holdings on investment every year
net_assets total assets of a fund minus its total liabilities
overview description of the fund
people.name manager name
people.tenure_since manager tenuring date

JSON request example

https://api.twelvedata.com/etfs/world/summary?symbol=QQQ&apikey=demo

PerformanceHigh Demand

This API request returns detailed performance of a etf, including trailing and annual returns.

HTTP request example

https://api.twelvedata.com/etfs/world/performance?symbol=IVV&apikey=your_api_key

This request will return JSON with the following structure

{
  "etf": {
    "performance": {
      "performance": {
        "trailing_returns": [
          {
            "period": "ytd",
            "share_class_return": -0.0751,
            "category_return": 0.1484
          }
        ],
        "annual_total_returns": [
          {
            "year": "2021",
            "share_class_return": 0.2866,
            "category_return": null
          }
        ]
      }
    }
  },
  "status": "ok"
}

HTTP route

/etfs/world/performance

API credits

200 per request

API parameters

Parameter Details
symbol • Required parameter
• Symbol ticker of etf
figi • Parameter is optional
• Filter by financial instrument global identifier (FIGI)
country • Parameter is optional
• Filter by country name or alpha code
dp • Parameter is optional
• Number of decimal places for floating values
• Accepts value in range [0,11]; default 5
apikey • Required parameter
• Your API key upgraded to the Enterprise plan or above

Response

Key Description
trailing_returns.period period of trailing returns
trailing_returns.share_class_return fund returns (%) generated over a given period
trailing_returns.category_return same category average returns (%) generated over a given period
annual_total_returns.year year of total returns
annual_total_returns.share_class_return fund total returns (%) generated over a given year
annual_total_returns.category_return same category average total returns (%) generated over a given year

JSON request example

https://api.twelvedata.com/etfs/world/performance?symbol=QQQ&apikey=demo

Risk

This API request returns core metrics to measure the risk of investing in a etf.

HTTP request example

https://api.twelvedata.com/etfs/world/risk?symbol=IVV&apikey=your_api_key

This request will return JSON with the following structure

{
  "etf": {
    "risk": {
      "volatility_measures": [
        {
          "period": "3_year",
          "alpha": -0.03,
          "alpha_category": -0.02,
          "beta": 1,
          "beta_category": 0.01,
          "mean_annual_return": 1.58,
          "mean_annual_return_category": 0.01,
          "r_squared": 100,
          "r_squared_category": 0.95,
          "std": 18.52,
          "std_category": 0.19,
          "sharpe_ratio": 0.95,
          "sharpe_ratio_category": 0.01,
          "treynor_ratio": 17.41,
          "treynor_ratio_category": 0.16
        }
      ],
      "valuation_metrics": {
        "price_to_earnings": 26.46,
        "price_to_book": 4.42,
        "price_to_sales": 2.96,
        "price_to_cashflow": 17.57
      }
    }
  },
  "status": "ok"
}

HTTP route

/etfs/world/risk

API credits

200 per request

API parameters

Parameter Details
symbol • Required parameter
• Symbol ticker of etf
figi • Parameter is optional
• Filter by financial instrument global identifier (FIGI)
country • Parameter is optional
• Filter by country name or alpha code
dp • Parameter is optional
• Number of decimal places for floating values
• Accepts value in range [0,11]; default 5
apikey • Required parameter
• Your API key upgraded to the Enterprise plan or above

Response

Key Description
volatility_measures.period period of a measure
volatility_measures.alpha alpha score of a fund
volatility_measures.alpha_category average alpha score of a fund's category
volatility_measures.beta beta score of a fund
volatility_measures.beta_category average beta score of a fund's category
volatility_measures.mean_annual mean annual return of a fund
volatility_measures.mean_annual_category average mean annual return of a fund's category
volatility_measures.r_squared r-squared metric of a fund
volatility_measures.r_squared_category average r-squared metric of a fund's category
volatility_measures.std standard deviation of a fund
volatility_measures.std_category average standard deviation of a fund's category
volatility_measures.sharpe_ratio sharpe ratio of a fund
volatility_measures.sharpe_ratio_category average sharpe ratio of a fund's category
volatility_measures.treynor_ratio treynor ratio of a fund
volatility_measures.treynor_ratio_category average treynor ratio of a fund's category
valuation_metrics.price_to_earnings fund price to earnings metric
valuation_metrics.price_to_earnings_category average price to earnings metric of funds in the same category
valuation_metrics.price_to_book fund price to book metric
valuation_metrics.price_to_book_category average price to book metric of funds in the same category
valuation_metrics.price_to_sales fund price to sales metric
valuation_metrics.price_to_sales_category average price to sales metric of funds in the same category
valuation_metrics.price_to_cashflow fund price to cashflow metric
valuation_metrics.price_to_cashflow_category average price to cashflow metric of funds in the same category
valuation_metrics.median_market_capitalization median market capitalization of a fund
valuation_metrics.median_market_capitalization_category median market capitalization of funds in the same category
valuation_metrics.3_year_earnings_growth earnings growth over the last three years
valuation_metrics.3_year_earnings_growth_category earnings growth over the last three years of funds in the same category

JSON request example

https://api.twelvedata.com/etfs/world/risk?symbol=QQQ&apikey=demo

CompositionHigh Demand

This API request returns portfolio composition of a etf, including sectors, holding details, weighted exposure, and others.

HTTP request example

https://api.twelvedata.com/etfs/world/composition?symbol=IVV&apikey=your_api_key

This request will return JSON with the following structure

{
  "etf": {
    "composition": {
      "major_market_sectors": [
        {
          "sector": "Technology",
          "weight": 0.2424
        }
      ],
      "country_allocation": [
        {
          "country": "United Kingdom",
          "allocation": 0.9855
        },
        {
          "country": "India",
          "allocation": 0.0045
        }
      ],
      "asset_allocation": {
        "cash": 0.0004,
        "stocks": 0.9996,
        "preferred_stocks": 0,
        "convertables": 0,
        "bonds": 0,
        "others": 0
      },
      "top_holdings": [
        {
          "symbol": "AAPL",
          "name": "Apple Inc",
          "weight": 0.0592
        }
      ],
      "bond_breakdown": {
        "average_maturity": {
          "fund": 6.65,
          "category": 7.81
        },
        "average_duration": {
          "fund": 5.72,
          "category": 5.64
        },
        "credit_quality": [
          {
            "grade": "AAA",
            "weight": 0
          }
        ]
      }
    }
  },
  "status": "ok"
}

HTTP route

/etfs/world/composition

API credits

200 per request

API parameters

Parameter Details
symbol • Required parameter
• Symbol ticker of etf
figi • Parameter is optional
• Filter by financial instrument global identifier (FIGI)
country • Parameter is optional
• Filter by country name or alpha code
dp • Parameter is optional
• Number of decimal places for floating values
• Accepts value in range [0,11]; default 5
apikey • Required parameter
• Your API key upgraded to the Enterprise plan or above

Response

Key Description
major_market_sectors.sector sector category of a fund exposure
major_market_sectors.weight weight (%) of a fund exposure in a sector
country_allocation.country country name
country_allocation.allocation percentages of a fund's net assets distributed to securities of the country
asset_allocation.cash percentage of overall portfolio composition in cash
asset_allocation.stocks percentage of overall portfolio composition in stocks
asset_allocation.preferred_stocks percentage of overall portfolio composition in preferred stocks
asset_allocation.convertables percentage of overall portfolio composition in convertable securities
asset_allocation.bonds percentage of overall portfolio composition in bond
asset_allocation.others percentage of overall portfolio composition in other forms of holding
top_holdings.symbol symbol ticker of a holding instrument
top_holdings.name name of a holding instrument
top_holdings.weight weight (%) of a holding instrument in overall portfolio composition
bond_breakdown.average_maturity.fund average maturity of bond holding of a fund
bond_breakdown.average_maturity.category average maturity of bond holding of funds in the same category
bond_breakdown.average_duration.fund average duration of bond holding of a fund
bond_breakdown.average_duration.category average duration of bond holding of funds in the same category
bond_breakdown.credit_quality.grade rating of bond holding of a fund from AAA to below B
bond_breakdown.credit_quality.weight weight of bond holding in fund portfolio

JSON request example

https://api.twelvedata.com/etfs/world/composition?symbol=QQQ&apikey=demo

Fundamentals

Fundamental data covers a broad range of datasets for US-based and international stock, ETFs, and mutual funds. Including, but not limited to financials, profiles, transactions, and more.

Returns a logo of company, cryptocurrency, or forex pair.

HTTP request example

https://api.twelvedata.com/logo?symbol=AAPL&apikey=your_api_key

https://api.twelvedata.com/logo?symbol=BTC/USD&apikey=your_api_key

https://api.twelvedata.com/logo?symbol=EUR/USD&apikey=your_api_key

This request will return JSON with the following structure

// Equity
{
  "meta": {
    "symbol": "AAPL",
    "name": "Apple Inc",
    "currency": "USD",
    "exchange": "NASDAQ",
    "mic_code": "XNAS",
    "exchange_timezone": "America/New_York"
  },
  "url": "https://api.twelvedata.com/logo/apple.com"
}

// Crypto
{
  "meta": {
    "symbol": "BTC/USD",
  },
  "logo_base": "https://logo.twelvedata.com/crypto/btc.png",
  "logo_quote": "https://logo.twelvedata.com/crypto/usd.png"
}

// Forex
{
  "meta": {
    "symbol": "EUR/USD"
  },
  "logo_base": "https://logo.twelvedata.com/forex/eur.png",
  "logo_quote": "https://logo.twelvedata.com/forex/usd.png"
}

HTTP route

/logo

API credits

1 per symbol

API parameters

Key Type Description
symbol string • Required parameter
• Symbol ticker of the instrument
E.g. AAPL, EUR/USD, ETH/BTC, ...
exchange string • Parameter is optional
• Exchange where instrument is traded
mic_code string • Parameter is optional
• Market Identifier Code (MIC) under ISO 10383 standard
country string • Parameter is optional
• Country where instrument is traded
apikey string • Required parameter
• Your API key, which you can obtain for free here

Response

Key Type Description
url string link to download the logo

JSON request example

https://api.twelvedata.com/logo?symbol=AAPL&apikey=demo

https://api.twelvedata.com/logo?symbol=BTC/USD&apikey=demo

https://api.twelvedata.com/logo?symbol=EUR/USD&apikey=demo

ProfileUseful

Returns general information about the company.

HTTP request example

https://api.twelvedata.com/profile?symbol=AAPL&apikey=your_api_key

This request will return JSON with the following structure

{
  "symbol": "AAPL",
  "name": "Apple Inc",
  "exchange": "NASDAQ",
  "mic_code": "XNAS",
  "sector": "Technology",
  "industry": "Consumer Electronics",
  "employees": 147000,
  "website": "http://www.apple.com",
  "description": "Apple Inc. designs, manufactures, and markets smartphones, personal computers, tablets, wearables, and accessories worldwide. It also sells various related services. The company offers iPhone, a line of smartphones; Mac, a line of personal computers; iPad, a line of multi-purpose tablets; and wearables, home, and accessories comprising AirPods, Apple TV, Apple Watch, Beats products, HomePod, iPod touch, and other Apple-branded and third-party accessories. It also provides AppleCare support services; cloud services store services; and operates various platforms, including the App Store, that allow customers to discover and download applications and digital content, such as books, music, video, games, and podcasts. In addition, the company offers various services, such as Apple Arcade, a game subscription service; Apple Music, which offers users a curated listening experience with on-demand radio stations; Apple News+, a subscription news and magazine service; Apple TV+, which offers exclusive original content; Apple Card, a co-branded credit card; and Apple Pay, a cashless payment service, as well as licenses its intellectual property. The company serves consumers, and small and mid-sized businesses; and the education, enterprise, and government markets. It sells and delivers third-party applications for its products through the App Store. The company also sells its products through its retail and online stores, and direct sales force; and third-party cellular network carriers, wholesalers, retailers, and resellers. Apple Inc. was founded in 1977 and is headquartered in Cupertino, California.",
  "type": "Common Stock",
  "CEO": "Mr. Timothy D. Cook",
  "address": "One Apple Park Way",
  "address2": "Cupertino, CA 95014",
  "city": "Cupertino",
  "zip": "95014",
  "state": "CA",
  "country": "US",
  "phone": "408-996-1010"
}

HTTP route

/profile

API credits

10 per symbol

API parameters

Key Type Description
symbol string • Required parameter
• Symbol ticker of instrument
• For preffered stocks use dot(.) delimiter
E.g. BRK.A or BRK.B will be correct
figi string • Parameter is optional
• Filter by financial instrument global identifier (FIGI)
exchange string • Parameter is optional
• Exchange where instrument is traded
mic_code string • Parameter is optional
• Market Identifier Code (MIC) under ISO 10383 standard
country string • Parameter is optional
• Country where instrument is traded
apikey string • Required parameter
• Your API key upgraded to the Grow plan or above, which can be obtained here

Response

Key Type Description
symbol string Ticker of the company
name string Name of the company
exchange string Exchange name where the company is listed
mic_code string Market Identifier Code (MIC) under ISO 10383 standard
sector string Sector at which the company operates
industry string Industry at which company operates
employees number Number of employees in the company
website string Website of the company
description string Description of the company activities
type string Issue type of the stock
CEO string Name of the CEO of the company
address string Street address of the company if presented
address2 string Secondary address of the company if presented
city string City of the company if presented
zip string ZIP code of the company if presented
state string State of the company if presented
country string Country of the company if presented
phone string Phone number of the company if presented

JSON request example

https://api.twelvedata.com/profile?symbol=AAPL&apikey=demo

Dividends

Returns the amount of dividends paid out for the last 10+ years.

HTTP request example

https://api.twelvedata.com/dividends?symbol=AAPL&apikey=your_api_key

This request will return JSON with the following structure

{
  "meta": {
    "symbol": "AAPL",
    "name": "Apple Inc",
    "currency": "USD",
    "exchange": "NASDAQ",
    "mic_code": "XNAS",
    "exchange_timezone": "America/New_York"
  },
  "dividends": [
    {
      "ex_date": "2021-08-06",
      "amount": 0.22
    }
  ]
}

HTTP route

/dividends

API credits

20 per symbol

API parameters

Key Type Description
symbol string • Required parameter
• Symbol ticker of instrument
• For preffered stocks use dot(.) delimiter
E.g. BRK.A or BRK.B will be correct
figi string • Parameter is optional
• Filter by financial instrument global identifier (FIGI)
exchange string • Parameter is optional
• Exchange where instrument is traded
mic_code string • Parameter is optional
• Market Identifier Code (MIC) under ISO 10383 standard
country string • Parameter is optional
• Country where instrument is traded
range string • Parameter is optional
last - the last dividend - default
1m - one month
3m - three months
6m - six months
ytd - year-to-date
1y - one year
2y - two years
5y - 5 years
full - complete history
start_date string • Parameter is optional
• Format 2006-01-02
end_date string • Parameter is optional
• Format 2006-01-02
apikey string • Required parameter
• Your API key upgraded to the Grow plan or above, which can be obtained here

Response

Key Type Description
ex_date string Stands for the ex date
amount number Stands for the payment amount

JSON request example

https://api.twelvedata.com/dividends?symbol=AAPL&apikey=demo

Dividends calendar

This API method returns dividend data as a calendar for a given date range. To call custom period, use start_date and end_date parameters.

HTTP request example

https://api.twelvedata.com/dividends_calendar?apikey=your_api_key

This request will return JSON with the following structure

[
    {
        "symbol": "MSFT",
        "mic_code": "XNGS",
        "exchange": "NASDAQ",
        "amount": 0.75,
        "ex_date": "2024-02-14"
    },
    {
        "symbol": "AAPL",
        "mic_code": "XNGS",
        "exchange": "NASDAQ",
        "amount": 0.24,
        "ex_date": "2024-02-09"
    },
    {
        "symbol": "MSFT",
        "mic_code": "XNGS",
        "exchange": "NASDAQ",
        "amount": 0.75,
        "ex_date": "2023-11-15"
    },
    {
        "symbol": "AAPL",
        "mic_code": "XNGS",
        "exchange": "NASDAQ",
        "amount": 0.24,
        "ex_date": "2023-11-10"
    },
]

HTTP route

/dividends_calendar

API credits

40 per symbol

API parameters

Key Type Description
exchange string • Parameter is optional
• Exchange where instrument is traded
mic_code string • Parameter is optional
• Market Identifier Code (MIC) under ISO 10383 standard
country string • Parameter is optional
• Country where instrument is traded
start_date string • Parameter is optional
• Format 2006-01-02
end_date string • Parameter is optional
• Format 2006-01-02
outputsize number • Parameter is optional
• Number of data points to retrieve
• Supports values in the range from 1 to 500
• Default 100 when no date parameters are set, otherwise set to maximum
page string • Parameter is optional
• Page number; default 1
apikey string • Required parameter
• Your API key upgraded to the Grow plan or above, which can be obtained here

Response

Key Type Description
symbol string Ticker of the company
mic_code string Market Identifier Code (MIC) under ISO 10383 standard
exchange string Exchange name where the company is listed
ex_date string Stands for the ex date
amount number Stands for the payment amount

JSON request example

https://api.twelvedata.com/dividends_calendar?apikey=your_api_key

Splits

Returns the date and the split factor of shares of the company for the last 10+ years.

HTTP request example

https://api.twelvedata.com/splits?symbol=AAPL&apikey=your_api_key

This request will return JSON with the following structure

{
  "meta": {
    "symbol": "AAPL",
    "name": "Apple Inc",
    "currency": "USD",
    "exchange": "NASDAQ",
    "mic_code": "XNAS",
    "exchange_timezone": "America/New_York"
  },
  "splits": [
    {
      "date": "2020-08-31",
      "description": "4-for-1 split",
      "ratio": 0.25,
      "from_factor": 4,
      "to_factor": 1
    }
  ]
}

HTTP route

/splits

API credits

20 per symbol

API parameters

Key Type Description
symbol string • Required parameter
• Symbol ticker of instrument
• For preffered stocks use dot(.) delimiter
E.g. BRK.A or BRK.B will be correct
figi string • Parameter is optional
• Filter by financial instrument global identifier (FIGI)
exchange string • Parameter is optional
• Exchange where instrument is traded
mic_code string • Parameter is optional
• Market Identifier Code (MIC) under ISO 10383 standard
country string • Parameter is optional
• Country where instrument is traded
range string • Parameter is optional
last - the last split - default
1m - one month
3m - three months
6m - six months
ytd - year-to-date
1y - one year
2y - two years
5y - 5 years
full - complete history
start_date string • Parameter is optional
• Format 2006-01-02
end_date string • Parameter is optional
• Format 2006-01-02
apikey string • Required parameter
• Your API key upgraded to the Grow plan or above, which can be obtained here

Response

Key Type Description
date string Stands for the split date
description string Specification of the split event
ratio number The ratio by which the number of a company's outstanding shares of stock are increased following a stock split. For example, a 4-for-1 split results in four times as many outstanding shares, with each share selling at one forth of its pre-split price
from_factor number To factor of the split
to_factor number From factor of the split

JSON request example

https://api.twelvedata.com/splits?symbol=AAPL&apikey=demo

Splits calendar

This API method returns split data as a calendar for a given date range. To call custom period, use start_date and end_date parameters.

HTTP request example

https://api.twelvedata.com/splits_calendar?apikey=your_api_key

This request will return JSON with the following structure

[
  {
    "date": "2024-04-23",
    "symbol": "AAPL",
    "mic_code": "XNGS",
    "exchange": "NASDAQ",
    "description": "1-for-1 split",
    "ratio": 1,
    "from_factor": 1,
    "to_factor": 1
  },
  {
    "date": "2024-02-23",
    "symbol": "LYT",
    "mic_code": "XNCM",
    "exchange": "NASDAQ",
    "description": "1-for-60 split",
    "ratio": 60,
    "from_factor": 1,
    "to_factor": 60
  },
  {
    "date": "2024-02-21",
    "symbol": "HAUS",
    "mic_code": "BATS",
    "exchange": "CBOE",
    "description": "1-for-10 split",
    "ratio": 10,
    "from_factor": 1,
    "to_factor": 10
  },
  {
    "date": "2024-02-21",
    "symbol": "TRBA",
    "mic_code": "XSTU",
    "exchange": "XSTU",
    "description": "1-for-5 split",
    "ratio": 5,
    "from_factor": 1,
    "to_factor": 5
  }
]

HTTP route

/splits_calendar

API credits

40 per symbol

API parameters

Key Type Description
exchange string • Parameter is optional
• Exchange where instrument is traded
mic_code string • Parameter is optional
• Market Identifier Code (MIC) under ISO 10383 standard
country string • Parameter is optional
• Country where instrument is traded
start_date string • Parameter is optional
• Format 2006-01-02
end_date string • Parameter is optional
• Format 2006-01-02
outputsize number • Parameter is optional
• Number of data points to retrieve
• Supports values in the range from 1 to 500
• Default 100 when no date parameters are set, otherwise set to maximum
page string • Parameter is optional
• Page number; default 1
apikey string • Required parameter
• Your API key upgraded to the Grow plan or above, which can be obtained here

Response

Key Type Description
date string Stands for the split date
symbol string Ticker of the company
mic_code string Market Identifier Code (MIC) under ISO 10383 standard
exchange string Exchange name where the company is listed
description string Specification of the split event
ratio number The ratio by which the number of a company's outstanding shares of stock are increased following a stock split. For example, a 4-for-1 split results in four times as many outstanding shares, with each share selling at one forth of its pre-split price
from_factor number To factor of the split
to_factor number From factor of the split

JSON request example

https://api.twelvedata.com/splits_calendar?apikey=demo

Earnings

This API call returns earnings data for a given company, including EPS estimate and EPS actual. Earnings are available for complete company history.

HTTP request example

https://api.twelvedata.com/earnings?symbol=AAPL&apikey=your_api_key

This request will return JSON with the following structure

{
  "meta": {
    "symbol": "AAPL",
    "name": "Apple Inc",
    "currency": "USD",
    "exchange": "NASDAQ",
    "mic_code": "XNAS",
    "exchange_timezone": "America/New_York"
  },
  "earnings":[
    {
       "date": "2020-04-30",
       "time": "After Hours",
       "eps_estimate": 2.09,
       "eps_actual": 2.55,
       "difference": 0.46,
       "surprise_prc": 22.01
    },
    {
       "date": "2020-01-28",
       "time": "After Hours",
       "eps_estimate": 4.54,
       "eps_actual": 4.99,
       "difference": 0.45,
       "surprise_prc": 9.91
    },
    {
       "date": "2019-10-30",
       "time": "After Hours",
       "eps_estimate": 2.84,
       "eps_actual": 3.03,
       "difference": 0.19,
       "surprise_prc": 6.69
    },
    {
       "date": "2010-07-30",
       "time": "After Hours",
       "eps_estimate": 2.10,
       "eps_actual": 2.18,
       "difference": 0.08,
       "surprise_prc": 3.81
    },
    {
       "date": "2019-04-30",
       "time": "After Hours",
       "eps_estimate": 2.37,
       "eps_actual": 2.46,
       "difference": 0.09,
       "surprise_prc": 3.8
    },
    {...}
  ],
  "status":"ok"
}

HTTP route

/earnings

API credits

20 per symbol

API parameters

Key Type Description
symbol string • Required parameter
• Symbol ticker of instrument
• For preffered stocks use dot(.) delimiter
E.g. BRK.A or BRK.B will be correct
figi string • Parameter is optional
• Filter by financial instrument global identifier (FIGI)
exchange string • Parameter is optional
• Exchange where instrument is traded
mic_code string • Parameter is optional
• Market Identifier Code (MIC) under ISO 10383 standard
country string • Parameter is optional
• Country where instrument is traded
type string • Parameter is optional
• The asset class to which the instrument belongs
• Supports American Depositary Receipt, Bond, Bond Fund, Closed-end Fund, Common Stock, Depositary Receipt, Digital Currency, ETF, Exchange-Traded Note, Global Depositary Receipt, Index, Limited Partnership, Mutual Fund, Physical Currency, Preferred Stock, REIT, Right, Structured Product, Trust, Unit, and Warrant
period string • Parameter is optional
• Type of earning, returns only 1 record
• When is not empty, dates and outputsize parameters are ignored
• Accepts: latest and next
outputsize number • Parameter is optional
• Number of data points to retrieve
• Supports values in the range from 1 to 1000
• Default 10 when no date parameters are set, otherwise set to maximum
format string • Parameter is optional
• Value can be JSON or CSV
• Default JSON
delimiter string • Parameter is optional
• Specify the delimiter used when downloading the CSV file
• Default semicolon ;
apikey string • Required parameter
• Your API key upgraded to the Grow plan or above, which can be obtained here

Response

Key Description
date date of earning release
time can be either of the following values: Pre Market, After Hours, Time Not Supplied, Transfer Agent
eps_estimate analyst estimate of the future company earning
eps_actual actual value of reported earning
difference delta between eps_actual and eps_estimate
surprise_prc surprise in the percentage of the eps_actual related to eps_estimate

JSON request example

https://api.twelvedata.com/earnings?symbol=AAPL&apikey=demo

Downloadable CSV example

https://api.twelvedata.com/earnings?symbol=AAPL&apikey=demo&format=CSV

Earnings Calendar

This API method returns earning data as a calendar for a given date range. By default today’s earning is returned. To call custom period, use start_date and end_date parameters.

HTTP request example

https://api.twelvedata.com/earnings_calendar?apikey=your_api_key

This request will return JSON with the following structure

{
    "earnings":{
        "2020-05-08":[
            {...},
            {
                "symbol": "BR",
                "name": "Broadridge Financial Solutions Inc",
                "currency": "USD",
                "exchange": "NYSE",
                "mic_code": "XNYS",
                "country": "United States",
                "time": "Time Not Supplied",
                "eps_estimate": 1.72,
                "eps_actual": 1.67,
                "difference": -0.05,
                "surprise_prc": -2.9
            },
            {
                "symbol": "LPL",
                "name": "LG Display Co Ltd",
                "currency": "USD",
                "exchange": "NYSE",
                "mic_code": "XNYS",
                "country": "United States",
                "time": "Time Not Supplied",
                "eps_estimate": -0.45,
                "eps_actual": -0.23,
                "difference": 0.22,
                "surprise_prc": 48.22
            },
            {...}
        ],
        "2020-05-07":[
            {...},
            {
                "symbol": "AAON",
                "name": "AAON Inc",
                "currency": "USD",
                "exchange": "NASDAQ",
                "mic_code": "XNAS",
                "country": "United States",
                "time": "Time Not Supplied",
                "eps_estimate": 0.35,
                "eps_actual": 0.41,
                "difference": 0.06,
                "surprise_prc": 17.14
            },
            {
                "symbol": "JOBS",
                "name": "51job Inc",
                "currency": "USD",
                "exchange": "NASDAQ",
                "mic_code": "XNAS",
                "country": "United States",
                "time": "Time Not Supplied",
                "eps_estimate": 2.44,
                "eps_actual": 3.27,
                "difference": 0.83,
                "surprise_prc": 34.02
            },
            {...}
        ],
        {...}
    },
    "status":"ok"
}

HTTP route

/earnings_calendar

API credits

40 per request

API parameters

Key Type Description
exchange string • Parameter is optional
• Exchange where instrument is traded
mic_code string • Parameter is optional
• Market Identifier Code (MIC) under ISO 10383 standard
country string • Parameter is optional
• Country where instrument is traded
format string • Parameter is optional
• Value can be JSON or CSV
• Default JSON
delimiter string • Parameter is optional
• Specify the delimiter used when downloading the CSV file
• Default semicolon ;
apikey string • Required parameter
• Your API key upgraded to the Grow plan or above, which can be obtained here

Response

Key Description
symbol instrument symbol (ticker)
name full name of instrument
currency currency in which instrument is traded by ISO 4217 standard
exchange exchange where instrument is traded
mic_code market identifier code (MIC) under ISO 10383 standard
country country where exchange is located
time can be either of the following values: Pre Market, After Hours, Time Not Supplied, Transfer Agent
eps_estimate analyst estimate of the future company earning
eps_actual actual value of reported earning
difference delta between eps_actual and eps_estimate
surprise_prc surprise in percentage of the eps_actual related to eps_estimate

JSON request example

https://api.twelvedata.com/earnings_calendar?apikey=demo

Downloadable CSV example

https://api.twelvedata.com/earnings_calendar?apikey=demo&format=CSV

IPO Calendar

This endpoint returns past, today, or upcoming IPOs.

HTTP request example

https://api.twelvedata.com/ipo_calendar?apikey=your_api_key

This request will return JSON with the following structure

{
  "2021-09-03": [
    {
      "symbol": "DWACU",
      "name": "Digital World Acquisition Corp.",
      "exchange": "NASDAQ",
      "mic_code": "XNAS",
      "price_range_low": 10,
      "price_range_high": 10,
      "offer_price": null,
      "currency": "USD",
      "shares": null
    },
    {
      "symbol": "9869",
      "name": "Helens Intl Hldg Co Ltd",
      "exchange": "HKEX",
      "mic_code": "XHKG",
      "price_range_low": null,
      "price_range_high": null,
      "offer_price": null,
      "currency": "HKD",
      "shares": null
    },
    {
      "symbol": "BMR",
      "name": "Ballymore Resources Ltd",
      "exchange": "ASX",
      "mic_code": "XASX",
      "price_range_low": 0.1548,
      "price_range_high": 0.1548,
      "offer_price": 0.2,
      "currency": "AUD",
      "shares": null
    }
  ]
}

HTTP route

/ipo_calendar

API credits

40 per request

API parameters

Key Type Description
exchange string • Parameter is optional
• Exchange where instrument is traded
mic_code string • Parameter is optional
• Market Identifier Code (MIC) under ISO 10383 standard
country string • Parameter is optional
• Country where instrument is traded
start_date string • Parameter is optional
• Format 2006-01-02
end_date string • Parameter is optional
• Format 2006-01-02
apikey string • Required parameter
• Your API key upgraded to the Grow plan or above, which can be obtained here

Response

Key Type Description
symbol string Ticker of the company
name string Name of the company
exchange string Exchange name where the company is listed
mic_code string Market Identifier Code (MIC) under ISO 10383 standard
price_range_low number The lower bound of stock price range if available
price_range_high number The upper bound of stock price range if available
offer_price number Initial offer price if available
currency string Currency of the stock
shares number Number of shares, if available

JSON request example

https://api.twelvedata.com/ipo_calendar?apikey=your_api_key

StatisticsHigh Demand

Returns current overview of company’s main statistics including valuation metrics and financials.

HTTP request example

https://api.twelvedata.com/statistics?symbol=AAPL&apikey=your_api_key

This request will return JSON with the following structure

{
  "meta": {
    "symbol": "AAPL",
    "name": "Apple Inc",
    "currency": "USD",
    "exchange": "NASDAQ",
    "mic_code": "XNAS",
    "exchange_timezone": "America/New_York"
  },
  "statistics": {
    "valuations_metrics": {
      "market_capitalization": 2546807865344,
      "enterprise_value": 2620597731328,
      "trailing_pe": 30.162493,
      "forward_pe": 26.982489,
      "peg_ratio": 1.4,
      "price_to_sales_ttm": 7.336227,
      "price_to_book_mrq": 39.68831,
      "enterprise_to_revenue": 7.549,
      "enterprise_to_ebitda": 23.623
    },
    "financials": {
      "fiscal_year_ends": "2020-09-26",
      "most_recent_quarter": "2021-06-26",
      "gross_margin": 46.57807
      "profit_margin": 0.25004,
      "operating_margin": 0.28788,
      "return_on_assets_ttm": 0.19302,
      "return_on_equity_ttm": 1.27125,
      "income_statement": {
        "revenue_ttm": 347155005440,
        "revenue_per_share_ttm": 20.61,
        "quarterly_revenue_growth": 0.364,
        "gross_profit_ttm": 104956000000,
        "ebitda": 110934999040,
        "net_income_to_common_ttm": 86801997824,
        "diluted_eps_ttm": 5.108,
        "quarterly_earnings_growth_yoy": 0.932
      },
      "balance_sheet": {
        "revenue_ttm": 347155005440,
        "total_cash_mrq": 61696000000,
        "total_cash_per_share_mrq": 3.732,
        "total_debt_mrq": 135491002368,
        "total_debt_to_equity_mrq": 210.782,
        "current_ratio_mrq": 1.062,
        "book_value_per_share_mrq": 3.882
      },
      "cash_flow": {
        "operating_cash_flow_ttm": 104414003200,
        "levered_free_cash_flow_ttm": 80625876992
      }
    },
    "stock_statistics": {
      "shares_outstanding": 16530199552,
      "float_shares": 16513305231,
      "avg_10_volume": 72804757,
      "avg_90_volume": 77013078,
      "shares_short": 93105968,
      "short_ratio": 1.19,
      "short_percent_of_shares_outstanding": 0.0056,
      "percent_held_by_insiders": 0.00071000005,
      "percent_held_by_institutions": 0.58474
    },
    "stock_price_summary": {
      "fifty_two_week_low": 103.1,
      "fifty_two_week_high": 157.26,
      "fifty_two_week_change": 0.375625,
      "beta": 1.201965,
      "day_50_ma": 148.96686,
      "day_200_ma": 134.42506
    },
    "dividends_and_splits": {
      "forward_annual_dividend_rate": 0.88,
      "forward_annual_dividend_yield": 0.0057,
      "trailing_annual_dividend_rate": 0.835,
      "trailing_annual_dividend_yield": 0.0053832764,
      "5_year_average_dividend_yield": 1.27,
      "payout_ratio": 0.16309999,
      "dividend_date": "2021-08-12",
      "ex_dividend_date": "2021-08-06",
      "last_split_factor": "4-for-1 split",
      "last_split_date": "2020-08-31"
    }
  }
}

HTTP route

/statistics

API credits

50 per symbol

API parameters

Key Type Description
symbol string • Required parameter
• Symbol ticker of instrument
• For preffered stocks use dot(.) delimiter
E.g. BRK.A or BRK.B will be correct
figi string • Parameter is optional
• Filter by financial instrument global identifier (FIGI)
exchange string • Parameter is optional
• Exchange where instrument is traded
mic_code string • Parameter is optional
• Market Identifier Code (MIC) under ISO 10383 standard
country string • Parameter is optional
• Country where instrument is traded
apikey string • Required parameter
• Your API key upgraded to the Pro plan or above, which can be obtained here

Response

Key Type Description
name string Name of the company
market_capitalization number Refers to the market value of the company's outstanding shares
enterprise_value number Refers to enterprise value (EV) of the company, often used as a more comprehensive alternative to market capitalization
trailing_pe number Refers to the trailing price-to-earnings (P/E). It is calculated by taking the current stock price and dividing it by the trailing earnings per share (EPS) for the past 12 months
forward_pe number Refers to the forward price-to-earnings ratio. It is calculated by dividing the current share price by the estimated future earnings per share
peg_ratio number The price/earnings to growth (PEG) ratio is a price-to-earnings ratio divided by the growth rate of the earnings
price_to_sales_ttm number The price-to-sales (P/S) ratio is a valuation ratio that compares the market capitalization to its revenues over the last 12 months
price_to_book_mrq number The price-to-book (P/B) ratio is equal to the current share price divided by the book value of all shares (BVPS) over the last quarter
enterprise_to_revenue number The enterprise value-to-revenue multiple (EV/R) is a measure that compares enterprise value to revenue
enterprise_to_ebitda number The enterprise value-to-ebitda multiple (EV/EBITDA) is a measure that compares enterprise value to EBITDA
fiscal_year_ends string Refers to the completion of the last 12-month accounting period
most_recent_quarter string The most recent quarter (MRQ) refers to the fiscal quarter that most recently ended
gross_margin number The portion of a company's revenue left over after direct costs are subtracted
profit_margin number Refers to gross profit margin. Calculated by dividing net income by sales revenue
operating_margin number Operating margin is calculated by dividing operating income by net sales
return_on_assets_ttm number Return on assets (ROA) is calculated by dividing net income by total assets
return_on_equity_ttm number Return on equity (ROE) is calculated by dividing net income by average shareholders' equity
revenue_ttm number Refers to total revenue over the last 12 months
revenue_per_share_ttm number Refers to revenue per share over the last 12 months
quarterly_revenue_growth number Refers to quarterly revenue growth year over year
gross_profit_ttm number Refers to gross profit over the last 12 months
ebitda number Refers to EBITDA (earnings before interest, taxes, depreciation, and amortization) measure; EBITDA is not calculated for banks.
net_income_to_common_ttm number Refers to net income applicable to common shares over the last 12 months
diluted_eps_ttm number Refers to diluted EPS measure over the last 12 months
quarterly_earnings_growth_yoy number Refers to quarterly earnings growth year over year
total_cash_mrq number Refers to total cash measure for the most recent quarter
total_cash_per_share_mrq number Refers to total cash per share measure for the most recent quarter
total_debt_mrq number Refers to total debt measure for the most recent quarter
total_debt_to_equity_mrq number Refers to total debt to equity measure for the most recent quarter
current_ratio_mrq number Refers to current ratio (total assets / total liabilities) ratio for the most recent quarter
book_value_per_share_mrq number Refers to book value per share (BVPS) ratio for the most recent quarter
operating_cash_flow_ttm number Refers to operating cash flow measure over the last 12 months
levered_free_cash_flow_ttm number Refers to levered free cash flow measure over the last 12 months
shares_outstanding number Refers for the shares outstanding currently held by all its shareholders
float_shares number Refers to floating stock is the number of public shares a company has available for trading on the open market
avg_10_volume number Refers to the average 10 days volume
avg_90_volume number Refers to the average 90 days volume
shares_short number Refers to the number of shares that have been shorted
short_ratio number Refers to short ratio measure
short_percent_of_shares_outstanding number Refers to the number of shorted shares divided by the number of shares outstanding
percent_held_by_insiders number Refers to the percentage of shares held by the company insiders
percent_held_by_institutions number Refers to the percentage of shares held by the institutions
fifty_two_week_low number Refers to the lowest price at which stock traded during a year
fifty_two_week_high number Refers to the highest price at which stock traded during a year
fifty_two_week_change number Refers to the change between lowest and highest prices during a year
beta number Refers to beta measure relative to the primary benchmark (index) of the country
day_50_ma number Refers to the 50-day simple moving average
day_200_ma number Refers to the 200-day simple moving average
forward_annual_dividend_rate number Refers to the forward dividend yield estimation in the currency of instrument
forward_annual_dividend_yield number Refers to the forward dividend yield percentage relative to stock price
trailing_annual_dividend_rate number Refers to the trailing dividend yield rate in the currency of instrument over the last 12 months
trailing_annual_dividend_yield number Refers to the trailing dividend yield percentage relative to stock price
5_year_average_dividend_yield number Refers to the average 5 years dividend yield
payout_ratio number Refers to payout ratio, showing the proportion of earnings a company pays its shareholders in the form of dividends
dividend_date number Refers to the last dividend payout date
ex_dividend_date number Refers to the last ex-dividend payout date
last_split_factor number Specification of the last split event
last_split_date number Refers for the last split date

JSON request example

https://api.twelvedata.com/statistics?symbol=AAPL&apikey=demo

Insider Transactions

Returns trading information performed by insiders.

HTTP request example

https://api.twelvedata.com/insider_transactions?symbol=AAPL&apikey=your_api_key

This request will return JSON with the following structure

{
  "meta": {
    "symbol": "AAPL",
    "name": "Apple Inc",
    "currency": "USD",
    "exchange": "NASDAQ",
    "mic_code": "XNAS",
    "exchange_timezone": "America/New_York"
  },
  "insider_transactions": [
    {
      "full_name": "ADAMS KATHERINE L",
      "position": "General Counsel",
      "date_reported": "2021-05-03",
      "is_direct": true,
      "shares": 17000,
      "value": 2257631,
      "description": "Sale at price 132.57 - 133.93 per share."
    },
    {
      "full_name": "MAESTRI LUCA",
      "position": "Chief Financial Officer",
      "date_reported": "2021-05-03",
      "is_direct": true,
      "shares": 121072,
      "value": 16079338,
      "description": "Sale at price 132.58 - 133.93 per share."
    },
    {
      "full_name": "O'BRIEN DEIRDRE",
      "position": "Officer",
      "date_reported": "2021-04-16",
      "is_direct": true,
      "shares": 18216,
      "value": 2441126,
      "description": "Sale at price 134.01 per share."
    },
    {
      "full_name": "KONDO CHRISTOPHER",
      "position": "Officer",
      "date_reported": "2021-04-15",
      "is_direct": true,
      "shares": 17603,
      "value": 0,
      "description": ""
    }
  ]
}

HTTP route

/insider_transactions

API credits

200 per symbol

API parameters

Key Type Description
symbol string • Required parameter
• Symbol ticker of instrument
• For preffered stocks use dot(.) delimiter
E.g. BRK.A or BRK.B will be correct
figi string • Parameter is optional
• Filter by financial instrument global identifier (FIGI)
exchange string • Parameter is optional
• Exchange where instrument is traded
mic_code string • Parameter is optional
• Market Identifier Code (MIC) under ISO 10383 standard
country string • Parameter is optional
• Country where instrument is traded
apikey string • Required parameter
• Your API key upgraded to the Pro plan or above, which can be obtained here

Response

Key Type Description
full_name string Full name of an individual, including first name, middle name, last name, and suffix
position string Job position of insider
date_reported string Date the transaction was reported
is_direct bool true if direct, false if indirect
shares number As per report the number of shares acquired or disposed of the transaction
value number Represents the value of transaction, calculated as price multiplied by the volume
description string Exact price or price range of the transaction if available

JSON request example

https://api.twelvedata.com/insider_transactions?symbol=AAPL&apikey=demo

Income StatementHigh Demand

Returns complete income statement of a company and shows the company’s revenues and expenses during a period (annual or quarter).

HTTP request example

https://api.twelvedata.com/income_statement?symbol=AAPL&apikey=your_api_key

This request will return JSON with the following structure

{
  "meta": {
    "symbol": "AAPL",
    "name": "Apple Inc",
    "currency": "USD",
    "exchange": "NASDAQ",
    "mic_code": "XNAS",
    "exchange_timezone": "America/New_York",
    "period": "Quarterly"
  },
  "income_statement": [
    {
      "fiscal_date": "2021-12-31",
      "quarter": 1,
      "year": 2022,
      "sales": 123945000000,
      "cost_of_goods": 69702000000,
      "gross_profit": 54243000000,
      "operating_expense": {
        "research_and_development": 6306000000,
        "selling_general_and_administrative": 6449000000,
        "other_operating_expenses": null
      },
      "operating_income": 41488000000,
      "non_operating_interest": {
        "income": 650000000,
        "expense": 694000000
      },
      "other_income_expense": -203000000,
      "pretax_income": 41241000000,
      "income_tax": 6611000000,
      "net_income": 34630000000,
      "eps_basic": 2.11,
      "eps_diluted": 2.1,
      "basic_shares_outstanding": 16391724000,
      "diluted_shares_outstanding": 16391724000,
      "ebitda": 44632000000,
      "net_income_continuous_operations": null,
      "minority_interests": null,
      "preferred_stock_dividends": null
    }
  ]
}

HTTP route

/income_statement

API credits

100 per symbol

API parameters

Key Type Description
symbol string • Required parameter
• Symbol ticker of instrument
• For preffered stocks use dot(.) delimiter
E.g. BRK.A or BRK.B will be correct
figi string • Parameter is optional
• Filter by financial instrument global identifier (FIGI)
exchange string • Parameter is optional
• Exchange where instrument is traded
mic_code string • Parameter is optional
• Market Identifier Code (MIC) under ISO 10383 standard
country string • Parameter is optional
• Country where instrument is traded
period string • Parameter is optional
• Values should be annual or quarterly
start_date string • Parameter is optional
• Format 2006-01-02
end_date string • Parameter is optional
• Format 2006-01-02
apikey string • Required parameter
• Your API key upgraded to the Pro plan or above, which can be obtained here

Response

Key Type Description
fiscal_date string Date of the income statement release
quarter number Fiscal quarter. Visible when &period=quarterly
year number Fiscal year. Visible when &period=quarterly
sales number Refers to total reported revenue
cost_of_goods number Refers to cost of revenue
gross_profit number Refers to net gross profit: sales - cost_of_goods
research_and_development number Refers to research & development (R&D) expenses
selling_general_and_administrative number Refers to selling, general and administrative (SG&A) expenses
other_operating_expenses number Refers to other operating expenses
operating_income number Refers to net operating income: gross_profit - research_and_development - selling_general_and_administrative
income number Refers to non-operating interest income
expense number Refers to non-operating interest expense
other_income_expense number Refers to other incomes or expenses
pretax_income number Refers to earnings before tax: operating_income + net_non_operating_interest - other_income_expense
income_tax number Refers to a tax provision
net_income number Refers to net income: pretax_income - income_tax
eps_basic number Refers to earnings per share (EPS)
eps_diluted number Refers to diluted earnings per share (EPS)
basic_shares_outstanding number Refers for the shares outstanding held by all its shareholders
diluted_shares_outstanding number Refers to the total number of shares a company would have if all dilutive securities were exercised and converted into shares
ebitda number Refers to EBITDA (earnings before interest, taxes, depreciation, and amortization) measure
net_income_continuous_operations number Refers to the after-tax earnings that a business has generated from its operational activities
minority_interests number Refers to amount of minority interests paid out
preferred_stock_dividends number Refers to dividend that is allocated to and paid on a company's preferred shares

JSON request example

https://api.twelvedata.com/income_statement?symbol=AAPL&apikey=demo

Income Statement Consolidated

Returns consolidated income statement of a company and expenses during a period (annual or quarter).

HTTP request example

https://api.twelvedata.com/income_statement/consolidated?symbol=AAPL&apikey=your_api_key

This request will return JSON with the following structure

{
  "income_statement": [
    {
      "fiscal_date": "2023-09-30",
      "revenue": {
        "total_revenue": 383285000000,
        "operating_revenue": 383285000000
      },
      "gross_profit": {
        "gross_profit_value": 169148000000,
        "cost_of_revenue": {
          "cost_of_revenue_value": 214137000000,
          "excise_taxes": 214137000000,
          "reconciled_cost_of_revenue": 214137000000
        }
      },
      "operating_income": {
        "operating_income_value": 114301000000,
        "total_operating_income_as_reported": 114301000000,
        "operating_expense": 54847000000,
        "other_operating_expenses": 114301000000,
        "total_expenses": 268984000000
      },
      "net_income": {
        "net_income_value": 96995000000,
        "net_income_common_stockholders": 96995000000,
        "net_income_including_noncontrolling_interests": 96995000000,
        "net_income_from_tax_loss_carryforward": 96995000000,
        "net_income_extraordinary": 96995000000,
        "net_income_discontinuous_operations": 96995000000,
        "net_income_continuous_operations": 96995000000,
        "net_income_from_continuing_operation_net_minority_interest": 96995000000,
        "net_income_from_continuing_and_discontinued_operation": 96995000000,
        "normalized_income": 96995000000,
        "minority_interests": 96995000000
      },
      "earnings_per_share": {
        "diluted_eps": 6.13,
        "basic_eps": 6.16,
        "continuing_and_discontinued_diluted_eps": 6.16,
        "continuing_and_discontinued_basic_eps": 6.16,
        "normalized_diluted_eps": 6.16,
        "normalized_basic_eps": 6.16,
        "reported_normalized_diluted_eps": 6.16,
        "reported_normalized_basic_eps": 6.16,
        "diluted_eps_other_gains_losses": 6.16,
        "tax_loss_carryforward_diluted_eps": 6.16,
        "diluted_accounting_change": 6.16,
        "diluted_extraordinary": 6.16,
        "diluted_discontinuous_operations": 6.16,
        "diluted_continuous_operations": 6.16,
        "basic_eps_other_gains_losses": 6.16,
        "tax_loss_carryforward_basic_eps": 6.16,
        "basic_accounting_change": 6.16,
        "basic_extraordinary": 6.16,
        "basic_discontinuous_operations": 6.16,
        "basic_continuous_operations": 6.16,
        "diluted_ni_avail_to_common_stockholders": 96995000000,
        "average_dilution_earnings": 96995000000
      },
      "expenses": {
        "total_expenses": 268984000000,
        "selling_general_and_administration_expense": 24932000000,
        "selling_and_marketing_expense": 24932000000,
        "general_and_administrative_expense": 24932000000,
        "other_general_and_administrative_expense": 24932000000,
        "depreciation_amortization_depletion_income_statement": 29915000000,
        "research_and_development_expense": 29915000000,
        "insurance_and_claims_expense": 29915000000,
        "rent_and_landing_fees": 29915000000,
        "salaries_and_wages_expense": 29915000000,
        "rent_expense_supplemental": 29915000000,
        "provision_for_doubtful_accounts": 29915000000
      },
      "interest_income_and_expense": {
        "interest_income": 3750000000,
        "interest_expense": 3933000000,
        "net_interest_income": -183000000,
        "net_non_operating_interest_income_expense": -183000000,
        "interest_expense_non_operating": 3933000000,
        "interest_income_non_operating": 3750000000
      },
      "other_income_and_expenses": {
        "other_income_expense": -382000000,
        "other_non_operating_income_expenses": -382000000,
        "special_income_charges": 382000000,
        "gain_on_sale_of_ppe": 382000000,
        "gain_on_sale_of_business": 382000000,
        "gain_on_sale_of_security": 382000000,
        "other_special_charges": 382000000,
        "write_off": 382000000,
        "impairment_of_capital_assets": 382000000,
        "restructuring_and_merger_acquisition": 382000000,
        "securities_amortization": 382000000,
        "earnings_from_equity_interest": 382000000,
        "earnings_from_equity_interest_net_of_tax": 382000000,
        "total_other_finance_cost": 382000000
      },
      "taxes": {
        "tax_provision": 16741000000,
        "tax_effect_of_unusual_items": 0,
        "tax_rate_for_calculations": 0.147,
        "other_taxes": 0
      },
      "depreciation_and_amortization": {
        "depreciation_amortization_depletion": 129188000000,
        "amortization_of_intangibles": 129188000000,
        "depreciation": 129188000000,
        "amortization": 129188000000,
        "depletion": 129188000000,
        "depreciation_and_amortization_in_income_statement": 129188000000
      },
      "ebitda": {
        "ebitda_value": 129188000000,
        "normalized_ebitda_value": 129188000000,
        "ebit_value": 117669000000
      },
      "dividends_and_shares": {
        "dividend_per_share": 15812547000,
        "diluted_average_shares": 15812547000,
        "basic_average_shares": 15744231000,
        "preferred_stock_dividends": 15744231000,
        "other_under_preferred_stock_dividend": 15744231000
      },
      "unusual_items": {
        "total_unusual_items": 11519000000,
        "total_unusual_items_excluding_goodwill": 11519000000
      },
      "depreciation": {
        "reconciled_depreciation": 11519000000
      },
      "pretax_income": {
        "pretax_income_value": 113736000000
      },
      "special_income_charges": {
        "special_income_charges_value": 113736000000
      }
    }
  ],
  "status": "ok"
}

HTTP route

/income_statement/consolidated

API credits

100 per symbol

API parameters

Key Type Description
symbol string • Required parameter
• Symbol ticker of instrument
• For preffered stocks use dot(.) delimiter
E.g. BRK.A or BRK.B will be correct
figi string • Parameter is optional
• Filter by financial instrument global identifier (FIGI)
exchange string • Parameter is optional
• Exchange where instrument is traded
mic_code string • Parameter is optional
• Market Identifier Code (MIC) under ISO 10383 standard
country string • Parameter is optional
• Country where instrument is traded
period string • Parameter is optional
• Values should be annual or quarterly
start_date string • Parameter is optional
• Format 2006-01-02
end_date string • Parameter is optional
• Format 2006-01-02
apikey string • Required parameter
• Your API key upgraded to the Pro plan or above, which can be obtained here

Response

Click to expand
Key Type Description
fiscal_date string Date of the income statement release
total_revenue number Total revenue
operating_revenue number Operating revenue
gross_profit_value number Gross profit value
cost_of_revenue_value number Cost of revenue value
excise_taxes number Excise taxes
reconciled_cost_of_revenue number Reconciled cost of revenue
operating_income_value number Operating income value
total_operating_income_as_reported number Total operating income as reported
operating_expense number Operating expense
other_operating_expenses number Other operating expenses
total_expenses number Total expenses
net_income_value number Net income value
net_income_common_stockholders number Net income common stockholders
net_income_including_noncontrolling_interests number Net income including noncontrolling interests
net_income_from_tax_loss_carryforward number Net income from tax loss carryforward
net_income_extraordinary number Net income extraordinary
net_income_discontinuous_operations number Net income discontinuous operations
net_income_continuous_operations number Net income continuous operations
net_income_from_continuing_operation_net_minority_interest number Net income from continuing operation net minority interest
net_income_from_continuing_and_discontinued_operation number Net income from continuing and discontinued operation
normalized_income number Normalized income
minority_interests number Minority interests
diluted_eps number Diluted eps
basic_eps number Basic eps
continuing_and_discontinued_diluted_eps number Continuing and discontinued diluted eps
continuing_and_discontinued_basic_eps number Continuing and discontinued basic eps
normalized_diluted_eps number Normalized diluted eps
normalized_basic_eps number Normalized basic eps
reported_normalized_diluted_eps number Reported normalized diluted eps
reported_normalized_basic_eps number Reported normalized basic eps
diluted_eps_other_gains_losses number Diluted eps other gains losses
tax_loss_carryforward_diluted_eps number Tax loss carryforward diluted eps
diluted_accounting_change number Diluted accounting change
diluted_extraordinary number Diluted extraordinary
diluted_discontinuous_operations number Diluted discontinuous operations
diluted_continuous_operations number Diluted continuous operations
basic_eps_other_gains_losses number Basic eps other gains losses
tax_loss_carryforward_basic_eps number Tax loss carryforward basic eps
basic_accounting_change number Basic accounting change
basic_extraordinary number Basic extraordinary
basic_discontinuous_operations number Basic discontinuous operations
basic_continuous_operations number Basic continuous operations
diluted_ni_avail_to_common_stockholders number Diluted ni avail to common stockholders
average_dilution_earnings number Average dilution earnings
total_expenses number Total expenses
selling_general_and_administration_expense number Selling general and administrative
selling_and_marketing_expense number Selling and marketing expense
general_and_administrative_expense number General and administrative expense
other_general_and_administrative_expense number Other general and administrative expense
depreciation_amortization_depletion_income_statement number Depreciation amortization depletion income statement
research_and_development_expense number Research and development expense
insurance_and_claims_expense number Insurance and claims expense
rent_and_landing_fees number Rent and landing fees
salaries_and_wages_expense number Salaries and wages expense
rent_expense_supplemental number Rent expense supplemental
provision_for_doubtful_accounts number Provision for doubtful accounts
interest_income number Interest income
interest_expense number Interest expense
net_interest_income number Net interest income
net_non_operating_interest_income_expense number Net non operating interest income expense
interest_expense_non_operating number Interest expense non operating
interest_income_non_operating number Interest income non operating
other_income_expense number Other income expense
other_non_operating_income_expenses number Other non operating income expenses
special_income_charges number Special income charges
gain_on_sale_of_ppe number Gain on sale of ppe
gain_on_sale_of_business number Gain on sale of business
gain_on_sale_of_security number Gain on sale of security
other_special_charges number Other special charges
write_off number Write off
impairment_of_capital_assets number Impairment of capital assets
restructuring_and_merger_acquisition number Restructuring and merger acquisition
securities_amortization number Securities amortization
earnings_from_equity_interest number Earnings from equity interest
earnings_from_equity_interest_net_of_tax number Earnings from equity interest net of tax
total_other_finance_cost number Total other finance cost
tax_provision number Tax provision
tax_effect_of_unusual_items number Tax effect of unusual items
tax_rate_for_calculations number Tax rate for calculations
other_taxes number Other taxes
depreciation_amortization_depletion number Depreciation amortization depletion
amortization_of_intangibles number Amortization of intangibles
depreciation number Depreciation
amortization number Amortization
depletion number Depletion
depreciation_and_amortization_in_income_statement number Depreciation and amortization in income statement
ebitda_value number Ebitda value
normalized_ebitda_value number Normalized ebitda value
ebit_value number Ebit value
dividend_per_share number Dividend per share
diluted_average_shares number Diluted average shares
basic_average_shares number Basic average shares
preferred_stock_dividends number Preferred stock dividends
other_under_preferred_stock_dividend number Other under preferred stock dividend
total_unusual_items number Total unusual items
total_unusual_items_excluding_goodwill number Total unusual items excluding goodwill
reconciled_depreciation number Reconciled depreciation
pretax_income_value number Pretax income value
special_income_charges_value number Special income charges value

JSON request example

https://api.twelvedata.com/income_statement/consolidated?symbol=AAPL&apikey=demo

Balance SheetHigh Demand

Returns complete balance sheet of a company showing the summary of assets, liabilities, and shareholders’ equity.

HTTP request example

https://api.twelvedata.com/balance_sheet?symbol=AAPL&apikey=your_api_key

This request will return JSON with the following structure

{
  "meta": {
    "symbol": "AAPL",
    "name": "Apple Inc",
    "currency": "USD",
    "exchange": "NASDAQ",
    "mic_code": "XNAS",
    "exchange_timezone": "America/New_York",
    "period": "Quarterly"
  },
  "balance_sheet": [
    {
      "fiscal_date": "2021-09-30",
      "assets": {
        "current_assets": {
          "cash": 17305000000,
          "cash_equivalents": 17635000000,
          "cash_and_cash_equivalents": 34940000000,
          "other_short_term_investments": 27699000000,
          "accounts_receivable": 26278000000,
          "other_receivables": 25228000000,
          "inventory": 6580000000,
          "prepaid_assets": null,
          "restricted_cash": null,
          "assets_held_for_sale": null,
          "hedging_assets": null,
          "other_current_assets": 14111000000,
          "total_current_assets": 134836000000
        },
        "non_current_assets": {
          "properties": 0,
          "land_and_improvements": 20041000000,
          "machinery_furniture_equipment": 78659000000,
          "construction_in_progress": null,
          "leases": 11023000000,
          "accumulated_depreciation": -70283000000,
          "goodwill": null,
          "investment_properties": null,
          "financial_assets": null,
          "intangible_assets": null,
          "investments_and_advances": 127877000000,
          "other_non_current_assets": 48849000000,
          "total_non_current_assets": 216166000000
        },
        "total_assets": 351002000000
      },
      "liabilities": {
        "current_liabilities": {
          "accounts_payable": 54763000000,
          "accrued_expenses": null,
          "short_term_debt": 15613000000,
          "deferred_revenue": 7612000000,
          "tax_payable": null,
          "pensions": null,
          "other_current_liabilities": 47493000000,
          "total_current_liabilities": 125481000000
        },
        "non_current_liabilities": {
          "long_term_provisions": null,
          "long_term_debt": 109106000000,
          "provision_for_risks_and_charges": 24689000000,
          "deferred_liabilities": null,
          "derivative_product_liabilities": null,
          "other_non_current_liabilities": 28636000000,
          "total_non_current_liabilities": 162431000000
        },
        "total_liabilities": 287912000000
      },
      "shareholders_equity": {
        "common_stock": 57365000000,
        "retained_earnings": 5562000000,
        "other_shareholders_equity": 163000000,
        "total_shareholders_equity": 63090000000,
        "additional_paid_in_capital": null,
        "treasury_stock": null,
        "minority_interest": null
      }
    }
  ]
}

HTTP route

/balance_sheet

API credits

100 per symbol

API parameters

Key Type Description
symbol string • Required parameter
• Symbol ticker of instrument
• For preffered stocks use dot(.) delimiter
E.g. BRK.A or BRK.B will be correct
figi string • Parameter is optional
• Filter by financial instrument global identifier (FIGI)
exchange string • Parameter is optional
• Exchange where instrument is traded
mic_code string • Parameter is optional
• Market Identifier Code (MIC) under ISO 10383 standard
country string • Parameter is optional
• Country where instrument is traded
period string • Parameter is optional
• Values should be annual or quarterly
start_date string • Parameter is optional
• Format 2006-01-02
end_date string • Parameter is optional
• Format 2006-01-02
apikey string • Required parameter
• Your API key upgraded to the Pro plan or above, which can be obtained here

Response

Key Type Description
fiscal_date string Date of the balance sheet release
quarter string Fiscal quarter. Visible when &period=quarterly
cash number Cash includes currency, bank accounts, and undeposited checks
cash_equivalents number Represents cash equivalents that have high credit quality and are highly liquid
cash_and_cash_equivalents number Combined value of cash and cash equivalents when company doesn't report a breakdown
other_short_term_investments number Represents other short term investments
accounts_receivable number Represents the balance of money due to a firm for goods or services delivered or used but not yet paid for by customers
other_receivables number Represents other receivables
inventory number Represents the goods available for sale and raw materials used to produce goods available for sale
prepaid_assets number Represents expense that has already been paid for, but which has not yet been consumed
restricted_cash number Represents money that is held for a specific purpose and thus not available to the company for immediate or general business use
assets_held_for_sale number Represents assets which company plans to sell
hedging_assets number Represents money that is spent on hedging assets
other_current_assets number Represents other current assets
total_current_assets number All current assets values in a total
properties number Represents property owned
land_and_improvements number Represents land and improvements owned
machinery_furniture_equipment number Represents office equipment, furniture, and vehicles owned
construction_in_progress number Represents the cost of construction work, which is not yet completed
leases number Represents operating and financial leases
accumulated_depreciation number Represents the cumulative depreciation of an asset that has been recorded
goodwill number Represents the value of a brand name, solid customer base, good customer relations, good employee relations, and proprietary technology
investment_properties number Represents real estate property purchased with the intention of earning a return on the investment
financial_assets number Represents liquid asset that gets its value from a contractual right or ownership claim
intangible_assets number Represents the patents, trademarks, and other intellectual properties
investments_and_advances number Represents available for sale financial securities
other_non_current_assets number Represents other long-term assets
total_non_current_assets number All long-term assets values in total
total_assets number The sum of total_current_assets + total_non_current_assets
accounts_payable number Refers to an account within the general ledger that represents an obligation to pay off a short-term debt to creditors or suppliers
accrued_expenses number Represents payments that a company is obligated to pay in the future for which goods and services have already been delivered
short_term_debt number Represents current debt and capital lease obligations
deferred_revenue number Represents advance payments a company receives for products or services that are to be delivered or performed in the future
tax_payable number Represents taxes due to the government within one year
pensions number Represents to pensions to be paid out
other_current_liabilities number Represents other current liabilities
total_current_liabilities number Represents total current assets
long_term_provisions number Represents money set aside for employee benefits such as gratuity
long_term_debt number Represents amount of outstanding debt that has a maturity of 12 months or longer
provision_for_risks_and_charges number Represents funds set aside as assets to pay for anticipated future losses
deferred_liabilities number Represents revenue producing activity for which revenue has not yet been recognized, and is not expected to be recognized in the next 12 months
derivative_product_liabilities number
other_non_current_liabilities number Represents other non-current liabilities
total_non_current_liabilities number Represents total non-current liabilities
total_liabilities number The sum of total_current_liabilities + total_non_current_liabilities
common_stock number Represents net worth of investors shares, which is equal to the total_assets - total_liabilities
retained_earnings number Refers to the profits earned minus dividends paid
other_shareholders_equity number Represents other not affecting retained earnings gains and looses
total_shareholders_equity number Represents the net worth of a company, which is the amount that would be returned to shareholders if a company's total assets were liquidated, and all of its debts were repaid

JSON request example

https://api.twelvedata.com/balance_sheet?symbol=AAPL&apikey=demo

Balance Sheet consolidated

Returns consolidated balance sheet of a company showing the summary of assets, liabilities, and shareholders.

HTTP request example

https://api.twelvedata.com/balance_sheet/consolidated?symbol=AAPL&apikey=your_api_key

This request will return JSON with the following structure

{
  "balance_sheet": [
    {
      "fiscal_date": "2023-09-30",
      "assets": {
        "total_assets": 352583000000,
        "current_assets": {
          "total_current_assets": 143566000000,
          "cash_cash_equivalents_and_short_term_investments": 61555000000,
          "cash_and_cash_equivalents": 29965000000,
          "cash_equivalents": 1606000000,
          "cash_financial": 28359000000,
          "other_short_term_investments": 31590000000,
          "restricted_cash": 31590000000,
          "receivables": {
            "total_receivables": 60985000000,
            "accounts_receivable": 29508000000,
            "gross_accounts_receivable": 29508000000,
            "allowance_for_doubtful_accounts_receivable": 29508000000,
            "receivables_adjustments_allowances": 29508000000,
            "other_receivables": 31477000000,
            "due_from_related_parties_current": 31477000000,
            "taxes_receivable": 31477000000,
            "accrued_interest_receivable": 31477000000,
            "notes_receivable": 31477000000,
            "loans_receivable": 31477000000
          },
          "inventory": {
            "total_inventory": 6331000000,
            "inventories_adjustments_allowances": 6331000000,
            "other_inventories": 6331000000,
            "finished_goods": 6331000000,
            "work_in_process": 6331000000,
            "raw_materials": 6331000000
          },
          "prepaid_assets": 14695000000,
          "current_deferred_assets": 14695000000,
          "current_deferred_taxes_assets": 14695000000,
          "assets_held_for_sale_current": 14695000000,
          "hedging_assets_current": 14695000000,
          "other_current_assets": 14695000000
        },
        "non_current_assets": {
          "total_non_current_assets": 209017000000,
          "financial_assets": 209017000000,
          "investments_and_advances": 100544000000,
          "other_investments": 100544000000,
          "investment_in_financial_assets": 100544000000,
          "held_to_maturity_securities": 100544000000,
          "available_for_sale_securities": 100544000000,
          "financial_assets_designated_as_fair_value_through_profit_or_loss_total": 100544000000,
          "trading_securities": 100544000000,
          "long_term_equity_investment": 100544000000,
          "investments_in_joint_ventures_at_cost": 100544000000,
          "investments_in_other_ventures_under_equity_method": 100544000000,
          "investments_in_associates_at_cost": 100544000000,
          "investments_in_subsidiaries_at_cost": 100544000000,
          "investment_properties": 100544000000,
          "goodwill_and_other_intangible_assets": {
            "goodwill": 100544000000,
            "other_intangible_assets": 100544000000,
            "total_goodwill_and_intangible_assets": 100544000000
          },
          "net_ppe": 54376000000,
          "gross_ppe": 125260000000,
          "accumulated_depreciation": -70884000000,
          "leases": 12839000000,
          "construction_in_progress": 12839000000,
          "other_properties": 10661000000,
          "machinery_furniture_equipment": 78314000000,
          "buildings_and_improvements": 12839000000,
          "land_and_improvements": 23446000000,
          "properties": 0,
          "non_current_accounts_receivable": 12839000000,
          "non_current_note_receivables": 12839000000,
          "due_from_related_parties_non_current": 12839000000,
          "non_current_prepaid_assets": 12839000000,
          "non_current_deferred_assets": 17852000000,
          "non_current_deferred_taxes_assets": 17852000000,
          "defined_pension_benefit": 12839000000,
          "other_non_current_assets": 36245000000
        },
        "liabilities": {
          "total_liabilities_net_minority_interest": 290437000000,
          "current_liabilities": {
            "total_current_liabilities": 145308000000,
            "current_debt_and_capital_lease_obligation": 17382000000,
            "current_debt": 15807000000,
            "current_capital_lease_obligation": 1575000000,
            "other_current_borrowings": 9822000000,
            "line_of_credit": 9822000000,
            "commercial_paper": 5985000000,
            "current_notes_payable": 9822000000,
            "current_provisions": 9822000000,
            "payables_and_accrued_expenses": {
              "total_payables_and_accrued_expenses": 71430000000,
              "accounts_payable": 62611000000,
              "current_accrued_expenses": 9822000000,
              "interest_payable": 9822000000,
              "payables": 71430000000,
              "other_payable": 9822000000,
              "due_to_related_parties_current": 9822000000,
              "dividends_payable": 9822000000,
              "total_tax_payable": 8819000000,
              "income_tax_payable": 8819000000
            },
            "pension_and_other_post_retirement_benefit_plans_current": 8061000000,
            "employee_benefits": 8061000000,
            "current_deferred_liabilities": 8061000000,
            "current_deferred_revenue": 8061000000,
            "current_deferred_taxes_liabilities": 8061000000,
            "other_current_liabilities": 48435000000,
            "liabilities_held_for_sale_non_current": 48435000000
          },
          "non_current_liabilities": {
            "total_non_current_liabilities_net_minority_interest": 145129000000,
            "long_term_debt_and_capital_lease_obligation": {
              "total_long_term_debt_and_capital_lease_obligation": 106548000000,
              "long_term_debt": 95281000000,
              "long_term_capital_lease_obligation": 11267000000
            },
            "long_term_provisions": 15457000000,
            "non_current_pension_and_other_postretirement_benefit_plans": 15457000000,
            "non_current_accrued_expenses": 15457000000,
            "due_to_related_parties_non_current": 15457000000,
            "trade_and_other_payables_non_current": 15457000000,
            "trade_and_other_payables_non_current": 15457000000,
            "non_current_deferred_liabilities": 15457000000,
            "non_current_deferred_revenue": 15457000000,
            "non_current_deferred_taxes_liabilities": 15457000000,
            "other_non_current_liabilities": 23124000000,
            "preferred_securities_outside_stock_equity": 15457000000,
            "derivative_product_liabilities": 15457000000,
            "capital_lease_obligations": 12842000000,
            "restricted_common_stock": 12842000000
          },
          "equity": {
            "total_equity_gross_minority_interest": 62146000000,
            "stockholders_equity": 62146000000,
            "common_stock_equity": 62146000000,
            "preferred_stock_equity": 62146000000,
            "other_equity_interest": 62146000000,
            "minority_interest": 62146000000,
            "total_capitalization": 157427000000,
            "net_tangible_assets": 62146000000,
            "tangible_book_value": 62146000000,
            "invested_capital": 173234000000,
            "working_capital": -1742000000,
            "capital_stock": {
              "common_stock": 73812000000,
              "preferred_stock": 73812000000,
              "total_partnership_capital": 73812000000,
              "general_partnership_capital": 73812000000,
              "limited_partnership_capital": 73812000000,
              "capital_stock": 73812000000,
              "other_capital_stock": 73812000000,
              "additional_paid_in_capital": 73812000000,
              "retained_earnings": -214000000,
              "treasury_stock": 73812000000,
              "treasury_shares_number": 0,
              "ordinary_shares_number": 15550061000,
              "preferred_shares_number": 73812000000,
              "share_issued": 15550061000
            },
            "equity_adjustments": {
              "gains_losses_not_affecting_retained_earnings": -11452000000,
              "other_equity_adjustments": -11452000000,
              "fixed_assets_revaluation_reserve": 11452000000,
              "foreign_currency_translation_adjustments": 11452000000,
              "minimum_pension_liabilities": 11452000000,
              "unrealized_gain_loss": 11452000000
            },
            "net_debt": 81123000000,
            "total_debt": 123930000000
          }
        }
      }
    }
  ],
  "status": "ok"
}

HTTP route

/balance_sheet/consolidated

API credits

100 per symbol

API parameters

Key Type Description
symbol string • Required parameter
• Symbol ticker of instrument
• For preffered stocks use dot(.) delimiter
E.g. BRK.A or BRK.B will be correct
figi string • Parameter is optional
• Filter by financial instrument global identifier (FIGI)
exchange string • Parameter is optional
• Exchange where instrument is traded
mic_code string • Parameter is optional
• Market Identifier Code (MIC) under ISO 10383 standard
country string • Parameter is optional
• Country where instrument is traded
period string • Parameter is optional
• Values should be annual or quarterly
start_date string • Parameter is optional
• Format 2006-01-02
end_date string • Parameter is optional
• Format 2006-01-02
apikey string • Required parameter
• Your API key upgraded to the Pro plan or above, which can be obtained here

Response

Click to expand
Key Type Description
fiscal_date string Date of the balance sheet release
total_assets number Total assets
total_current_assets number Total current assets
cash_cash_equivalents_and_short_term_investments number Cash cash equivalents and short term investments
cash_and_cash_equivalents number Cash and cash equivalents
cash_equivalents number Cash equivalents
cash_financial number Cash financial
other_short_term_investments number Other short term investments
restricted_cash number Restricted cash
total_receivables number Total receivables
accounts_receivable number Accounts receivable
gross_accounts_receivable number Gross accounts receivable
allowance_for_doubtful_accounts_receivable number Allowance for doubtful accounts receivable
receivables_adjustments_allowances number Receivables adjustments allowances
other_receivables number Other receivables
due_from_related_parties_current number Due from related parties current
taxes_receivable number Taxes receivable
accrued_interest_receivable number Accrued interest receivable
notes_receivable number Notes receivable
loans_receivable number Loans receivable
total_inventory number Total inventory
inventories_adjustments_allowances number Inventories adjustments allowances
other_inventories number Other inventories
finished_goods number Finished goods
work_in_process number Work in process
raw_materials number Raw materials
prepaid_assets number Prepaid assets
current_deferred_assets number Current deferred assets
current_deferred_taxes_assets number Current deferred taxes assets
assets_held_for_sale_current number Assets held for sale current
hedging_assets_current number Hedging assets current
other_current_assets number Other current assets
total_non_current_assets number Total non current assets
financial_assets number Financial assets
investments_and_advances number Investments and advances
other_investments number Other investments
investment_in_financial_assets number Investment in financial assets
held_to_maturity_securities number Held to maturity securities
available_for_sale_securities number Available for sale securities
financial_assets_designated_as_fair_value_through_profit_or_loss_total number Financial assets designated as fair value through profit or loss total
trading_securities number Trading securities
long_term_equity_investment number Long term equity investment
investments_in_joint_ventures_at_cost number Investments in joint ventures at cost
investments_in_other_ventures_under_equity_method number Investments in other ventures under equity method
investments_in_associates_at_cost number Investments in associates at cost
investments_in_subsidiaries_at_cost number Investments in subsidiaries at cost
investment_properties number Investment properties
goodwill number Goodwill
other_intangible_assets number Other intangible assets
total_goodwill_and_intangible_assets number Total goodwill and intangible assets
net_ppe number Net ppe
gross_ppe number Gross ppe
accumulated_depreciation number Accumulated depreciation
leases number Leases
construction_in_progress number Construction in progress
other_properties number Other properties
machinery_furniture_equipment number Machinery furniture equipment
buildings_and_improvements number Buildings and improvements
land_and_improvements number Land and improvements
properties number Properties
non_current_accounts_receivable number Non current accounts receivable
non_current_note_receivables number Non current note receivables
due_from_related_parties_non_current number Due from related parties non current
non_current_prepaid_assets number Non current prepaid assets
non_current_deferred_assets number Non current deferred assets
non_current_deferred_taxes_assets number Non current deferred taxes assets
defined_pension_benefit number Defined pension benefit
other_non_current_assets number Other non current assets
total_liabilities_net_minority_interest number Total liabilities net minority interest
total_current_liabilities number Total current liabilities
current_debt_and_capital_lease_obligation number Current debt and capital lease obligation
current_debt number Current debt
current_capital_lease_obligation number Current capital lease obligation
other_current_borrowings number Other current borrowings
line_of_credit number Line of credit
commercial_paper number Commercial paper
current_notes_payable number Current notes payable
current_provisions number Current provisions
total_payables_and_accrued_expenses number Total payables and accrued expenses
accounts_payable number Accounts payable
current_accrued_expenses number Current accrued expenses
interest_payable number Interest payable
payables number Payables
other_payable number Other payable
due_to_related_parties_current number Due to related parties current
dividends_payable number Dividends payable
total_tax_payable number Total tax payable
income_tax_payable number Income tax payable
pension_and_other_post_retirement_benefit_plans_current number Pension and other post retirement benefit plans current
employee_benefits number Employee benefits
current_deferred_liabilities number Current deferred liabilities
current_deferred_revenue number Current deferred revenue
current_deferred_taxes_liabilities number Current deferred taxes liabilities
other_current_liabilities number Other current liabilities
liabilities_held_for_sale_non_current number Liabilities held for sale non current
total_non_current_liabilities_net_minority_interest number Total non current liabilities net minority interest
total_long_term_debt_and_capital_lease_obligation number Total long term debt and capital lease obligation
long_term_debt number Long term debt
long_term_capital_lease_obligation number Long term capital lease obligation
long_term_provisions number Long term provisions
non_current_pension_and_other_postretirement_benefit_plans number Non current pension and other postretirement benefit plans
non_current_accrued_expenses number Non current accrued expenses
due_to_related_parties_non_current number Due to related parties non current
trade_and_other_payables_non_current number Trade and other payables non current
non_current_deferred_liabilities number Non current deferred liabilities
non_current_deferred_revenue number Non current deferred revenue
non_current_deferred_taxes_liabilities number Non current deferred taxes liabilities
other_non_current_liabilities number Other non current liabilities
preferred_securities_outside_stock_equity number Preferred securities outside stock equity
derivative_product_liabilities number Derivative product liabilities
capital_lease_obligations number Capital lease obligations
restricted_common_stock number Restricted common stock
total_equity_gross_minority_interest number Total equity gross minority interest
stockholders_equity number Stockholders equity
common_stock_equity number Common stock equity
preferred_stock_equity number Preferred stock equity
other_equity_interest number Other equity interest
minority_interest number Minority interest
total_capitalization number Total capitalization
net_tangible_assets number Net tangible assets
tangible_book_value number Tangible book value
invested_capital number Invested capital
working_capital number Working capital
common_stock number Common stock
preferred_stock number Preferred stock
total_partnership_capital number Total partnership capital
general_partnership_capital number General partnership capital
limited_partnership_capital number Limited partnership capital
capital_stock number Capital stock
other_capital_stock number Other capital stock
additional_paid_in_capital number Additional paid in capital
retained_earnings number Retained earnings
treasury_stock number Treasury stock
treasury_shares_number number Treasury shares number
preferred_shares_number number Preferred shares number
ordinary_shares_number number Ordinary shares number
share_issued number Share issued
gains_losses_not_affecting_retained_earnings number Gains losses not affecting retained earnings
other_equity_adjustments number Other equity adjustments
fixed_assets_revaluation_reserve number Fixed assets revaluation reserve
foreign_currency_translation_adjustments number Foreign currency translation adjustments
minimum_pension_liabilities number Minimum pension liabilities
unrealized_gain_loss number Unrealized gain loss
net_debt number Net debt
total_debt number Total debt

JSON request example

https://api.twelvedata.com/balance_sheet/consolidated?symbol=AAPL&apikey=demo

Cash FlowHigh Demand

Returns complete cash flow of a company showing the net amount of cash and cash equivalents being transferred into and out of business.

HTTP request example

https://api.twelvedata.com/cash_flow?symbol=AAPL&apikey=your_api_key

This request will return JSON with the following structure

{
  "meta": {
    "symbol": "AAPL",
    "name": "Apple Inc",
    "currency": "USD",
    "exchange": "NASDAQ",
    "mic_code": "XNAS",
    "exchange_timezone": "America/New_York",
    "period": "Quarterly"
  },
  "cash_flow": [
    {
      "fiscal_date": "2021-12-31",
      "quarter": 1,
      "operating_activities": {
        "net_income": 34630000000,
        "depreciation": 2697000000,
        "deferred_taxes": 682000000,
        "stock_based_compensation": 2265000000,
        "other_non_cash_items": 167000000,
        "accounts_receivable": -13746000000,
        "accounts_payable": 19813000000,
        "other_assets_liabilities": 458000000,
        "operating_cash_flow": 46966000000
      },
      "investing_activities": {
        "capital_expenditures": -2803000000,
        "net_intangibles": null,
        "net_acquisitions": null,
        "purchase_of_investments": -34913000000,
        "sale_of_investments": 21984000000,
        "other_investing_activity": -374000000,
        "investing_cash_flow": -16106000000
      },
      "financing_activities": {
        "long_term_debt_issuance": null,
        "long_term_debt_payments": 0,
        "short_term_debt_issuance": -1000000000,
        "common_stock_issuance": null,
        "common_stock_repurchase": -20478000000,
        "common_dividends": -3732000000,
        "other_financing_charges": -2949000000,
        "financing_cash_flow": -28159000000
      },
      "end_cash_position": 38630000000,
      "income_tax_paid": 5235000000,
      "interest_paid": 531000000,
      "free_cash_flow": 49769000000
    }
  ]
}

HTTP route

/cash_flow

API credits

100 per symbol

API parameters

Key Type Description
symbol string • Required parameter
• Symbol ticker of instrument
• For preffered stocks use dot(.) delimiter
E.g. BRK.A or BRK.B will be correct
figi string • Parameter is optional
• Filter by financial instrument global identifier (FIGI)
exchange string • Parameter is optional
• Exchange where instrument is traded
mic_code string • Parameter is optional
• Market Identifier Code (MIC) under ISO 10383 standard
country string • Parameter is optional
• Country where instrument is traded
period string • Parameter is optional
• Values should be annual or quarterly
start_date string • Parameter is optional
• Format 2006-01-02
end_date string • Parameter is optional
• Format 2006-01-02
apikey string • Required parameter
• Your API key upgraded to the Pro plan or above, which can be obtained here

Response

Key Type Description
fiscal_date string Date of the cash flow release
quarter string Fiscal quarter. Visible when &period=quarterly
net_income number Returns net income (NI). Calculated as sales minus cost of goods sold
depreciation number Represents depreciation and amortization measure
deferred_taxes number Stands for taxes that are owed but are not due to be paid until a future date
stock_based_compensation number Refers to share-based compensation as the way of paying employees, executives, and directors of a company with equity in the business
other_non_cash_items number Represents other non-cash items
accounts_receivable number Represents the balance of money due to a firm for goods or services delivered or used but not yet paid for by customers
accounts_payable number Refers to an account within the general ledger that represents an obligation to pay off a short-term debt to creditors or suppliers
other_assets_liabilities number Represents cumulative changes in inventory, other current assets, other current liabilities, and other working capital
operating_cash_flow number Returns operating cash flow (OCF) measure representing a total amount of cash generated by company's normal business operations
capital_expenditures number Capital expenditures (CapEx) are funds used by a company to acquire, upgrade, and maintain physical assets (PPE)
net_intangibles number Represents purchase of a not physical asset
net_acquisitions number Refers to net amount of business purchase and sale
purchase_of_investments number Represents how much money has been used in making investments, including purchases of physical assets, investments in securities
sale_of_investments number Represents how much money has been generated from the sale of securities or assets
other_investing_activity number Represents other investing activity
investing_cash_flow number Returns total amount of cash flow used in investments
long_term_debt_issuance number Refers to the issuance of any financial obligations that extend beyond a 12 months period
long_term_debt_payments number Refers to the payments of any financial obligations that extend beyond a 12 months period
short_term_debt_issuance number Refers to the issuance of any financial obligations that are expected to be paid off within a year
common_stock_issuance number Represents a transaction whereby a company issues its own shares to the marketplace
common_stock_repurchase number Represents a transaction whereby a company buys back its own shares from the marketplace
common_dividends number Returns value of payment doled out by a company to its stockholders in the form of periodic distributions of cash
other_financing_charges number Represents other financing charges
financing_cash_flow number Returns cash flow from financing activities (CFF), which shows the net flows of cash that are used to fund the company
end_cash_position number Returns the amount of cash a company has when adding the change in cash and beginning cash balance for the current fiscal period
income_tax_paid number Refers to supplemental data about income tax paid
interest_paid number Refers to supplemental data about interest paid
free_cash_flow number Represents the cash a company generates after accounting for cash outflows to support operations and maintain its capital assets

JSON request example

https://api.twelvedata.com/cash_flow?symbol=AAPL&apikey=demo

Cash Flow consolidated

Returns consolidated cash flow of a company showing the net amount of cash and cash equivalents being transferred into and out of business.

HTTP request example

https://api.twelvedata.com/cash_flow/consolidated?symbol=AAPL&apikey=your_api_key

This request will return JSON with the following structure

{
  "cash_flow": [
    {
      "fiscal_date": "2023-09-30",
      "cash_flow_from_operating_activities": {
        "net_income_from_continuing_operations": 96995000000,
        "operating_cash_flow": 110543000000,
        "cash_flow_from_continuing_operating_activities": 110543000000,
        "cash_from_discontinued_operating_activities": 108488000000,
        "cash_flow_from_discontinued_operation": 108488000000,
        "free_cash_flow": 99584000000,
        "cash_flows_from_used_in_operating_activities_direct": 108488000000,
        "taxes_refund_paid": 108488000000,
        "taxes_refund_paid_direct": 108488000000,
        "interest_received": 108488000000,
        "interest_received_direct": 108488000000,
        "interest_paid": 108488000000,
        "interest_paid_direct": 108488000000,
        "dividend_received": 108488000000,
        "dividend_received_direct": 108488000000,
        "dividend_paid": 108488000000,
        "dividend_paid_direct": 108488000000,
        "change_in_working_capital": -6577000000,
        "change_in_other_working_capital": 108488000000,
        "change_in_receivables": -417000000,
        "changes_in_account_receivables": -1688000000,
        "change_in_payables_and_accrued_expense": -1889000000,
        "change_in_accrued_expense": 108488000000,
        "change_in_payable": -1889000000,
        "change_in_dividend_payable": 108488000000,
        "change_in_account_payable": -1889000000,
        "change_in_tax_payable": 108488000000,
        "change_in_income_tax_payable": 108488000000,
        "change_in_interest_payable": 108488000000,
        "change_in_other_current_liabilities": 3031000000,
        "change_in_other_current_assets": -5684000000,
        "change_in_inventory": -1618000000,
        "change_in_prepaid_assets": 108488000000,
        "other_non_cash_items": -2227000000,
        "excess_tax_benefit_from_stock_based_compensation": 108488000000,
        "stock_based_compensation": 10833000000,
        "unrealized_gain_loss_on_investment_securities": 108488000000,
        "provision_and_write_off_of_assets": 108488000000,
        "asset_impairment_charge": 108488000000,
        "amortization_of_securities": 108488000000,
        "deferred_tax": 108488000000,
        "deferred_income_tax": 108488000000,
        "depreciation_amortization_depletion": 11519000000,
        "depletion": 108488000000,
        "depreciation_and_amortization": 11519000000,
        "amortization_cash_flow": 108488000000,
        "amortization_of_intangibles": 108488000000,
        "depreciation": 108488000000,
        "operating_gains_losses": 108488000000,
        "pension_and_employee_benefit_expense": 108488000000,
        "earnings_losses_from_equity_investments": 108488000000,
        "gain_loss_on_investment_securities": 108488000000,
        "net_foreign_currency_exchange_gain_loss": 108488000000,
        "gain_loss_on_sale_of_ppe": 108488000000,
        "gain_loss_on_sale_of_business": 108488000000
      },
      "cash_flow_from_investing_activities": {
        "investing_cash_flow": 3705000000,
        "cash_flow_from_continuing_investing_activities": 3705000000,
        "cash_from_discontinued_investing_activities": 108488000000,
        "net_other_investing_changes": -1337000000,
        "interest_received_cfi": 108488000000,
        "dividends_received_cfi": 108488000000,
        "net_investment_purchase_and_sale": 16001000000,
        "sale_of_investment": 45514000000,
        "purchase_of_investment": -29513000000,
        "net_investment_properties_purchase_and_sale": 108488000000,
        "sale_of_investment_properties": 108488000000,
        "purchase_of_investment_properties": 108488000000,
        "net_business_purchase_and_sale": 108488000000,
        "sale_of_business": 108488000000,
        "purchase_of_business": 108488000000,
        "net_intangibles_purchase_and_sale": 108488000000,
        "sale_of_intangibles": 108488000000,
        "purchase_of_intangibles": 108488000000,
        "net_ppe_purchase_and_sale": -10959000000,
        "sale_of_ppe": 108488000000,
        "purchase_of_ppe": -10959000000,
        "capital_expenditure_reported": 108488000000,
        "capital_expenditure": -10959000000
      },
      "cash_flow_from_financing_activities": {
        "financing_cash_flow": -108488000000,
        "cash_flow_from_continuing_financing_activities": -108488000000,
        "cash_from_discontinued_financing_activities": 108488000000,
        "net_other_financing_charges": -6012000000,
        "interest_paid_cff": 108488000000,
        "proceeds_from_stock_option_exercised": 108488000000,
        "cash_dividends_paid": -15025000000,
        "preferred_stock_dividend_paid": 108488000000,
        "common_stock_dividend_paid": -15025000000,
        "net_preferred_stock_issuance": 108488000000,
        "preferred_stock_payments": 108488000000,
        "preferred_stock_issuance": 108488000000,
        "net_common_stock_issuance": -77550000000,
        "common_stock_payments": -77550000000,
        "common_stock_issuance": 108488000000,
        "repurchase_of_capital_stock": -77550000000,
        "net_issuance_payments_of_debt": -9901000000,
        "net_short_term_debt_issuance": -3978000000,
        "short_term_debt_payments": 108488000000,
        "short_term_debt_issuance": 108488000000,
        "net_long_term_debt_issuance": -5923000000,
        "long_term_debt_payments": -11151000000,
        "long_term_debt_issuance": 5228000000,
        "issuance_of_debt": 5228000000,
        "repayment_of_debt": -11151000000,
        "issuance_of_capital_stock": 108488000000
      },
      "supplemental_data": {
        "interest_paid_supplemental_data": 3803000000,
        "income_tax_paid_supplemental_data": 18679000000
      },
      "foreign_and_domestic_sales": {
        "foreign_sales": 108488000000,
        "domestic_sales": 108488000000,
        "adjusted_geography_segment_data": 108488000000
      },
      "cash_position": {
        "beginning_cash_position": 24977000000,
        "end_cash_position": 30737000000,
        "changes_in_cash": 5760000000,
        "other_cash_adjustment_outside_change_in_cash": 108488000000,
        "other_cash_adjustment_inside_change_in_cash": 108488000000,
        "effect_of_exchange_rate_changes": 108488000000
      },
      "direct_method_cash_flow": {
        "classes_of_cash_receipts_from_operating_activities": 108488000000,
        "other_cash_receipts_from_operating_activities": 108488000000,
        "receipts_from_government_grants": 108488000000,
        "receipts_from_customers": 108488000000,
        "classes_of_cash_payments": 108488000000,
        "other_cash_payments_from_operating_activities": 108488000000,
        "payments_on_behalf_of_employees": 108488000000,
        "payments_to_suppliers_for_goods_and_services": 108488000000
      }
    }
  ],
  "status": "ok"
}

HTTP route

/cash_flow/consolidated

API credits

100 per symbol

API parameters

Key Type Description
symbol string • Required parameter
• Symbol ticker of instrument
• For preffered stocks use dot(.) delimiter
E.g. BRK.A or BRK.B will be correct
figi string • Parameter is optional
• Filter by financial instrument global identifier (FIGI)
exchange string • Parameter is optional
• Exchange where instrument is traded
mic_code string • Parameter is optional
• Market Identifier Code (MIC) under ISO 10383 standard
country string • Parameter is optional
• Country where instrument is traded
period string • Parameter is optional
• Values should be annual or quarterly
start_date string • Parameter is optional
• Format 2006-01-02
end_date string • Parameter is optional
• Format 2006-01-02
apikey string • Required parameter
• Your API key upgraded to the Pro plan or above, which can be obtained here

Response

Click to expand
Key Type Description
fiscal_date string Fiscal date
net_income_from_continuing_operations number Net income from continuing operations
operating_cash_flow number Operating cash flow
cash_flow_from_continuing_operating_activities number Cash flow from continuing operating activities
cash_from_discontinued_operating_activities number Cash from discontinued operating activities
cash_flow_from_discontinued_operation number Cash flow from discontinued operation
free_cash_flow number Free cash flow
cash_flows_from_used_in_operating_activities_direct number Cash flows from used in operating activities direct
taxes_refund_paid number Taxes refund paid
taxes_refund_paid_direct number Taxes refund paid direct
interest_received number Interest received
interest_received_direct number Interest received direct
interest_paid number Interest paid
interest_paid_direct number Interest paid direct
dividend_received number Dividend received
dividend_received_direct number Dividend received direct
dividend_paid number Dividend paid
dividend_paid_direct number Dividend paid direct
change_in_working_capital number Change in working capital
change_in_other_working_capital number Change in other working capital
change_in_receivables number Change in receivables
changes_in_account_receivables number Changes in account receivables
change_in_payables_and_accrued_expense number Change in payables and accrued expense
change_in_accrued_expense number Change in accrued expense
change_in_payable number Change in payable
change_in_dividend_payable number Change in dividend payable
change_in_account_payable number Change in account payable
change_in_tax_payable number Change in tax payable
change_in_income_tax_payable number Change in income tax payable
change_in_interest_payable number Change in interest payable
change_in_other_current_liabilities number Change in other current liabilities
change_in_other_current_assets number Change in other current assets
change_in_inventory number Change in inventory
change_in_prepaid_assets number Change in prepaid assets
other_non_cash_items number Other non cash items
excess_tax_benefit_from_stock_based_compensation number Excess tax benefit from stock based compensation
stock_based_compensation number Stock based compensation
unrealized_gain_loss_on_investment_securities number Unrealized gain loss on investment securities
provision_and_write_off_of_assets number Provision and write off of assets
asset_impairment_charge number Asset impairment charge
amortization_of_securities number Amortization of securities
deferred_tax number Deferred tax
deferred_income_tax number Deferred income tax
depreciation_amortization_depletion number Depreciation amortization depletion
depletion number Depletion
depreciation_and_amortization number Depreciation and amortization
amortization_cash_flow number Amortization cash flow
amortization_of_intangibles number Amortization of intangibles
depreciation number Depreciation
operating_gains_losses number Operating gains losses
pension_and_employee_benefit_expense number Pension and employee benefit expense
earnings_losses_from_equity_investments number Earnings losses from equity investments
gain_loss_on_investment_securities number Gain loss on investment securities
net_foreign_currency_exchange_gain_loss number Net foreign currency exchange gain loss
gain_loss_on_sale_of_ppe number Gain loss on sale of ppe
gain_loss_on_sale_of_business number Gain loss on sale of business
investing_cash_flow number Investing cash flow
cash_flow_from_continuing_investing_activities number Cash flow from continuing investing activities
cash_from_discontinued_investing_activities number Cash from discontinued investing activities
net_other_investing_changes number Net other investing changes
interest_received_cfi number Interest received cfi
dividends_received_cfi number Dividends received cfi
net_investment_purchase_and_sale number Net investment purchase and sale
sale_of_investment number Sale of investment
purchase_of_investment number Purchase of investment
net_investment_properties_purchase_and_sale number Net investment properties purchase and sale
sale_of_investment_properties number Sale of investment properties
purchase_of_investment_properties number Purchase of investment properties
net_business_purchase_and_sale number Net business purchase and sale
sale_of_business number Sale of business
purchase_of_business number Purchase of business
net_intangibles_purchase_and_sale number Net intangibles purchase and sale
sale_of_intangibles number Sale of intangibles
purchase_of_intangibles number Purchase of intangibles
net_ppe_purchase_and_sale number Net ppe purchase and sale
sale_of_ppe number Sale of ppe
purchase_of_ppe number Purchase of ppe
capital_expenditure_reported number Capital expenditure reported
capital_expenditure number Capital expenditure
financing_cash_flow number Financing cash flow
cash_flow_from_continuing_financing_activities number Cash flow from continuing financing activities
cash_from_discontinued_financing_activities number Cash from discontinued financing activities
net_other_financing_charges number Net other financing charges
interest_paid_cff number Interest paid cff
proceeds_from_stock_option_exercised number Proceeds from stock option exercised
cash_dividends_paid number Cash dividends paid
preferred_stock_dividend_paid number Preferred stock dividend paid
common_stock_dividend_paid number Common stock dividend paid
net_preferred_stock_issuance number Net preferred stock issuance
preferred_stock_payments number Preferred stock payments
preferred_stock_issuance number Preferred stock issuance
net_common_stock_issuance number Net common stock issuance
common_stock_payments number Common stock payments
common_stock_issuance number Common stock issuance
repurchase_of_capital_stock number Repurchase of capital stock
net_issuance_payments_of_debt number Net issuance payments of debt
net_short_term_debt_issuance number Net short term debt issuance
short_term_debt_payments number Short term debt payments
short_term_debt_issuance number Short term debt issuance
net_long_term_debt_issuance number Net long term debt issuance
long_term_debt_payments number Long term debt payments
long_term_debt_issuance number Long term debt issuance
issuance_of_debt number Issuance of debt
repayment_of_debt number Repayment of debt
issuance_of_capital_stock number Issuance of capital stock
interest_paid_supplemental_data number Interest paid supplemental data
income_tax_paid_supplemental_data number Income tax paid supplemental data
foreign_sales number Foreign sales
domestic_sales number Domestic sales
adjusted_geography_segment_data number Adjusted geography segment data
beginning_cash_position number Beginning cash position
end_cash_position number End cash position
changes_in_cash number Changes in cash
other_cash_adjustment_outside_change_in_cash number Other cash adjustment outside change in cash
other_cash_adjustment_inside_change_in_cash number Other cash adjustment inside change in cash
effect_of_exchange_rate_changes number Effect of exchange rate changes
classes_of_cash_receipts_from_operating_activities number Classes of cash receipts from operating activities
other_cash_receipts_from_operating_activities number Other cash receipts from operating activities
receipts_from_government_grants number Receipts from government grants
receipts_from_customers number Receipts from customers
classes_of_cash_payments number Classes of cash payments
other_cash_payments_from_operating_activities number Other cash payments from operating activities
payments_on_behalf_of_employees number Payments on behalf of employees
payments_to_suppliers_for_goods_and_services number Payments to suppliers for goods and services

JSON request example

https://api.twelvedata.com/cash_flow/consolidated?symbol=AAPL&apikey=demo

Options Expiration

Return the expiration dates of an option contract.

HTTP request example

https://api.twelvedata.com/options/expiration?symbol=AAPL&apikey=your_api_key

This request will return JSON with the following structure

{
  "meta": {
    "symbol": "AAPL",
    "name": "Apple Inc",
    "currency": "USD",
    "exchange": "NASDAQ",
    "mic_code": "XNAS",
    "exchange_timezone": "America/New_York"
  },
  "dates": [
    "2021-09-17",
    "2021-09-24",
    "2021-10-01",
    "2021-10-08",
    "2021-10-15",
    "2021-10-22",
    "2021-11-19",
    "2021-12-17",
    "2022-01-21",
    "2022-03-18",
    "2022-04-14",
    "2022-06-17",
    "2022-09-16",
    "2023-01-20",
    "2023-03-17",
    "2023-06-16",
    "2023-09-15"
  ]
}

HTTP route

/options/expiration

API credits

200 per symbol

API parameters

Key Type Description
symbol string • Required parameter
• Symbol ticker of instrument
• For preffered stocks use dot(.) delimiter
E.g. BRK.A or BRK.B will be correct
figi string • Parameter is optional
• Filter by financial instrument global identifier (FIGI)
exchange string • Parameter is optional
• Exchange where instrument is traded
mic_code string • Parameter is optional
• Market Identifier Code (MIC) under ISO 10383 standard
country string • Parameter is optional
• Country where instrument is traded
apikey string • Required parameter
• Your API key upgraded to the Pro plan or above, which can be obtained here

Response

Key Type Description
dates array Returns an array of future expiration dates in ascending order

JSON request example

https://api.twelvedata.com/options/expiration?symbol=AAPL&apikey=demo

Options Chain

Returns a listing of all available options contracts for given security. It shows all listed puts, calls, their expiration, strike prices, and pricing information for a single underlying asset within a given maturity period.

HTTP request example

https://api.twelvedata.com/options/chain?symbol=AAPL&expiration_date=2022-01-21&apikey=your_api_key

This request will return JSON with the following structure

{
  "meta": {
    "symbol": "AAPL",
    "name": "Apple Inc",
    "currency": "USD",
    "exchange": "NASDAQ",
    "mic_code": "XNAS",
    "exchange_timezone": "America/New_York"
  },
  "calls": [
    {
      "contract_name": "AAPL Option Call 21-01-2022 145",
      "option_id": "AAPL220121C00145000",
      "last_trade_date": "2021-09-13 14:53:00",
      "strike": 145,
      "last_price": 11.95,
      "bid": 11.95,
      "ask": 12.15,
      "change": -3.2700005,
      "percent_change": -21.48489,
      "volume": 1318,
      "open_interest": 48688,
      "implied_volatility": 0.2850108120727538,
      "in_the_money": true
    }
  ],
  "puts": [
    {
      "contract_name": "AAPL Option Put 21-01-2022 150",
      "option_id": "AAPL220121P00150000",
      "last_trade_date": "2021-09-13 14:52:00",
      "strike": 150,
      "last_price": 10.25,
      "bid": 10.2,
      "ask": 10.4,
      "change": 2.4499998,
      "percent_change": 31.410254,
      "volume": 3588,
      "open_interest": 41797,
      "implied_volatility": 0.27579459564208975,
      "in_the_money": true
    }
  ]
}

HTTP route

/options/chain

API credits

50 per symbol

API parameters

Key Type Description
symbol string • Required parameter
• Symbol ticker of instrument
• For preffered stocks use dot(.) delimiter
E.g. BRK.A or BRK.B will be correct
figi string • Parameter is optional
• Filter by financial instrument global identifier (FIGI)
exchange string • Parameter is optional
• Exchange where instrument is traded
mic_code string • Parameter is optional
• Market Identifier Code (MIC) under ISO 10383 standard
country string • Parameter is optional
• Country where instrument is traded
expiration_date string • Required parameter, if option_id is not specified
• Expiration date of an option contract
• Could be requested via /options/expiration endpoint
• Format 2006-01-02
option_id string • Required parameter, if expiration_date is not specified
• Contract name of an option
• Format AAPL220121C00505000
side string • Parameter is optional
• Specifies calls or puts side of an option
• Works only when expiration_date parameter is set
apikey string • Required parameter
• Your API key upgraded to the Pro plan or above, which can be obtained here

Response

Key Type Description
contract_name string Expanded components of an options symbol
option_id string Option symbol as per OCC (Options Clearing Corporation) symbology
last_trade_date string Refers to the last trade datetime of an option
strike number Returns strike price of an option at which it can be exercised
last_price number Returns price of the last trade if available
bid number Bid price of the last trade if available
ask number Ask price of the last trade if available
change number Change of current price compared to previous day close
percent_change number Change of current price compared to previous day close in percentage
volume number Refers to the number of trades completed in a day
open_interest number Refers to the number of contracts that are held by traders and investors in active positions, ready to be traded
implied_volatility number Represents implied volatility (IV) in percentage
in_the_money bool true if in-the-money (ITM), false if out of the money (OTM)

JSON request example

https://api.twelvedata.com/options/chain?symbol=AAPL&expiration_date=2022-01-21&apikey=demo

Options Price

Returns a recent price for the options contract.

HTTP request example

https://api.twelvedata.com/options/price?option_id=AAPL240216C00130000&apikey=your_api_key

This request will return JSON with the following structure

{
    "last_price": "200.99001"
}

HTTP route

/options/price

API credits

1 per request

API parameters

Key Type Description
option_id string • Required parameter
• Contract name of an option
• Format AAPL220121C00505000

Response

Key Type Description
last_price number Returns price of the last trade if available

JSON request example

https://api.twelvedata.com/options/price?option_id=AAPL240216C00130000&apikey=your_api_key

Key ExecutivesUseful

Returns individuals at the highest level of management of an organization.

HTTP request example

https://api.twelvedata.com/key_executives?symbol=AAPL&apikey=your_api_key

This request will return JSON with the following structure

{
  "meta": {
    "symbol": "AAPL",
    "name": "Apple Inc",
    "currency": "USD",
    "exchange": "NASDAQ",
    "mic_code": "XNAS",
    "exchange_timezone": "America/New_York"
  },
  "key_executives": [
    {
      "name": "Mr. Timothy D. Cook",
      "title": "CEO & Director",
      "age": 59,
      "year_born": 1961,
      "pay": 14769259
    },
    {
      "name": "Mr. Luca  Maestri",
      "title": "CFO & Sr. VP",
      "age": 56,
      "year_born": 1964,
      "pay": 4595583
    },
    {
      "name": "Mr. Jeffrey E. Williams",
      "title": "Chief Operating Officer",
      "age": 56,
      "year_born": 1964,
      "pay": 4594137
    }
  ]
}

HTTP route

/key_executives

API credits

1000 per symbol

API parameters

Key Type Description
symbol string • Required parameter
• Symbol ticker of instrument
• For preffered stocks use dot(.) delimiter
E.g. BRK.A or BRK.B will be correct
figi string • Parameter is optional
• Filter by financial instrument global identifier (FIGI)
exchange string • Parameter is optional
• Exchange where instrument is traded
mic_code string • Parameter is optional
• Market Identifier Code (MIC) under ISO 10383 standard
country string • Parameter is optional
• Country where instrument is traded
apikey string • Required parameter
• Your API key upgraded to the Pro plan or above, which can be obtained here

Response

Key Type Description
name string Full name of an executive, including first name, middle name, last name, and suffix
title string Refers to job title
age number Current age of an executive if available
year_born number Year of birth of an executive if available
pay number Total salary of an executive if available

JSON request example

https://api.twelvedata.com/key_executives?symbol=AAPL&apikey=demo

Institutional Holders

Returns the amount of the company’s available stock owned by institutions (pension funds, insurance companies, investment firms, private foundations, endowments, or other large entities that manage funds on behalf of others).

HTTP request example

https://api.twelvedata.com/institutional_holders?symbol=AAPL&apikey=your_api_key

This request will return JSON with the following structure

{
  "meta": {
    "symbol": "AAPL",
    "name": "Apple Inc",
    "currency": "USD",
    "exchange": "NASDAQ",
    "mic_code": "XNAS",
    "exchange_timezone": "America/New_York"
  },
  "institutional_holders": [
    {
      "entity_name": "Vanguard Group, Inc. (The)",
      "date_reported": "2021-06-30",
      "shares": 1264936543,
      "value": 173245708929,
      "percent_held": 0.0765
    },
    {
      "entity_name": "Blackrock Inc.",
      "date_reported": "2021-06-30",
      "shares": 1028698316,
      "value": 140890521359,
      "percent_held": 0.0622
    },
    {
      "entity_name": "Berkshire Hathaway, Inc",
      "date_reported": "2021-06-30",
      "shares": 887135554,
      "value": 121502085475,
      "percent_held": 0.0537
    }
  ]
}

HTTP route

/institutional_holders

API credits

1500 per symbol

API parameters

Key Type Description
symbol string • Required parameter
• Symbol ticker of instrument
• For preffered stocks use dot(.) delimiter
E.g. BRK.A or BRK.B will be correct
figi string • Parameter is optional
• Filter by financial instrument global identifier (FIGI)
exchange string • Parameter is optional
• Exchange where instrument is traded
mic_code string • Parameter is optional
• Market Identifier Code (MIC) under ISO 10383 standard
country string • Parameter is optional
• Country where instrument is traded
apikey string • Required parameter
• Your API key upgraded to the Pro plan or above, which can be obtained here

Response

Key Type Description
entity_name string Refers to the legal name of the institution
date_reported string Refers to date reported
shares number Refers to the number of shares owned
value number Total value of shares owned, calculated by multiplying shares by the current price
percent_held number Represents the percentage of shares outstanding that are owned by the financial institution

JSON request example

https://api.twelvedata.com/institutional_holders?symbol=AAPL&apikey=demo

Fund Holders

Returns the amount of the company’s available stock owned by mutual fund holders.

HTTP request example

https://api.twelvedata.com/fund_holders?symbol=AAPL&apikey=your_api_key

This request will return JSON with the following structure

{
  "meta": {
    "symbol": "AAPL",
    "name": "Apple Inc",
    "currency": "USD",
    "exchange": "NASDAQ",
    "mic_code": "XNAS",
    "exchange_timezone": "America/New_York"
  },
  "fund_holders": [
    {
      "entity_name": "Vanguard Total Stock Market Index Fund",
      "date_reported": "2021-06-30",
      "shares": 447734657,
      "value": 61321738622,
      "percent_held": 0.0271
    },
    {
      "entity_name": "Vanguard 500 Index Fund",
      "date_reported": "2021-06-30",
      "shares": 325785979,
      "value": 44619647683,
      "percent_held": 0.0197
    },
    {
      "entity_name": "SPDR S&P 500 ETF Trust",
      "date_reported": "2021-06-30",
      "shares": 161505783,
      "value": 22119832039,
      "percent_held": 0.0098
    }
  ]
}

HTTP route

/fund_holders

API credits

1500 per symbol

API parameters

Key Type Description
symbol string • Required parameter
• Symbol ticker of instrument
• For preffered stocks use dot(.) delimiter
E.g. BRK.A or BRK.B will be correct
figi string • Parameter is optional
• Filter by financial instrument global identifier (FIGI)
exchange string • Parameter is optional
• Exchange where instrument is traded
mic_code string • Parameter is optional
• Market Identifier Code (MIC) under ISO 10383 standard
country string • Parameter is optional
• Country where instrument is traded
apikey string • Required parameter
• Your API key upgraded to the Pro plan or above, which can be obtained here

Response

Key Type Description
entity_name string Refers to the legal name of the fund
date_reported string Refers to date reported
shares number Refers to the number of shares owned
value number Total value of shares owned, calculated by multiplying shares by the current price
percent_held number Represents the percentage of shares outstanding that are owned by the fund

JSON request example

https://api.twelvedata.com/fund_holders?symbol=AAPL&apikey=demo

Direct HoldersNew

Returns the amount of the stocks owned directly and recorded in the company's share registry.

HTTP request example

https://api.twelvedata.com/direct_holders?symbol=4261&apikey=your_api_key

This request will return JSON with the following structure

{
  "meta": {
    "symbol": "4261",
    "name": "Theeb Rent A Car Company",
    "currency": "SAR",
    "exchange": "Tadawul",
    "mic_code": "XSAU",
    "exchange_timezone": "Asia/Riyadh"
  },
  "direct_holders": [
    {
      "entity_name": "Growth Opportunities Co. For Trading",
      "date_reported": "2022-04-17",
      "shares": 2145700,
      "value": 154490400,
      "percent_held": null
    },
    {
      "entity_name": "Dhabib Nayef Mohammed Ahmed Al",
      "date_reported": "2022-04-17",
      "shares": 210700,
      "value": 15170400,
      "percent_held": null
    },
    {
      "entity_name": "Dhabib Mohammed Ahmed Abdullah Al",
      "date_reported": "2022-04-17",
      "shares": 10461900,
      "value": 753256800,
      "percent_held": null
    },
    {
      "entity_name": "Dhabib Mohammed Mahmoud Abdullah Al",
      "date_reported": "2022-04-17",
      "shares": 849981,
      "value": 61198632,
      "percent_held": null
    },
    {
      "entity_name": "Dhabib Hamood Abdullah Ibrahim Al",
      "date_reported": "2022-04-17",
      "shares": 5813600,
      "value": 418579200,
      "percent_held": null
    }
  ]
}

HTTP route

/direct_holders

API credits

1500 per symbol

API parameters

Key Type Description
symbol string • Required parameter
• Symbol ticker of instrument
• For preffered stocks use dot(.) delimiter
E.g. BRK.A or BRK.B will be correct
figi string • Parameter is optional
• Filter by financial instrument global identifier (FIGI)
exchange string • Parameter is optional
• Exchange where instrument is traded
mic_code string • Parameter is optional
• Market Identifier Code (MIC) under ISO 10383 standard
country string • Parameter is optional
• Country where instrument is traded
apikey string • Required parameter
• Your API key upgraded to the Pro plan or above, which can be obtained here

Response

Key Type Description
entity_name string Refers to the legal name of the fund
date_reported string Refers to date reported
shares number Refers to the number of shares owned
value number Total value of shares owned, calculated by multiplying shares by the current price
percent_held number Represents the percentage of shares outstanding that are owned by the fund

JSON request example

https://api.twelvedata.com/direct_holders?symbol=4261&apikey=demo

Last changesNew

Returns the latest changes of fundamental data. This endpoint helps consume API credits more efficiently and request new data once it is updated.

HTTP request example

https://api.twelvedata.com/last_change/:endpoint?apikey=demo&start_date=2023-10-14 10:00:00

This request will return JSON with the following structure

[
    {
        "symbol": "VFIAX",
        "mic_code": "XNAS",
        "last_change": "2023-10-14 12:22:48"
    },
    {
        "symbol": "AAPL",
        "mic_code": "XNAS",
        "last_change": "2023-10-14 12:22:48"
    }
]

HTTP route

/last_change/:endpoint

API credits

1 per request

API parameters

Parameter Details
apikey • Required parameter
• Your personal API key, which you can obtain for free here
• Type string
endpoint • Required parameter
• Endpoint name. Supported values: price_target, recommendations, statistics, insider_transactions, profile, mutual_funds_world_summary, mutual_funds_world, institutional_holders, analyst_rating, income_statement, cash_flow, balance_sheet, mutual_funds_list, mutual_funds_world_sustainability, mutual_funds_world_summary, mutual_funds_world_risk, mutual_funds_world_purchase_info, mutual_funds_world_composition, mutual_funds_world_performance, mutual_funds_world, etfs_list, etfs_world, etfs_world_summary, etfs_world_performance, etfs_world_risk, etfs_world_composition
start_date • Parameter is optional
• The starting date and time for data selection, in "2006-01-02 15:04:05" format
symbol • Parameter is optional
• Filter by symbol
exchange • Parameter is optional
• Filter by exchange name or mic code
mic_code • Parameter is optional
• Filter by market identifier code (MIC) under ISO 10383 standard
country • Parameter is optional
• Filter by country name or alpha code
page • Parameter is optional
• Page number; default 1
outputsize • Parameter is optional
• Number of records in response; default 30

Response

Key Type Description
symbol string Ticker of the company
mic_code string Market Identifier Code (MIC) under ISO 10383 standard
last_change string The date and time of last changes, in "2006-01-02 15:04:05" format.

JSON request example

https://api.twelvedata.com/last_change/profile?start_date=2023-10-14 10:00:00&apikey=your_api_key

Edgar filings archiveNew

Real-time and historical access to all forms, filings, and exhibits directly from the SEC's EDGAR system.

HTTP request example

https://api.twelvedata.com/edgar_filings/archive?apikey=your_api_key

This request will return JSON with the following structure

{
    "meta": {
        "symbol": "AAPL",
        "exchange": "NASDAQ",
        "mic_code": "XNGS",
        "type": "Common Stock"
    },
    "values": [
    {
        "cik": 1711463,
        "filed_at": 1726617600,
        "files": [
            {
                "name": "primary_doc.html",
                "type": "144",
                "url": "https://www.sec.gov/Archives/edgar/data/1711463/000197185724000581/xsl144X01/primary_doc.xml"
            },
            {
                "name": "primary_doc.xml",
                "size": 2980,
                "type": "144",
                "url": "https://www.sec.gov/Archives/edgar/data/1711463/000197185724000581/primary_doc.xml"
            },
            {
                "name": "0001971857-24-000581.txt",
                "size": 4382,
                "type": "archive_file",
                "url": "https://www.sec.gov/Archives/edgar/data/1711463/000197185724000581/0001971857-24-000581.txt"
            }
        ],
        "filing_url": "https://www.sec.gov/Archives/edgar/data/1711463/0001971857-24-000581-index.htm",
        "form_type": "144"
    }
}

HTTP route

/edgar_filings/archive

API credits

50 per request

API parameters

Parameter Details
apikey • Required parameter
• Your personal API key, which you can obtain for free here
• Type string
symbol • Parameter is optional
• Filter by symbol
figi Parameter is optional
• Filter by financial instrument global identifier (FIGI)
exchange • Parameter is optional
• Filter by exchange name or mic code
mic_code • Parameter is optional
• Filter by market identifier code (MIC) under ISO 10383 standard
country • Parameter is optional
• Filter by country name or alpha code
form_type • Parameter is optional
• Filter by form types, example 8-K, EX-1.1
filled_from • Parameter is optional
• Filter by filled time from, example 2024-01-01
filled_to • Parameter is optional
• Filter by filled time to, example 2024-01-01
page • Parameter is optional
• Page number; default 1
page_size • Parameter is optional
• Number of records in response; default 10

Response

Key Type Description
symbol string Ticker of the company
exchange string Exchange name where the company is listed
mic_code string Market Identifier Code (MIC) under ISO 10383 standard
type string Issue type of the stock
cik integer CIK code
filled_at integer Filing date in UNIX timestamp
form_type string Filing form type
files array Filing files
files.name string File name
files.size integer File size
files.type string File type
files.url string File full url
filing_url string Full URL of the filing
ticker array List of tickers

JSON request example

https://api.twelvedata.com/edgar_filings/archive

Analysis

Earnings EstimateUseful

This API endpoint returns analysts' estimate for a company's future quarterly and annual earnings per share (EPS).

HTTP request example

https://api.twelvedata.com/earnings_estimate?symbol=AAPL&apikey=your_api_key

This request will return JSON with the following structure

{
  "meta": {
    "symbol": "AAPL",
    "name": "Apple Inc",
    "currency": "USD",
    "exchange_timezone": "America/New_York",
    "exchange": "NASDAQ",
    "mic_code": "XNGS",
    "type": "Common Stock"
  },
  "earnings_estimate": [
    {
      "date": "2022-09-30",
      "period": "current_quarter",
      "number_of_analysts": 27,
      "avg_estimate": 1.26,
      "low_estimate": 1.13,
      "high_estimate": 1.35,
      "year_ago_eps": 1.24
    },
    {
      "date": "2022-12-31",
      "period": "next_quarter",
      "number_of_analysts": 23,
      "avg_estimate": 2.12,
      "low_estimate": 2.01,
      "high_estimate": 2.29,
      "year_ago_eps": 2.1
    },
    {
      "date": "2022-09-30",
      "period": "current_year",
      "number_of_analysts": 37,
      "avg_estimate": 6.1,
      "low_estimate": 5.96,
      "high_estimate": 6.4,
      "year_ago_eps": 5.61
    },
    {
      "date": "2023-09-30",
      "period": "next_year",
      "number_of_analysts": 37,
      "avg_estimate": 6.44,
      "low_estimate": 5.79,
      "high_estimate": 7.06,
      "year_ago_eps": 6.1
    }
  ],
  "status": "ok"
}

HTTP route

/earnings_estimate

API credits

20 per symbol

API parameters

Parameter Details
symbol • Required parameter
• Filter by symbol
figi • Parameter is optional
• Filter by financial instrument global identifier (FIGI)
country • Parameter is optional
• Filter by country name or alpha code
exchange • Parameter is optional
• Filter by exchange name or mic code
apikey • Required parameter
• Your API key at the Enterprise plan or above

Response

Key Description
period defines period of estimation, can be current_quarter, next_quarter, current_year, or next_year
number_of_analysts number of analysts that made the estimation
avg_estimate average estimation across analysts
low_estimate lowest estimation given by an analyst
high_estimate highest estimation given by an analyst
year_ago_eps average estimation of this period’s earnings given a year ago

JSON request example

https://api.twelvedata.com/earnings_estimate?symbol=aapl&apikey=demo

Revenue Estimate

This API endpoint returns analysts' estimate for a company's future quarterly and annual sales (total revenue).

HTTP request example

https://api.twelvedata.com/revenue_estimate?symbol=AAPL&apikey=your_api_key

This request will return JSON with the following structure

{
  "meta": {
    "symbol": "AAPL",
    "name": "Apple Inc",
    "currency": "USD",
    "exchange_timezone": "America/New_York",
    "exchange": "NASDAQ",
    "mic_code": "XNGS",
    "type": "Common Stock"
  },
  "revenue_estimate": [
    {
      "date": "2022-09-30",
      "period": "current_quarter",
      "number_of_analysts": 24,
      "avg_estimate": 88631500000,
      "low_estimate": 85144300000,
      "high_estimate": 92794900000,
      "year_ago_sales": 83360000000,
      "sales_growth": 0.06
    },
    {
      "date": "2022-12-31",
      "period": "next_quarter",
      "number_of_analysts": 20,
      "avg_estimate": 127693000000,
      "low_estimate": 122868000000,
      "high_estimate": 132979000000,
      "year_ago_sales": null,
      "sales_growth": null
    },
    {
      "date": "2022-09-30",
      "period": "current_year",
      "number_of_analysts": 36,
      "avg_estimate": 392509000000,
      "low_estimate": 389326000000,
      "high_estimate": 396977000000,
      "year_ago_sales": 365817000000,
      "sales_growth": 0.07
    },
    {
      "date": "2023-09-30",
      "period": "next_year",
      "number_of_analysts": 36,
      "avg_estimate": 411466000000,
      "low_estimate": 387836000000,
      "high_estimate": 441307000000,
      "year_ago_sales": 392509000000,
      "sales_growth": 0.05
    }
  ],
  "status": "ok"
}

HTTP route

/revenue_estimate

API credits

20 per symbol

API parameters

Parameter Details
symbol • Required parameter
• Filter by symbol
figi • Parameter is optional
• Filter by financial instrument global identifier (FIGI)
country • Parameter is optional
• Filter by country name or alpha code
exchange • Parameter is optional
• Filter by exchange name or mic code
dp • Number of decimal places for floating values
• Should be in range [0,11] inclusive. Default 5
apikey • Required parameter
• Your API key at the Enterprise plan or above

Response

Key Description
period defines period of estimation, can be current_quarter, next_quarter, current_year, or next_year
number_of_analysts number of analysts that made the estimation
avg_estimate average estimation across analysts
low_estimate lowest estimation given by an analyst
high_estimate highest estimation given by an analyst
year_ago_sales total revenue received a year ago relative to period
sales_growth estimated sales growth of the period in relation to year-ago sales in prc (%)

JSON request example

https://api.twelvedata.com/revenue_estimate?symbol=aapl&apikey=demo

EPS Trend

This API endpoint returns a breakdown of the estimated historical EPS changes at a given period.

HTTP request example

https://api.twelvedata.com/eps_trend?symbol=AAPL&apikey=your_api_key

This request will return JSON with the following structure

{
  "meta": {
    "symbol": "AAPL",
    "name": "Apple Inc",
    "currency": "USD",
    "exchange_timezone": "America/New_York",
    "exchange": "NASDAQ",
    "mic_code": "XNGS",
    "type": "Common Stock"
  },
  "eps_trend": [
    {
      "date": "2022-09-30",
      "period": "current_quarter",
      "current_estimate": 1.26,
      "7_days_ago": 1.26,
      "30_days_ago": 1.31,
      "60_days_ago": 1.32,
      "90_days_ago": 1.33
    },
    {
      "date": "2022-12-31",
      "period": "next_quarter",
      "current_estimate": 2.12,
      "7_days_ago": 2.11,
      "30_days_ago": 2.18,
      "60_days_ago": 2.19,
      "90_days_ago": 2.19
    },
    {
      "date": "2022-09-30",
      "period": "current_year",
      "current_estimate": 6.1,
      "7_days_ago": 6.1,
      "30_days_ago": 6.13,
      "60_days_ago": 6.14,
      "90_days_ago": 6.14
    },
    {
      "date": "2023-09-30",
      "period": "next_year",
      "current_estimate": 6.44,
      "7_days_ago": 6.44,
      "30_days_ago": 6.51,
      "60_days_ago": 6.55,
      "90_days_ago": 6.56
    }
  ],
  "status": "ok"
}

HTTP route

/eps_trend

API credits

20 per symbol

API parameters

Parameter Details
symbol • Required parameter
• Filter by symbol
figi • Parameter is optional
• Filter by financial instrument global identifier (FIGI)
country • Parameter is optional
• Filter by country name or alpha code
exchange • Parameter is optional
• Filter by exchange name or mic code
apikey • Required parameter
• Your API key at the Enterprise plan or above

Response

Key Description
period defines period of estimation, can be current_quarter, next_quarter, current_year, or next_year
current_estimate actual EPS estimation for the period
7_days_ago EPS estimation value 7 days ago
30_days_ago EPS estimation value 30 days ago
60_days_ago EPS estimation value 60 days ago
90_days_ago EPS estimation value 90 days ago

JSON request example

https://api.twelvedata.com/eps_trend?symbol=aapl&apikey=demo

EPS Revisions

This API endpoint returns analysts’ revisions of a company's future quarterly and annual earnings per share (EPS) over the last week and month.

HTTP request example

https://api.twelvedata.com/eps_revisions?symbol=AAPL&apikey=your_api_key

This request will return JSON with the following structure

{
  "meta": {
    "symbol": "AAPL",
    "name": "Apple Inc",
    "currency": "USD",
    "exchange_timezone": "America/New_York",
    "exchange": "NASDAQ",
    "mic_code": "XNGS",
    "type": "Common Stock"
  },
  "eps_revision": [
    {
      "date": "2022-09-30",
      "period": "current_quarter",
      "up_last_week": 1,
      "up_last_month": 5,
      "down_last_week": 0,
      "down_last_month": 0
    },
    {
      "date": "2022-12-31",
      "period": "next_quarter",
      "up_last_week": 1,
      "up_last_month": 5,
      "down_last_week": 0,
      "down_last_month": 0
    },
    {
      "date": "2022-09-30",
      "period": "current_year",
      "up_last_week": 1,
      "up_last_month": 10,
      "down_last_week": 0,
      "down_last_month": 1
    },
    {
      "date": "2023-09-30",
      "period": "next_year",
      "up_last_week": 1,
      "up_last_month": 10,
      "down_last_week": 0,
      "down_last_month": 1
    }
  ],
  "status": "ok"
}

HTTP route

/eps_revisions

API credits

20 per symbol

API parameters

Parameter Details
symbol • Required parameter
• Filter by symbol
figi • Parameter is optional
• Filter by financial instrument global identifier (FIGI)
country • Parameter is optional
• Filter by country name or alpha code
exchange • Parameter is optional
• Filter by exchange name or mic code
apikey • Required parameter
• Your API key at the Enterprise plan or above

Response

Key Description
period defines period of estimation, can be current_quarter, next_quarter, current_year, or next_year
up_last_week number of up revisions over the last 7 days
up_last_month number of up revisions over the last 30 days
down_last_week number of down revisions over the last 7 days
down_last_month number of down revisions over the last 30 days

JSON request example

https://api.twelvedata.com/eps_revisions?symbol=aapl&apikey=demo

Growth Estimates

This API endpoint returns consensus analyst estimates over the company's growth rates for various periods.

HTTP request example

https://api.twelvedata.com/growth_estimates?symbol=AAPL&apikey=your_api_key

This request will return JSON with the following structure

{
  "meta": {
    "symbol": "AAPL",
    "name": "Apple Inc",
    "currency": "USD",
    "exchange_timezone": "America/New_York",
    "exchange": "NASDAQ",
    "mic_code": "XNGS",
    "type": "Common Stock"
  },
  "growth_estimates": {
    "current_quarter": 0.016,
    "next_quarter": 0.01,
    "current_year": 0.087,
    "next_year": 0.055999998,
    "next_5_years_pa": 0.094799995,
    "past_5_years_pa": 0.23867
  },
  "status": "ok"
}

HTTP route

/growth_estimates

API credits

20 per symbol

API parameters

Parameter Details
symbol • Required parameter
• Filter by symbol
figi • Parameter is optional
• Filter by financial instrument global identifier (FIGI)
country • Parameter is optional
• Filter by country name or alpha code
exchange • Parameter is optional
• Filter by exchange name or mic code
apikey • Required parameter
• Your API key at the Enterprise plan or above

Response

Key Description
current_quarter projected growth of the current quarter in prc (%)
next_quarter projected growth of the next quarter in prc (%)
current_year projected growth of the current year in prc (%)
next_year projected growth of the next year in prc (%)
next_5_years_pa projected growth during the next 5 years in prc (%) per annum
past_5_years_pa actual growth over the last 5 years in prc (%) per annum

JSON request example

https://api.twelvedata.com/growth_estimates?symbol=aapl&apikey=demo

RecommendationsHigh Demand

This API endpoint returns the average of all analyst recommendations and classifies them as Strong Buy, Buy, Hold, or Sell. Also, it returns a recommendation score.

HTTP request example

https://api.twelvedata.com/recommendations?symbol=AAPL&apikey=your_api_key

This request will return JSON with the following structure

{
  "meta": {
    "symbol": "AAPL",
    "name": "Apple Inc",
    "currency": "USD",
    "exchange_timezone": "America/New_York",
    "exchange": "NASDAQ",
    "mic_code": "XNGS",
    "type": "Common Stock"
  },
  "trends": {
    "current_month": {
      "strong_buy": 11,
      "buy": 21,
      "hold": 6,
      "sell": 0,
      "strong_sell": 0
    },
    "previous_month": {
      "strong_buy": 14,
      "buy": 24,
      "hold": 8,
      "sell": 0,
      "strong_sell": 0
    },
    "2_months_ago": {
      "strong_buy": 14,
      "buy": 24,
      "hold": 8,
      "sell": 0,
      "strong_sell": 0
    },
    "3_months_ago": {
      "strong_buy": 13,
      "buy": 20,
      "hold": 8,
      "sell": 0,
      "strong_sell": 0
    }
  },
  "rating": 8.2,
  "status": "ok"
}

HTTP route

/recommendations

API credits

100 per symbol

API parameters

Parameter Details
symbol • Required parameter
• Filter by symbol
figi • Parameter is optional
• Filter by financial instrument global identifier (FIGI)
country • Parameter is optional
• Filter by country name or alpha code
exchange • Parameter is optional
• Filter by exchange name or mic code
apikey • Required parameter
• Your API key at the Enterprise plan or above

Response

Key Description
strong_buy number of analysts that give a strong buy recommendation
buy number of analysts that give a buy recommendation
hold number of analysts that give a hold recommendation
sell number of analysts that give a sell recommendation
strong_sell number of analysts that give a strong sell recommendation
rating rating from 0 to 10 represents overall analysts’ recommendation. 0 to 2 - strong sell, 2 to 4 - sell, 4 to 6 - hold, 6 to 8 - buy, 8 to 10 - strong buy.

JSON request example

https://api.twelvedata.com/recommendations?symbol=aapl&apikey=demo

Price TargetHigh Demand

This API endpoint returns the analysts' projection of a security's future price.

HTTP request example

https://api.twelvedata.com/price_target?symbol=AAPL&apikey=your_api_key

This request will return JSON with the following structure

{
  "meta": {
    "symbol": "AAPL",
    "name": "Apple Inc",
    "currency": "USD",
    "exchange_timezone": "America/New_York",
    "exchange": "NASDAQ",
    "mic_code": "XNGS",
    "type": "Common Stock"
  },
  "price_target": {
    "high": 220,
    "median": 185,
    "low": 136,
    "average": 184.01,
    "current": 169.5672
  },
  "status": "ok"
}

HTTP route

/price_target

API credits

75 per symbol

API parameters

Parameter Details
symbol • Required parameter
• Filter by symbol
figi • Parameter is optional
• Filter by financial instrument global identifier (FIGI)
country • Parameter is optional
• Filter by country name or alpha code
exchange • Parameter is optional
• Filter by exchange name or mic code
apikey • Required parameter
• Your API key at the Enterprise plan or above

Response

Key Description
high highest price target given by an analyst
median median price target given across analysts
low lowest price target given by an analyst
average average price target given across analysts
current current price from of a security

JSON request example

https://api.twelvedata.com/price_target?symbol=aapl&apikey=demo

Analyst Ratings - Light

This API endpoint returns a lightweight version of ratings issued by analyst firms. Works for US and international markets.

HTTP request example

https://api.twelvedata.com/analyst_ratings/light?symbol=AAPL&apikey=your_api_key

This request will return JSON with the following structure

{
  "meta": {
    "symbol": "AAPL",
    "name": "Apple Inc",
    "currency": "USD",
    "exchange_timezone": "America/New_York",
    "exchange": "NASDAQ",
    "mic_code": "XNGS",
    "type": "Common Stock"
  },
  "ratings": [
    {
      "date": "2022-08-19",
      "firm": "Keybanc",
      "rating_change": "Maintains",
      "rating_current": "Overweight",
      "rating_prior": "Overweight"
    },
    {
      "date": "2022-08-17",
      "firm": "Credit Suisse",
      "rating_change": "Upgrade",
      "rating_current": "Outperform",
      "rating_prior": "Neutral"
    },
    {
      "date": "2022-08-17",
      "firm": "Wedbush",
      "rating_change": "Maintains",
      "rating_current": "Outperform",
      "rating_prior": "Outperform"
    }
  ],
  "status": "ok"
}

HTTP route

/analyst_ratings/light

API credits

75 per symbol

API parameters

Parameter Details
symbol • Required parameter
• Filter by symbol
figi • Parameter is optional
• Filter by financial instrument global identifier (FIGI)
country • Parameter is optional
• Filter by country name or alpha code
exchange • Parameter is optional
• Filter by exchange name or mic code
rating_change • Parameter is optional
• Filter by rating change action: Maintains, Upgrade, Downgrade, Initiates or Reiterates
outputsize • Parameter is optional
• Number of records in response; default 30
apikey • Required parameter
• Your API key at the Enterprise plan or above

Response

Key Description
date date when the rating was released
firm firm that issued the ranking
rating_change defines the action of the firm to ranking, could be Maintains, Upgrade, Downgrade, Initiates or Reiterates
rating_current current firm's ranking of the instrument
rating_prior prior firm's ranking of the instrument

JSON request example

https://api.twelvedata.com/analyst_ratings/light?symbol=aapl&apikey=demo

https://api.twelvedata.com/analyst_ratings/light?symbol=infy&country=india&apikey=demo

Analyst Ratings - US Equities

This API endpoint returns complete information on ratings issued by analyst firms. Works only for US equities.

HTTP request example

https://api.twelvedata.com/analyst_ratings/us_equities?symbol=AAPL&apikey=your_api_key

This request will return JSON with the following structure

{
  "meta": {
    "symbol": "AAPL",
    "name": "Apple Inc",
    "currency": "USD",
    "exchange_timezone": "America/New_York",
    "exchange": "NASDAQ",
    "mic_code": "XNGS",
    "type": "Common Stock"
  },
  "ratings": [
    {
      "date": "2022-08-19",
      "firm": "Keybanc",
      "analyst_name": "Brandon Nispel",
      "rating_change": "Maintains",
      "rating_current": "Overweight",
      "rating_prior": "Overweight",
      "time": "08:29:48",
      "action_price_target": "Raises",
      "price_target_current": 185,
      "price_target_prior": 177
    },
    {
      "date": "2022-08-17",
      "firm": "Credit Suisse",
      "analyst_name": "Shannon Cross",
      "rating_change": "Upgrade",
      "rating_current": "Outperform",
      "rating_prior": "Neutral",
      "time": "08:14:09",
      "action_price_target": "Announces",
      "price_target_current": 201,
      "price_target_prior": null
    },
    {
      "date": "2022-08-17",
      "firm": "Wedbush",
      "analyst_name": "Daniel Ives",
      "rating_change": "Maintains",
      "rating_current": "Outperform",
      "rating_prior": "Outperform",
      "time": "10:22:55",
      "action_price_target": "Raises",
      "price_target_current": 220,
      "price_target_prior": 200
    }
  ],
  "status": "ok"
}

HTTP route

/analyst_ratings/us_equities

API credits

200 per symbol

API parameters

Parameter Details
symbol • Required parameter
• Filter by symbol
figi • Parameter is optional
• Filter by financial instrument global identifier (FIGI)
exchange • Parameter is optional
• Filter by exchange name or mic code
rating_change • Parameter is optional
• Filter by rating change action: Maintains, Upgrade, Downgrade, Initiates, Reiterates, Assumes, or Reinstates
outputsize • Parameter is optional
• Number of records in response; default 30
apikey • Required parameter
• Your API key at the Enterprise plan or above

Response

Key Description
date date when the rating was released
firm firm that issued the ranking
analyst_name name of an analyst
rating_change defines the action of the firm to ranking, could be Maintains, Upgrade, Downgrade, Initiates, Reiterates, Assumes, or Reinstates
rating_current current firm's ranking of the instrument
rating_prior prior firm's ranking of the instrument
time time when the rating was released or updated
action_price_target action that firm took towards target price
price_target_current current firm's price target for the instrument
price_target_prior prior firm's price target for the instrument

JSON request example

https://api.twelvedata.com/analyst_ratings/us_equities?symbol=aapl&apikey=demo

WebSocket

Connect & Authorize

# Pass API key as connection parameter
wss://ws.twelvedata.com/v1/{$route}?apikey=your_api_key

# Or pass API key separately in header
wss://ws.twelvedata.com/v1/{$route}
X-TD-APIKEY: your_api_key

WebSocket will automatically send the data to you once a new piece of data is available on the exchange. In the beginning, you need to establish a connection between the server and the client. Then all data is controlled by sending event messages to the server. WebSocket is opposed to the API, where the data has to be explicitly requested from the server.

You may use the API key to connect to the Twelve Data Distributed WebSocket System (TDDWS). This system will manage all your requests to all available instruments across different exchanges. You can establish up to 3 connections (typically used in production, stage, and local environments) across the whole lifespan of the application; if you open more, the previous connections will be closed.

You may subscribe to all symbols available at Twelve Data; meanwhile, the format remains the same as the API unless there are constraints in the endpoint. Moreover, you may combine symbols across different types, and TDDWS will manage the routing. There are some limitations, though:

Please note that full access to WebSocket is available for the users on the Pro plan and above. However, testing can be done on the Basic and Grow tier plans with only one connection and up to 8 simultaneous symbols subscriptions among the permitted list.

Resources
You can try out streaming via WebSocket Playground located in the personal dashboard. On Basic and Grow plans, only trial symbols can be used; on Pro plan and above, any instrument can be streamed.

Trial symbols
WebSocket FAQ
How to stream data tutorial

Real-time priceUseful

This method allows you to get real-time price streaming from the exchange. Equities also have day volume information.

Subscribe to stream

# You may subscribe to multiple symbols by calling subscribe action. 
# Additionally, you can pass the exchange name after the colon(:).
{
  "action": "subscribe", 
  "params": {
    "symbols": "AAPL,RY,RY:TSX,EUR/USD,BTC/USD"
  }
}
# Alternatively, if you need to get data from the ambiguos symbol you may use the extended format
{ "action": "subscribe", 
  "params": {
    "symbols": [{
        "symbol": "AAPL",
        "exchange": "NASDAQ"
      }, {
        "symbol": "RY", 
        "mic_code": "XNYS"
      }, {
        "symbo