contacts

Telephone

United States

dropdown button

United States

Canada

United Kingdom

Spain

France

Italy

Germany

Australia

+1 (800) 815 - 9959

10:00 AM - 5:00 PM (EST/EDT)

Monday - Friday

mobile-menu

Basic docs

Version 4 divider Last updated: January 15, 2022

Get started API 4

Endpoint

https://api.semrush.com/apis/v4/

Authorization

Semrush API supports authorization with the Oauth2 flow. Please pass your Oauth2 authorization token in the HTTP request header.

Authorization: Bearer ****

Authentication

Semrush API supports two ways to grant OAuth2 credentials:

  • Device Authorization Grant flow (RFC 8628)
  • Semrush Auth flow

Use one of these options to authenticate in Semrush API.

Device Authorization Grant flow

Step 1. Device Authorization request

  1. 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.
  2. The client makes a device authorization request to the device authorization endpoint by including the following scope parameter.

Request parameters

Name Description
scope Requested scopes, comma-separated string

Step 2. User interaction

  1. 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.
  2. The authorizing user navigates to verification_uri and is redirected to the authorization server with the session state code.
  3. The authorization server redirects the user to the DAG authentication service with the authorization code granted and the original state parameter.
  4. 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 Section 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.

Semrush Auth

Step 1. Get code

  1. Open the authorization URL in your browser.
  2. 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.
  3. Copy the value of the code parameter. In the earlier example, it's UTyWR6YQAPUbtLIX9jWM4OifmK1ODVWDOVUt8hlk.
background image
Note:

If you have the SEOquake extension installed, you may not see the code parameter in the URL. In this case, disable the extension and repeat this step.

Step 2. Get access token

Make a POST request using the value you copied as the value of the code parameter:

Request example

curl -L 'https://oauth.semrush.com/oauth2/access_token' -d 'client_id=seoquake' -d 'client_secret=d41d8cd98f00b204e9800998ecf8427e' -d 'grant_type=authorization_code' -d 'code=zSypMRLSwnVFtp5Z2lUkU6fX3D3WjoyUesnuytPW' -d 'redirect_uri=https%3A%2F%2Foauth.semrush.com%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=seoquake&client_secret=d41d8cd98f00b204e9800998ecf8427e&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" }

Response format of the API

The response body contains a JSON-encoded object, which has a top-level object meta, followed by either a data object or an error object, but not both. An explanation of each of these properties can be found below.

Object meta
Key Type Description Optional
success boolean Status of the request Mandatory
status_code int HTTP status code Mandatory
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" } ] }

Object error
Key Type Description Optional
code int Error code Mandatory
message string Error message Mandatory
description string Error description Optional

Failed response example

{ "meta": { "success": false, "status_code": 400, "request_id": "IAD-123ade456" }, "error": { "code": 120200, "message": "This was bad", "description": "google.me?error=120200" } }