API unit balance

Basic docs divider

Last updated: March 24, 2025

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:

By using the following free API requests for Standard and .Trends API:

Price: free

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)

Copy code

http://www.semrush.com/users/countapiunits.html

Request example

Copy code

http://www.semrush.com/users/countapiunits.html?key=YOUR_API_KEY

Response example

Copy code

1,000

Price: free

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)

Copy code

http://api.semrush.com/analytics/ta/limits/key/

Request example

Copy code

http://api.semrush.com/analytics/ta/limits/key/API_KEY

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_limit parameter. Use it to limit the number of lines returned in a response to save on API units. For example, adding &display_limit=10 will 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.

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 403 error.

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)

Copy code

{
  "error": {
    "code": 403,
    "message": "????",
    "description": "????"
  }
}

Was this page helpful?

API unit balance

Check API unit balance

Standard API

Request parameters

.Trends API

Request parameters

Limits consumption

How API units are consumed

Check API request price

Optimize unit consumption

Cost calculation example

Not enough units

Errors

Partial number of lines