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:

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

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

1,000

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.

Jump to How API units are consumedHow 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).

Jump to Check API request priceCheck 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.

Jump to Optimize unit consumptionOptimize unit consumption

1. 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.
2. Estimate API unit usage. Before making an API request, calculate the potential unit cost to prevent excessive usage.

Jump to Cost calculation exampleCost 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.

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

Jump to View your Semrush API query logView your Semrush API query log

Semrush provides a dedicated report where you can review your recent API requests and track how your API units are used. To find this information in the Semrush UI, go to My Profile → Query log → API Queries.

API Queries only has logs for the Standard Semrush API v3. Logs for Trends API and Semrush API v4 aren’t listed. If you need to review your Trends API request log, contact Semrush Customer Support.

The API Queries report shows a detailed log of your v3 API activity, including:

• Query: What was the domain, subdomain, subfolder, URL, or keyword queried (when applicable).
• Time: When the request was sent.
• User IP address: IP that initiated the request.
• DB: Database selected for the query (when applicable).
• Report type: Specific API report requested.
• Historical: Whether the request retrieved historical data (when applicable).
• Requested rows: Number of rows queried.
• Offset: Based on display_offset, what the data offset was that the request started from (when applicable).
• Report cost: Number of API units spent for the data returned.
• API units: Standard API unit balance remaining after that specific request.

This information helps you monitor API usage, troubleshoot unexpected unit consumption, and analyze request history.

Jump to Export your API request log dataExport your API request log data

You can export your v3 API request log in CSV directly from the API queries report. Use the Export button in the top-right corner of the table. You can choose to export:

• All available records (up to 50,000).
• Only the first N rows, selecting a limit such as 100, 500, 1,000, 10,000, 30,000, or 50,000.

If your API Queries log has more than 50,000 entries, request an export via Semrush Customer Support.

You can use the exported file for internal reports, sharing with your team, or analyzing in Excel or Google Sheets.