Developer
Telephone
United States
+1 (800) 815 - 9959
10:00 AM - 5:00 PM (EST/EDT)
Monday - Friday
API unit balance
Basic docs
Last updated: March 24, 2025
Last updated: March 24, 2025
Check API unit balance
When you purchase an API unit package in addition to your Business subscription, you'll have a limited number of API units to make calls. If you run out of API units, you can buy more on the Subscription info page or contact our sales representatives. To learn more, refer to How to get API.
Make sure your API unit balance is sufficient before making requests. You can check your remaining units in two ways:
- In the Subscription info tab:
Standard API
This request returns the number of remaining API units to help you manage usage.
Request parameters
| Name | Value/Type | Description |
|---|---|---|
| key* | YOUR_API_KEY | Identification key assigned to each user after subscribing to Semrush. You'll find it in Subscription info > API units. |
* Fields marked by an asterisk (*) are required
Endpoint (GET)
http://www.semrush.com/users/countapiunits.html
Request example
http://www.semrush.com/users/countapiunits.html?key=YOUR_API_KEY
Response example
1,000
.Trends API
This request returns your monthly, daily, and hourly API unit usage. This helps you monitor and optimize your API consumption.
Request parameters
| Name | Value/Type | Description |
|---|---|---|
| key* | API_KEY | Identification key assigned to each user after subscribing to Semrush. You'll find it in Subscription info > API units. |
* Fields marked by an asterisk (*) are required
Endpoint (GET)
http://api.semrush.com/analytics/ta/limits/key/
Request example
http://api.semrush.com/analytics/ta/limits/key/API_KEY
Limits consumption
Each request to the Semrush API consumes a specific number of units, depending on the type of report and the amount of data requested.
To effectively manage API usage, it is crucial to understand how units are consumed and how to optimize requests.
Requests to the methods of Listing Management and Map Rank Tracker don't use up API units.
How API units are consumed
Different API reports have varying unit costs:
- Reports that charge per line of data returned (for example, Domain reports).
- Reports that have a fixed cost per request (for example, Backlinks overview).
Check API request price
You can check how many units are consumed for each report or request in the API documentation under the respective report or request name.
The total request price is calculated based on the number of lines in the report or particular request.
Besides regular data, most analytical data also contains historical data which costs more than regular data requests. For details, refer to Historical data.
Optimize unit consumption
- Use the display_limit parameter. Certain types of reports within Semrush API support the
display_limitparameter. Use it to limit the number of lines returned in a response to save on API units. For example, adding&display_limit=10will limit your request to the top 10 results. - Estimate API unit usage. Before making an API request, calculate the potential unit cost to prevent excessive usage.
Cost calculation example
Suppose you need to analyze organic keyword rankings for a list of 50 domains using the Domain Organic Search Keywords report.
You need 500 keywords per domain with the following conditions:
- Regular data for the last month (current rankings)
- Historical data from 12 months ago for comparison
It means that:
- For regular data, you will spend 500 keywords × 10 units per keyword × 50 domains = 250,000 units.
- For historical data, you will spend 500 keywords × 50 units per keyword × 50 domains = 1,250,000 units.
The total number of API units required is 1,500,000.
Not enough units
Depending on the report and API version, you'll get either an error or a partial number of lines.
Errors
If you don't have enough API units for the requested number of lines or requests:
- In API version 3, you'll get
ERROR 132. - In API version 4, you'll get the
403error.
Partial number of lines
In API version 3, for reports that cost per line, you will get the number of lines for which you have enough API units.
Therefore, it's important to check the API unit balance so you don't lose data.
Response example (API v4)
{
"error": {
"code": 403,
"message": "????",
"description": "????"
}
}