Twelve data

Learn how to use Twelve data with Composio

Overview

SLUG: TWELVE_DATA

Description

Twelve Data provides a comprehensive financial data API offering real-time and historical market data for stocks, forex, cryptocurrencies, ETFs, and indices.

Authentication Details

generic_api_key
stringRequired

Connecting to Twelve data

Create an auth config

Use the dashboard to create an auth config for the Twelve data toolkit. This allows you to connect multiple Twelve data accounts to Composio for agents to use.

1

Select App

Navigate to [Twelve data](https://platform.composio.dev?next_page=/marketplace/Twelve data).

2

Configure Auth Config Settings

Select among the supported auth schemes of and configure them here.

3

Create and Get auth config ID

Click “Create Twelve data Auth Config”. After creation, copy the displayed ID starting with ac_. This is your auth config ID. This is not a sensitive ID — you can save it in environment variables or a database. This ID will be used to create connections to the toolkit for a given user.

Connect Your Account

Using API Key

1from composio import Composio
2
3# Replace these with your actual values
4twelve_data_auth_config_id = "ac_YOUR_TWELVE_DATA_CONFIG_ID" # Auth config ID created above
5user_id = "0000-0000-0000" # UUID from database/app
6
7composio = Composio()
8
9def authenticate_toolkit(user_id: str, auth_config_id: str):
10 # Replace this with a method to retrieve an API key from the user.
11 # Or supply your own.
12 user_api_key = input("[!] Enter API key")
13
14 connection_request = composio.connected_accounts.initiate(
15 user_id=user_id,
16 auth_config_id=auth_config_id,
17 config={"auth_scheme": "API_KEY", "val": {"generic_api_key": user_api_key}}
18 )
19
20 # API Key authentication is immediate - no redirect needed
21 print(f"Successfully connected Twelve data for user {user_id}")
22 print(f"Connection status: {connection_request.status}")
23
24 return connection_request.id
25
26
27connection_id = authenticate_toolkit(user_id, twelve_data_auth_config_id)
28
29# You can verify the connection using:
30connected_account = composio.connected_accounts.get(connection_id)
31print(f"Connected account: {connected_account}")

Tools

Executing tools

To prototype you can execute some tools to see the responses and working on the [Twelve data toolkit’s playground](https://app.composio.dev/app/Twelve data)

Python
1from composio import Composio
2from openai import OpenAI
3import json
4
5openai = OpenAI()
6composio = Composio()
7
8# User ID must be a valid UUID format
9user_id = "0000-0000-0000" # Replace with actual user UUID from your database
10
11tools = composio.tools.get(user_id=user_id, toolkits=["TWELVE_DATA"])
12
13print("[!] Tools:")
14print(json.dumps(tools))
15
16def invoke_llm(task = "What can you do?"):
17 completion = openai.chat.completions.create(
18 model="gpt-4o",
19 messages=[
20 {
21 "role": "user",
22 "content": task, # Your task here!
23 },
24 ],
25 tools=tools,
26 )
27
28 # Handle Result from tool call
29 result = composio.provider.handle_tool_calls(user_id=user_id, response=completion)
30 print(f"[!] Completion: {completion}")
31 print(f"[!] Tool call result: {result}")
32
33invoke_llm()

Tool List

Tool Name: Cash Flow

Description

Tool to get company cash flow statement. Use when you need operating, investing, and financing cash flow details after selecting a company.

Action Parameters

country
string
cusip
string
end_date
string
exchange
string
figi
string
isin
string
mic_code
string
outputsize
integerDefaults to 6
period
stringDefaults to annual
start_date
string
symbol
string

Action Response

data
objectRequired
error
string
successful
booleanRequired

Tool Name: Consolidated Cash Flow

Description

Tool to get raw consolidated cash flow statements. Use when you need detailed cash flow data for a company.

Action Parameters

country
string
cusip
string
end_date
string
exchange
string
figi
string
isin
string
mic_code
string
outputsize
integerDefaults to 6
period
stringDefaults to annual
start_date
string
symbol
string

Action Response

data
objectRequired
error
string
successful
booleanRequired

Tool Name: List Commodities

Description

Tool to retrieve a list of supported commodities. Use when you need all available commodities after obtaining a valid API key.

Action Parameters

Action Response

data
objectRequired
error
string
successful
booleanRequired

Tool Name: Correlation Coefficient

Description

Tool to fetch Pearson correlation coefficient between two series over a period. Use after selecting identifiers and interval.

Action Parameters

adjust
stringDefaults to splits
country
string
cusip
string
end_date
string
exchange
string
figi
string
interval
stringRequired
isin
string
mic_code
string
previous_close
boolean
series_type_1
stringDefaults to open
series_type_2
stringDefaults to close
start_date
string
symbol
string
time_period
integerDefaults to 9
timezone
string
type
string

Action Response

data
objectRequired
error
string
successful
booleanRequired

Tool Name: List Countries

Description

Tool to retrieve a list of countries with ISO codes, names, capitals, and currencies. Use when you need country metadata after obtaining a valid API key.

Action Parameters

Action Response

data
objectRequired
error
string
successful
booleanRequired

Tool Name: Cross Listings

Description

Tool to retrieve cross-listed symbols for a security across multiple exchanges. Use when you need to list all market listings of a given instrument.

Action Parameters

country
string
exchange
string
mic_code
string
symbol
stringRequired

Action Response

data
objectRequired
error
string
successful
booleanRequired

Tool Name: List Cryptocurrencies

Description

Tool to list all supported cryptocurrencies. Use when you need the complete set of crypto symbols. Use after obtaining a valid API key.

Action Parameters

apikey
stringRequired
outputsize
integer
symbol
string

Action Response

data
arrayRequired
error
string
message
string
status
stringRequired
successful
booleanRequired

Tool Name: List Cryptocurrency Exchanges

Description

Tool to list supported cryptocurrency exchanges. Use when you need a list of available crypto trading platforms.

Action Parameters

delimiter
stringDefaults to ;
format
stringDefaults to JSON

Action Response

data
arrayRequired
error
string
message
string
status
stringRequired
successful
booleanRequired

Tool Name: Currency Conversion

Description

Tool to convert an amount from one currency to another. Use after confirming currency codes to retrieve real-time conversion.

Action Parameters

amount
numberRequired
from_currency
stringRequired
to_currency
stringRequired

Action Response

data
objectRequired
error
string
successful
booleanRequired

Tool Name: Dividends

Description

Tool to retrieve dividend payout history for a specified symbol. Use when you need historical dividends over multiple years.

Action Parameters

country
string
delimiter
stringDefaults to ,
end_date
string
exchange
string
format
stringDefaults to JSON
outputsize
integerDefaults to 30
start_date
string
symbol
stringRequired
timezone
string

Action Response

data
objectRequired
error
string
successful
booleanRequired

Tool Name: Earnings

Description

Tool to retrieve earnings data including EPS estimates and actuals. Use when you need detailed earnings history for a selected stock symbol.

Action Parameters

format
string
source
string
symbol
stringRequired
type
string

Action Response

data
objectRequired
error
string
successful
booleanRequired

Tool Name: EPS Revisions

Description

Tool to provide analysts’ revisions of a company’s future EPS over the last week and month. Use after confirming the stock symbol.

Action Parameters

dp
integer
exchange
string
format
stringDefaults to json
symbol
stringRequired

Action Response

data
objectRequired
error
string
successful
booleanRequired

Tool Name: EPS Trend

Description

Tool to retrieve historical EPS trends for a specified company. Use after selecting a stock symbol to view estimated vs actual EPS and surprise indicators. Returns a breakdown of EPS actuals, estimates, differences, and surprise percentages.

Action Parameters

format
stringDefaults to JSON
interval
stringDefaults to 1day
outputsize
integerDefaults to 30
symbol
stringRequired
timezone
string

Action Response

data
objectRequired
error
string
successful
booleanRequired

Tool Name: ETFS Directory

Description

Tool to fetch a daily updated list of exchange-traded funds sorted by total assets. Use when you need a directory of ETFs by exchange or country.

Action Parameters

country
string
exchange
string
format
stringDefaults to JSON

Action Response

data
arrayRequired
error
string
message
string
status
stringRequired
successful
booleanRequired

Tool Name: ETFS Family

Description

Tool to fetch a comprehensive list of ETFs by family. Use when you need to list ETFs managed by a specific investment company.

Action Parameters

family
string

Action Response

data
arrayRequired
error
string
successful
booleanRequired

Tool Name: Get ETF Types

Description

Tool to retrieve ETF categories by market, including types like 'Equity Precious Metals'. Use after confirming API key is set; no parameters are needed.

Action Parameters

Action Response

data
arrayRequired
error
string
successful
booleanRequired

Tool Name: ETF World

Description

Tool to fetch comprehensive ETF analytics (summary, performance, risk, composition). Use when you need a detailed overview of an ETF's metrics and holdings.

Action Parameters

country
string
cusip
string
dp
integerDefaults to 5
figi
string
isin
string
symbol
string

Action Response

data
objectRequired
error
string
successful
booleanRequired

Tool Name: ETF World Composition

Description

Tool to fetch global ETF composition details including sector, country, asset allocations, top holdings, and bond metrics. Use after selecting an ETF to analyze its composition.

Action Parameters

country
string
cusip
string
dp
integerDefaults to 5
figi
string
isin
string
symbol
string

Action Response

data
objectRequired
error
string
successful
booleanRequired

Tool Name: ETF World Risk

Description

Tool to get global ETF risk metrics. Use when you need to analyze volatility and valuation ratios for an ETF.

Action Parameters

country
string
cusip
string
dp
integerDefaults to 5
figi
string
isin
string
symbol
string

Action Response

data
objectRequired
error
string
successful
booleanRequired

Tool Name: List supported exchanges

Description

Tool to retrieve a list of supported exchanges. Use when you need all available stock and forex exchanges.

Action Parameters

country
string
format
stringDefaults to json

Action Response

data
objectRequired
error
string
successful
booleanRequired

Tool Name: List supported forex pairs

Description

Tool to retrieve a list of all supported forex currency pairs. Use when exploring available forex pairs before making other forex data requests.

Action Parameters

Action Response

data
objectRequired
error
string
successful
booleanRequired

Tool Name: Get Analyst Rating

Description

Tool to retrieve the analyst rating summary for a given symbol. Use when you need rating counts and a derived average score after selecting a symbol.

Action Parameters

symbol
stringRequired

Action Response

data
objectRequired
error
string
successful
booleanRequired

Tool Name: Get API Usage

Description

Tool to retrieve your current plan and remaining API credits. Use when monitoring your subscription usage in real-time.

Action Parameters

Action Response

data
objectRequired
error
string
successful
booleanRequired

Tool Name: Balance Sheet

Description

Tool to retrieve a company's balance sheet (assets, liabilities, equity). Use when you need annual or quarterly financial position data for a given symbol or identifier.

Action Parameters

country
string
cusip
string
end_date
string
exchange
string
figi
string
isin
string
mic_code
string
outputsize
integerDefaults to 6
period
stringDefaults to annual
start_date
string
symbol
string

Action Response

data
objectRequired
error
string
successful
booleanRequired

Tool Name: Balance Sheet Consolidated

Description

Tool to get raw consolidated balance sheet data (assets, liabilities, equity) for a company. Use when you need detailed historical balance sheet by period.

Action Parameters

country
string
cusip
string
end_date
string
exchange
string
figi
string
isin
string
mic_code
string
outputsize
integer
period
string
start_date
string
symbol
string

Action Response

data
objectRequired
error
string
successful
booleanRequired

Tool Name: Get Earliest Timestamp

Description

Tool to return the first available timestamp for a symbol and interval. Use after selecting instrument identifiers and interval to discover the earliest data point.

Action Parameters

cusip
string
exchange
string
figi
string
interval
stringRequired
isin
string
mic_code
string
symbol
string
timezone
string

Action Response

data
objectRequired
error
string
successful
booleanRequired

Tool Name: Global ETF Performance

Description

Tool to get global ETF performance metrics (trailing and annual returns). Use when you need detailed performance analytics for an ETF.

Action Parameters

country
string
cusip
string
dp
integerDefaults to 5
figi
string
isin
string
symbol
string

Action Response

data
objectRequired
error
string
successful
booleanRequired

Tool Name: Get exchange schedule

Description

Tool to get trading sessions and hours for exchanges. Use when you need pre-market, main, and post-market hours for a given exchange and date.

Action Parameters

country
string
date
string
mic_code
string
mic_name
string

Action Response

data
arrayRequired
error
string
successful
booleanRequired

Tool Name: Income Statement

Description

Tool to retrieve a company's income statement data (annual or quarterly). Use when you need detailed income metrics for a given symbol or identifier.

Action Parameters

country
string
cusip
string
end_date
string
exchange
string
figi
string
isin
string
mic_code
string
outputsize
integerDefaults to 6
period
stringDefaults to annual
start_date
string
symbol
string

Action Response

data
objectRequired
error
string
successful
booleanRequired

Tool Name: Insider Transactions

Description

Tool to retrieve insider trading transactions for a specified company. Use when you need to fetch details of officer/trader transactions including type, date, and amount.

Action Parameters

end_date
string
exchange
string
format
stringDefaults to JSON
outputsize
integerDefaults to 30
start_date
string
symbol
stringRequired
timezone
string

Action Response

data
objectRequired
error
string
successful
booleanRequired

Tool Name: Key Executives

Description

Tool to retrieve company leadership data such as executive names, titles, and compensation. Use when you need detailed management info by symbol or other identifier. Requires Ultra plan (1000 credits per request).

Action Parameters

country
string
cusip
string
exchange
string
figi
string
isin
string
mic_code
string
symbol
string

Action Response

data
objectRequired
error
string
successful
booleanRequired

Tool Name: Get Last Change

Description

Tool to retrieve the latest update timestamps for a fundamentals dataset. Use when checking recent changes (e.g., dividends, splits).

Action Parameters

country
string
endpoint
stringRequired
exchange
string
mic_code
string
outputsize
integerDefaults to 30
page
integerDefaults to 1
start_date
string
symbol
string

Action Response

data
arrayRequired
error
string
pagination
objectRequired
successful
booleanRequired

Tool Name: Market Movers

Description

Tool to retrieve a snapshot of top gainers or losers for a specified market. Use when you need to quickly see market movers after choosing a market type.

Action Parameters

country
string
direction
stringDefaults to gainers
dp
integerDefaults to 5
market
stringRequired
outputsize
integerDefaults to 30
price_greater_than
number

Action Response

data
objectRequired
error
string
successful
booleanRequired

Tool Name: Get Market State

Description

Tool to report current open/closed status for exchanges. Use when you need real-time market status updates after selecting exchanges.

Action Parameters

code
string
country
string
exchange
string

Action Response

data
objectRequired
error
string
successful
booleanRequired

Tool Name: Global Mutual Fund Performance

Description

Tool to get global mutual fund performance metrics (trailing, annual, quarterly, load-adjusted returns). Use when you need detailed performance analytics for a mutual fund.

Action Parameters

country
string
cusip
string
dp
integerDefaults to 5
figi
string
isin
string
symbol
string

Action Response

data
objectRequired
error
string
successful
booleanRequired

Tool Name: Mutual Funds World Risk

Description

Tool to fetch global mutual fund risk metrics. Use when you need detailed risk analytics (standard deviation, beta, Sharpe ratio) for a specific mutual fund identifier.

Action Parameters

country
string
cusip
string
dp
integerDefaults to 5
figi
string
isin
string
symbol
string

Action Response

data
objectRequired
error
string
successful
booleanRequired

Tool Name: Global Mutual Fund Summary

Description

Tool to retrieve a global mutual fund summary snapshot. Use when you need a high-level overview of a fund’s key identifiers and attributes.

Action Parameters

country
string
cusip
string
dp
integerDefaults to 5
figi
string
isin
string
symbol
string

Action Response

data
objectRequired
error
string
successful
booleanRequired

Tool Name: Global Mutual Fund Sustainability

Description

Tool to get global mutual fund sustainability and ESG metrics. Use when you need fund ESG scores and pillar breakdowns.

Action Parameters

country
string
cusip
string
dp
integerDefaults to 5
figi
string
isin
string
symbol
string

Action Response

data
objectRequired
error
string
successful
booleanRequired

Tool Name: Price Target

Description

Tool to fetch analysts' price target dataset for equities. Use when you need the latest and historical price forecasts for a symbol.

Action Parameters

symbol
stringRequired

Action Response

data
objectRequired
error
string
successful
booleanRequired

Tool Name: Get Profile

Description

Tool to retrieve company profile. Use when you need company details like industry, sector, and identifiers after selecting a symbol.

Action Parameters

country
string
cusip
string
exchange
string
figi
string
isin
string
mic_code
string
symbol
string

Action Response

data
objectRequired
error
string
successful
booleanRequired

Tool Name: Recommendations

Description

Tool to retrieve aggregated analyst recommendations for a company. Use when you need buy/hold/sell consensus ratings.

Action Parameters

symbol
stringRequired

Action Response

data
objectRequired
error
string
successful
booleanRequired

Tool Name: Stock Splits

Description

Tool to retrieve historical stock split events. Use when you need to fetch split history for a particular instrument.

Action Parameters

country
string
cusip
string
end_date
string
exchange
string
figi
string
isin
string
mic_code
string
range
stringDefaults to last
start_date
string
symbol
string

Action Response

data
objectRequired
error
string
successful
booleanRequired

Tool Name: Splits Calendar

Description

Tool to retrieve a calendar of stock split events. Use when you need to fetch split events for instruments over a date range.

Action Parameters

country
string
cusip
string
end_date
string
exchange
string
figi
string
isin
string
mic_code
string
outputsize
integer
page
integerDefaults to 1
start_date
string
symbol
string

Action Response

data
objectRequired
error
string
successful
booleanRequired

Tool Name: Get Statistics

Description

Tool to retrieve key company statistics including valuation and financial overview. Use when you need a company financial snapshot after selecting an instrument.

Action Parameters

country
string
cusip
string
exchange
string
figi
string
isin
string
mic_code
string
symbol
string

Action Response

data
objectRequired
error
string
successful
booleanRequired

Tool Name: List market indices

Description

Tool to retrieve a list of market indices. Use when you need to fetch available indices filtered by country.

Action Parameters

country
string
format
stringDefaults to json

Action Response

data
objectRequired
error
string
successful
booleanRequired

Tool Name: Institutional Holders

Description

Tool to retrieve institutional holders positions for a company. Use when you need summary ownership metrics and top institutions.

Action Parameters

country
string
cusip
string
exchange
string
figi
string
isin
string
mic_code
string
symbol
string

Action Response

data
objectRequired
error
string
successful
booleanRequired

Tool Name: Mutual Funds Family

Description

Tool to list all available mutual fund families. Use when you need a comprehensive list of mutual fund families managed by investment companies after obtaining a valid API key.

Action Parameters

Action Response

data
arrayRequired
error
string
message
string
status
stringRequired
successful
booleanRequired

Tool Name: Mutual Funds List

Description

Tool to retrieve a daily updated list of mutual funds sorted by total assets. Use when you need to enumerate available mutual funds for analysis.

Action Parameters

country
string
exchange
string
format
stringDefaults to json
type
string

Action Response

data
objectRequired
error
string
successful
booleanRequired

Tool Name: Mutual Funds World Composition

Description

Tool to fetch global mutual fund portfolio composition including sectors, asset allocation, top holdings, and bond metrics. Use after selecting a mutual fund to analyze its composition.

Action Parameters

country
string
cusip
string
dp
integerDefaults to 5
figi
string
isin
string
symbol
string

Action Response

data
objectRequired
error
string
successful
booleanRequired

Tool Name: Options Chain

Description

Tool to retrieve the options chain for a given symbol and optional expiration date. Use when you need detailed option contract data and Greeks. Omitting date returns all expirations.

Action Parameters

date
string
includeGreeks
boolean
symbol
stringRequired

Action Response

data
objectRequired
error
string
successful
booleanRequired

Tool Name: Options Expiration

Description

Tool to retrieve available option expiration dates. Use when exploring available expiration dates for a given options symbol.

Action Parameters

exchange
string
symbol
stringRequired

Action Response

data
objectRequired
error
string
successful
booleanRequired

Tool Name: Quote

Description

Tool to retrieve the latest market data for a specified symbol. Use when you need a quick real-time quote after selecting a symbol.

Action Parameters

format
string
source
string
symbol
stringRequired

Action Response

data
objectRequired
error
string
successful
booleanRequired

Tool Name: List Stocks

Description

Tool to retrieve a list of stocks. Use when you need to fetch securities with optional filtering by exchange, country, type, or symbol.

Action Parameters

country
string
exchange
string
format
stringDefaults to json
symbol
string
type
string

Action Response

data
objectRequired
error
string
successful
booleanRequired

Tool Name: Technical Indicators

Description

Tool to fetch time-series data for a specific technical indicator. Use when you have a symbol, interval, and indicator name.

Action Parameters

indicator
stringRequired
indicator_params
object
interval
stringRequired
outputsize
integer
symbol
stringRequired

Action Response

data
objectRequired
error
string
successful
booleanRequired

Tool Name: Time Series

Description

Tool to retrieve historical and real-time time series data for a specified symbol. Use when you need to fetch price data over a time range after selecting a symbol.

Action Parameters

end_date
string
format
stringDefaults to JSON
interval
stringRequired
outputsize
integerDefaults to 30
start_date
string
symbol
stringRequired
timezone
string

Action Response

data
objectRequired
error
string
successful
booleanRequired