Introduction
Everything you need before your first request. Get an API key and make a call in five steps, see how authentication, parameters, and responses work, look up error codes, and pick an official SDK, AI integration, or spreadsheet add-on.
Quickstart
To get started, you'll need to sign up for an API key. Once you have your API key, you can start making requests to the API.
Step 1: Create Twelve Data account
Sign up on the Twelve Data website to create your account here. This gives you access to the API dashboard and your API key.
Step 2: Get your API key
After signing in, navigate to your dashboard to find your unique API key. This key is required to authenticate all API and WebSocket requests.
Step 3: Make your first request
Try a simple API call with cURL to fetch the latest price for Apple (AAPL):
curl "https://api.twelvedata.com/price?symbol=AAPL&apikey=your_api_key"
Step 4: Make a request from Python or Javascript
Use our client libraries or standard HTTP clients to make API calls programmatically. Here’s an example in Python and Node.js:
Python (using official Twelve Data SDK):
from twelvedata import TDClient
# Initialize client with your API key
td = TDClient(apikey="your_api_key")
# Get latest price for Apple
price = td.price(symbol="AAPL").as_json()
print(price)
JavaScript (Node.js):
import { MarketDataApi, CreateConfig } from "@twelvedata/twelvedata-node";
const config = CreateConfig('your_api_key');
const api = new MarketDataApi(config);
async function main() {
const response = await api.getPrice({
symbol: "AAPL",
});
console.log(response.data);
}
main().catch(console.error);
Step 5: Perform correlation analysis between Tesla and Microsoft prices
Fetch historical price data for Tesla (TSLA) and Microsoft (MSFT) and calculate the correlation of their closing prices:
from twelvedata import TDClient
import pandas as pd
# Initialize client with your API key
td = TDClient(apikey="your_api_key")
# Fetch historical price data for Tesla
tsla_ts = td.time_series(
symbol="TSLA",
interval="1day",
outputsize=100
).as_pandas()
# Fetch historical price data for Microsoft
msft_ts = td.time_series(
symbol="MSFT",
interval="1day",
outputsize=100
).as_pandas()
# Align data on datetime index
combined = pd.concat(
[tsla_ts['close'].astype(float), msft_ts['close'].astype(float)],
axis=1,
keys=["TSLA", "MSFT"]
).dropna()
# Calculate correlation
correlation = combined["TSLA"].corr(combined["MSFT"])
print(f"Correlation of closing prices between TSLA and MSFT: {correlation:.2f}")
Authentication
Authenticate your requests using one of these methods:
Query parameter method
GET https://api.twelvedata.com/endpoint?symbol=AAPL&apikey=your_api_key
HTTP header method (recommended)
Authorization: apikey your_api_key
API key useful information
- Demo API key (
apikey=demo) available for demo requests - Personal API key required for full access
- Premium endpoints and data require higher-tier plans (testable with trial symbols)
API endpoints
| Service | Base URL |
|---|---|
| REST API | https://api.twelvedata.com |
| WebSocket | wss://ws.twelvedata.com |
API credits and limits
API credits are counted per minute on every plan. Only the Basic plan has a daily cap of 800 API credits, which resets at midnight UTC. Paid plans have no daily limit.
To check your current usage and your plan's limits, call the /api_usage endpoint.
Parameter guidelines
- Separator: Use
&to separate multiple parameters - Case sensitivity: Parameter names are case-insensitive (
symbol=AAPL=symbol=aapl) - Multiple values: Separate with commas where supported
Response handling
Default format
All responses return JSON format by default unless otherwise specified.
Null values
Important: Some response fields may contain null values when data is unavailable for specific metrics. This is expected behavior, not an error.
Best Practices:
- Always implement
nullvalue handling in your application - Use defensive programming techniques for data processing
- Consider fallback values or error handling for critical metrics
Error handling
Structure your code to gracefully handle:
- Network timeouts
- Rate limiting responses
- Invalid parameter errors
- Data unavailability periods
Best practices
- Rate limits: Your plan limits API credits per minute. Only the Basic plan also has a daily cap of 800 API credits. Check your usage with the
/api_usageendpoint. - Error handling: Implement retry logic for transient errors (e.g.,
429 Too Many Requests). - Caching: Cache responses for frequently accessed data to reduce API calls and improve performance.
- Secure storage: Store your API key securely and never expose it in client-side code or public repositories.
Errors
Twelve Data API employs a standardized error response format, delivering a JSON object with code, message, and status keys for clear and consistent error communication.
Codes
Below is a table of possible error codes, their HTTP status, meanings, and resolution steps:
| Code | status | Meaning | Resolution |
|---|---|---|---|
| 400 | Bad Request | Invalid or incorrect parameter(s) provided. | Check the message in the response for details. Refer to the API Documentation to correct the input. |
| 401 | Unauthorized | Invalid or incorrect API key. | Verify your API key is correct. Sign up for a key here. |
| 403 | Forbidden | API key lacks permissions for the requested resource (upgrade required). | Upgrade your plan here. |
| 404 | Not Found | Requested data could not be found. | Adjust parameters to be less strict as they may be too restrictive. |
| 414 | Parameter Too Long | Input parameter array exceeds the allowed length. | Follow the message guidance to adjust the parameter length. |
| 429 | Too Many Requests | API request limit reached for your key. | Wait briefly or upgrade your plan here. |
| 500 | Internal Server Error | Server-side issue occurred; retry later. | Contact support here for assistance. |
Example error response
Consider the following invalid request:
https://api.twelvedata.com/time_series?symbol=AAPL&interval=0.99min&apikey=your_api_key
Due to the incorrect interval value, the API returns:
{
"code": 400,
"message": "Invalid **interval** provided: 0.99min. Supported intervals: 1min, 5min, 15min, 30min, 45min, 1h, 2h, 4h, 8h, 1day, 1week, 1month",
"status": "error"
}
Refer to the API Documentation for valid parameter values to resolve such errors.
Libraries
Twelve Data provides a growing ecosystem of libraries and integrations to help you build faster and smarter in your preferred environment. Official libraries are actively maintained by the Twelve Data team, while selected community-built libraries offer additional flexibility.
A full list is available on our GitHub profile.
Official SDKs
- Python: twelvedata-python
- Node.js: twelvedata-node
- Go: twelvedata-go
- Java: twelvedata-java
- R: twelvedata-r-sdk
- CLI: twelvedata-cli
AI integrations
- Twelve Data MCP Server: Repository — Model Context Protocol (MCP) server that provides seamless integration with AI assistants and language models, enabling direct access to Twelve Data's financial market data within conversational interfaces and AI workflows.
- Twelve Data integration for OpenClaw: Clawhub skill — Integration for the OpenClaw platform, allowing users to leverage Twelve Data's API within their OpenClaw applications.
- Twelve Data NEAR Agent: NEAR Agent — Access Twelve Data's API directly from NEAR's AI agent platform, enabling users to retrieve financial data and insights within their NEAR AI agent workflows.
Spreadsheet add-ons
- Excel: Excel Add-in
- Google Sheets: Google Sheets Add-on
Community libraries
The community has developed libraries in several popular languages. You can explore more community libraries on GitHub.
- C#: TwelveDataSharp
- JavaScript: twelvedata
- PHP: twelvedata
- Go: twelvedata
- TypeScript: twelve-data-wrapper
Other Twelve Data repositories
- searchindex (Go): Repository — In-memory search index by strings
- ws-tools (Python): Repository — Utility tools for WebSocket stream handling
API specification
- OpenAPI / Swagger: Access the complete API specification in OpenAPI format. You can use this file to automatically generate client libraries in your preferred programming language, explore the API interactively via Swagger tools, or integrate Twelve Data seamlessly into your AI and LLM workflows.