Messages are the fundamental units used to access data and make API calls on IEX Cloud. Each API endpoint has a certain “data weight,” or a given number of messages that are used every time you make an API call with that endpoint.
For example, the Earnings endpoint has a data weight of 1,000 messages per symbol per period. This means you would use 1,000 messages to see a company’s earnings for one specific quarter.
Messages make your subscription with IEX Cloud flexible and adjustable to your use case. You may use a higher volume of lower-weighted endpoints, fewer higher-weighted endpoints, or a combination. Note that certain endpoints are only available with paid plans on IEX Cloud.
The IEX Cloud Console “Message Use” tab automatically keeps track of how many messages you have used so far in the month. Check out our API documentation to see the data weights for different endpoints on IEX Cloud.
Why do different API endpoints use different numbers of messages?
Data weights are determined by a number of factors, including agreements between IEX Cloud and our third-party data providers, the cost of sourcing the data further upstream, and other computational costs.
Rather than requiring customers to pay for a preset selection of data in bulk, messages give you the flexibility to choose exactly the data you want to use with your subscription and how often you want to use it. IEX Cloud serves a diverse range of use cases and is designed to make data accessible for everyone.
Core messages vs. Pay-as-you-go messages
Each IEX Cloud plan provides a different number of monthly core messages, as well as a different pay-as-you-go message rate.
Core messages represent the base number of messages included with your subscription each month. Core messages can be used towards any of the Core Data endpoints included with your plan. Your core message usage is reset at the beginning of each calendar month.
Pay-as-you-go messages can be used in addition to your core messages as needed and are priced at a discounted rate. After you’ve used your core messages for a given month, you can use pay-as-you-go messages to continue accessing as much data as you need. Pay-as-you-go messages can also be used to access Premium Data — specialized datasets that can be added onto your subscription.
It’s highly recommended that you enable the automatic use of pay-as-you-go messages in the IEX Cloud Console. This setting helps prevent disruption in your service and allows IEX Cloud to default over to using pay-as-you-go messages after you have used all of your core messages for the month.
If you do not have the automatic use of pay-as-you-go messages enabled, IEX Cloud will pause access to data after you have used all of your core messages and will restore access at the beginning of the next month.
How many messages do I need, and which plan should I choose?
Each IEX Cloud plan provides a different monthly allocation of core messages, a pay-as-you-go message rate, and a designated set of tools and available datasets. Higher plans offer a larger number of core messages, a less expensive pay-as-you-go message rate, and a broader set of tools and data.
You can choose your IEX Cloud plan based on the data you would like to access as well as the number of messages you estimate you’ll need on a monthly basis. Once you know what data you would like to use on IEX Cloud, you can estimate your monthly message usage by referencing those endpoints’ data weights in our documentation and multiplying that weighting by how frequently you will request this data.
Our calculator here can help assist with estimation. Alternatively, use the following formula as a guideline:
Data Weight x Number of Symbols x Frequency = Message Use for that API Endpoint
For example, let’s say you were looking to see the last three quarters’ earnings for a list of 5,000 companies. The Earnings endpoint uses 1,000 messages per symbol per period.
Your message usage for that endpoint would be:
(1,000 messages) x (5,000 symbols) x (3 periods) x (1 call per symbol) = 15,000,000 messages
Best practices for messages
Make the most of your messages by checking out these IEX Cloud features:
- Sandbox testing: Test IEX Cloud for free with randomized test data — no messages required.
- Cloud Cache: More efficiently use your messages by storing and reusing the data that you’ve already requested from IEX Cloud. Let us handle the work for you by enabling Cloud Cache. Cloud Cache is available as an add-on to all paid plans.
- Pay-as-you-go messages: Enable pay-as-you-go messages in the IEX Cloud Console. This ensures that you can continue to access data without interruption if you use all the core messages allocated with your subscription for the month.
- Getting Started on IEX Cloud
- How do I stream data?
- Can I cache data?
- Testing with the IEX Cloud Sandbox
- How to use the IEX Cloud API
- Can I use more messages once I’ve hit the monthly message quota?
- Other FAQs