Skip to main content
Credits

Credits allocation for API & WebSocket, choosing the right plan, and pricing credo

Team avatar
Written by Team
Updated over a week ago

Credits are the core metric used to access data on our platform. They can be of two types API credits and WebSocket credits.

API

Each API endpoint has a specific data weight that indicates how many credits you will consume. Our versatile credit system allows you to access Twelve Data in the most efficient and timely manner. Each API endpoint has a specific data weight that indicates how many credits you will consume. API credits quota will be reset each minute, and there are no hidden extra data weights unless explicitly stated in the corresponding documentation section.

For instance, if you access /time_series data for AAPL, MSFT, and TSLA - you would consume a total of (1 credit) * (3 symbols) = 3 credits. If you want to retrieve /income_statement for the above three stocks, you will consume (100 credits) * (3 symbols) = 300 credits.

WebSocket

WebSocket shares the same idea about weights as the API, however, in a slightly different manner. Each WebSocket method has its subscription weight, consumed when subscribing to the symbols data stream.

For example, we take /quotes/price endpoint, which returns real-time tick price. It has a data weight of 1 WebSocket credit per successfully subscribed symbol. By subscribing to the AAPL,INFY,TRP,QQQ,IXIC,EUR/USD,USD/JPY,BTC/USD,ETH/BTC - only 9 WS credits are consumed.

Which plan is right for me?

Firstly, decide whether your application will require API, WebSocket, or both. Secondly, visit documentation and determine the necessary endpoints.

Specific endpoints or features are only available starting from the designed plan. For instance, /profile data with the Grow plan, /balance_sheet with the Pro, and /institutional_holders with the Enterprise. Based on that - choose the plan that would serve as the least possible for your case.

API consumption could be calculated with the following formula:

data weight * number of symbols = credits used per endpoint per minute

Apply the above formula for all endpoints you plan to use and sum the total number of credits. Using the above-written formula will estimate the maximum amount of credits that API might consume.

Running out of credits

API

When you run out of API credits, you will receive a 429 error code with the message that you have reached the API credits limit. At the beginning of each new minute, you'll have a complete quota of API credits. For instance, if you're on the Pro 610 plan and have used 555 API credits at 16:59:58, at 17:00:00, you will have your 610 API credits per minute quota restored.

The same logic applies to the daily limits with the Basic plan, but instead, at 00:00:00 midnight UTC quota is set back to 800. Paid plans do not have any daily limits.

WebSocket

When you run out of WebSocket credits, you will no longer be able to subscribe to new events until you reset all of the subscriptions or partially unsubscribe from them. There are two possible statuses for that: warning and failed. The warning is received when you were partially able to subscribe to some of the symbols with the remaining limit, whereas others have failed due to exceeding it. Failed is returned when not a single symbol ticker was successfully subscribed.

Last but not least, you might try to open more connections than is possible - by default, the limit is 3. In this case, if you intend to open the 4th one - the 1st will be closed, if you open the 4th and 5th - then the 1st and 2nd would be closed.
โ€‹

Best practices

  • Each API request returns api-credits-used and api-credits-left in response headers. There are also other ways to control your API usage; check them in this article.

  • Anticipate the number of credits usage and choose the right plan.

  • Store data for less frequently updated endpoints, such as /stocks on the client-side.

Check out documentation before getting started to see the weights of each endpoint. If you need more credits or access to premium endpoints, you may upgrade your plan here.

Pricing credo

The mission of Twelve Data is to organize the world's financial data and make it universally accessible. We strive to become the single place where all customers, from individual traders to well-established institutions, will find all financial data. However, not all data has the same value. For example, getting a company's logo is much simpler than getting a company's fund holders.

The API credit system with minute quota allocations allows us to achieve the highest level of transparency and easiness of use across all endpoints - with a single subscription. Data weighting depends on the cost of maintaining the data and the frequency of updates. Some data could be easily collected with convenient formats others require lots of work for standardizing the dataset; some endpoints update every minute, other every hour. All details influence the data weighting.

Thank you for supporting our mission!

Did this answer your question?