Basic docs

Version 4

Last updated: March 3, 2025

Semrush API 4 is available only for the following Semrush tools and under specific conditions:

To use the Projects API, you must have the Business subscription and available API units. Learn more about the Standard API ›
The Listing Management API is available for all Semrush Local Advanced Plan users. You don't need to buy API units to use it. Learn more about the Listing Management API ›
The Map Rank Tracker API is available to all Semrush users upon request. You don't need to buy API units to use it. Learn more about the Map Rank Tracker API ›

Map Rank Tracker API lets you access critical data related to your campaigns, keywords, and competitors. The methods provide detailed information about campaign rankings, heatmaps, competitors, and keyword performance. By easily integrating real-time data into your existing systems, you can stay ahead in your SEO strategies.

Learn more about Map Rank Tracker ›

You don't need to purchase API units or have a special subscription to access the Map Rank Tracker API.

To get started with Map Rank Tracker API, get your Bearer Token as described in the Authentication section.

Semrush API supports authorization with the OAuth 2.0 flow. You need to pass your OAuth 2.0 authorization token in the HTTP request header:

Authorization: Bearer <TOKEN>

The Semrush API supports two ways to grant OAuth 2.0 credentials:

Semrush Auth flow
Device Authorization Grant flow (RFC 8628)

Use one of these options to authenticate in the Semrush API.

Semrush Auth

Step 1. Get code

Contact the Semrush Tech Support to obtain your client_id and client_secret.
Replace YOUR_CLIENT_ID with your client_id and open the link in your browser:
https://oauth.semrush.com/oauth2/authorize?client_id=YOUR_CLIENT_ID&redirect_uri=%2Foauth2%2Fsuccess&response_type=code&scope=user.id
Log in to Semrush, if needed, and click Approve to provide access to the data. You will then be redirected to a new page with the Authorization provided title. Its URL will look similar to this: https://oauth.semrush.com/oauth2/success?code=UTyWR6YQAPUbtLIX9jWM4OifmK1ODVWDOVUt8hlk.
Copy the value of the code parameter. In the earlier example, it's UTyWR6YQAPUbtLIX9jWM4OifmK1ODVWDOVUt8hlk.

Step 2. Get access token

Make a POST request using the value you copied as the code parameter value. In addition, replace YOUR_CLIENT_ID and YOUR_CLIENT_SECRET with the ones you received from Tech Support:

Request content type

Note that the next request does not use json-body. Instead, the content type is application/x-www-form-urlencoded.

Request example

curl -L 'https://oauth.semrush.com/oauth2/access_token' -H 'Content-Type: application/x-www-form-urlencoded' -d 'client_id=YOUR_CLIENT_ID' -d 'client_secret=YOUR_CLIENT_SECRET' -d 'grant_type=authorization_code' -d 'code=YOUR_CODE' -d 'redirect_uri=%2Foauth2%2Fsuccess'

Response example

{ "access_token": "wz1q0IpUBLLX7fqBKJI4pUoKBLZghAKp1VmBuJy5", "token_type": "Bearer", "expires_in": 604800, "refresh_token": "KTL5iInbFLIhm428FIKtHXO1ZX7ZUKNJTBoD9jk3" }

Use the access_token value when making requests to the API. To get a new one when it expires, use refresh_token:

Request example

curl -X POST -d "client_id=YOUR_CLIENT_ID&client_secret=YOUR_CLIENT_SECRET&grant_type=refresh_token&refresh_token=KTL5iInbFLIhm428FIKtHXO1ZX7ZUKNJTBoD9jk3" https://oauth.semrush.com/oauth2/access_token

Response example

{ "access_token": "u8pPo6fo2NV70QCy7USWd3iT34CenBiT8RSuEEGn", "token_type": "Bearer", "expires_in": 604800, "refresh_token": "s99qrRuqbUdFRnum3R1HC9dTEJMOMs0IU1hJSi7W" }

Device Authorization Grant flow

Step 1. Device Authorization request

The client initiates the authorization flow by requesting a set of verification codes from the authorization server, making an HTTP POST request to the https://oauth.semrush.com/dag/device/code endpoint.
The client makes a device authorization request to the device authorization endpoint: https://oauth.semrush.com/dag/device/code. If the API requires access scope, you can use this optional API parameter: scope=<scope>.

Step 2. User interaction

After receiving a successful authorization response, the client displays user_code and verification_uri to the end user and instructs them to visit the URI.
The authorizing user navigates to verification_uri and is redirected to the authorization server with the session state code.
The authorization server redirects the user to the DAG authentication service with the authorization code granted and the original state parameter.
The DAG authentication service substitutes the returned authorization code with the access token using its client_id and secret.

Request example

$ open https://oauth.semrush.com/dag/auth/verify_code?code=AVZV-MSPD

Step 3. Device Access Token request

During the user interaction, the device continuously polls the https://oauth.semrush.com/dag/device/token token endpoint using the POST HTTP method with the device_code provided, until the user completes the interaction, the code expires, or another error occurs. The device_code value is not intended for the end user directly; thus, it shouldn't be displayed during the interaction to avoid confusing the end user.

Request parameters

Name	Description
grant_type	Value must be set to `urn:ietf:params:oauth:grant-type:device_code`.
device_code	Device verification code, `device_code` from the device authorization response, defined in Step 1.

Request example

$ curl https://oauth.semrush.com/dag/device/token -d device_code=7ee7a929306d4075b9c4020e584fe4508862f26605e37c131eb6efe2f83b6dd0 -d grant_type=urn:ietf:params:oauth:grant-type:device_code

Response example

{ "access_token": "e3wLk3PtqyVPHM7Ele61OhuZFWtKCFK4O1HQslzh", "token_type": "Bearer", "expires_in": 604800, "refresh_token": "YWza6vpqkW628wtMldRsQNalEu9k33Vg75PQiXGi" }

If the user has approved the grant, the token endpoint responds with a success response defined in Section 5.1 of RFC 6749. Otherwise, it responds with an error, as defined in Section 5.2 of RFC 6749. In addition to the error codes defined in Section 5.2 of RFC 6749, the following error codes are specified for use with the device authorization grant in token endpoint responses.

The response body contains a JSON-encoded object, which has a top-level object called meta, followed by either a data object or an error object, but not both.

Meta object
Key	Type	Description	Required/Optional
success	boolean	Request status	Required
status_code	integer	HTTP status code	Required
request_id	string	Unique ID of the request	Optional

Success response example

{ "meta": { "success": true, "status_code": 200, "request_id": "IAD-as5656as776" }, "data": [ { "id": "590e", "kind": "dog", "name": "Penny" }, { "id": "a45f", "kind": "cat", "name": "Tommy" } ] }

Error object
Key	Type	Description	Required/Optional
code	integer	Error code	Required
message	string	Error message	Required
details	array	Error details	Optional

Failed response example

{ "meta": { "success": false, "status_code": 400, "request_id": "IAD-123ade456" }, "error": { "code": 120200, "message": "This was bad", "details": [ { "message": { "field_violations": [ { "field": "user_id", "description": "user_id must be a number" } ] } } ] } }

The API version 4 returns a corresponding HTTP status code with every request response, whether it succeeds or fails.

Code	Description	Recommended action
2XX OK	The request was processed successfully.	No action required.
400 Bad Request	The request couldn't be processed because it was incorrect or incomplete.	Check the request body for typos and missing parameters. For details, refer to the optional 'error.details' field if it's present in the response.
401 Unauthorized	The request couldn't be processed because the provided authentication credentials were incorrect or missing.	Ensure the access token you use for accessing the API is still valid.
403 Forbidden	The request couldn't be processed due to a restriction or permission issue.	Contact the Semrush Support Team.
404 Not Found	The request couldn't be processed because the target resource was incorrect or had been moved.	Ensure the target resource exists and is specified correctly in the request.
409 Conflict	The request couldn't be processed due to a conflict with the current state of the resource.	Retry the request later or check the resource state–for example, when creating a project, confirm it doesn't already exist.
429 Too Many Requests	The request couldn't be processed because there were too many requests from the user with the given access token.	Retry the request later.
499 Client Closed Request	The request couldn't be processed because the user disconnected before receiving a response.	Check your network connection and retry the request later.
550 Internal Server Error	The request couldn’t be processed due to a server-side error.	Retry the request later.
551 Not Implemented	The request couldn't be processed because the specified request method isn’t supported.	To check all available methods, refer to the API version 4 reference.
553 Service Unavailable	The request couldn't be processed due to server maintenance or overload.	Retry the request later.
554 Gateway Timeout	The request couldn't be processed due to a timeout at the acting gateway or proxy server.	Retry the request later.

Show all

Basic docs

Get started with API 4

Map Rank Tracker API overview

Authorization

Authentication

Semrush Auth

Step 1. Get code

Step 2. Get access token

Device Authorization Grant flow

Step 1. Device Authorization request

Step 2. User interaction

Step 3. Device Access Token request

Request parameters

API response format

Status codes