logo-small

SEMrush API

Any questions?
US customers, Toll-Free
+1-800-815-9959
offline
Monday through Friday (ET)
Europe customers, Toll-Free
United Kingdom
España
France
Italia
+44 (808) 1642570
online
Monday through Friday in your local time

Semrush API v4.0

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

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

Authorization: Bearer ****

Authentication

Semrush API supports the Device Authorization Grant flow (RFC-8628) to grant Oauth2 credentials. Please follow these steps to authenticate in Semrush API:

1. Device Authorization Request

The client initiates the authorization flow by requesting a set of verification codes from the authorization server by 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 by including the following parameter scope (requested scopes, comma-separated string)

Request parameters

NameDescription
scope*requested scopes, comma-separated string
Fields marked with an asterisk (*) are required

Available scopes

NameDescription
siteaudit.infoGet information about your "Site Audit" projects and reports.

In response, the authorization server generates a unique device verification code and an end-user code that are valid for a limited time, and includes them in the HTTP response body using the application/json format.

Request example $ curl https://oauth.semrush.com/dag/device/code -d scope=siteaudit.info Response example { "device_code": "abcd1234abcd1234abcd1234abcd1234abcd1234abcd1234", "user_code": "ABCD-WXYZ", "verification_uri": "https://oauth.semrush.com/dag/auth/verify_code?code=ABCD-WXYZ", "expires_in": 300, "interval": 5 }

2. User Interaction

After receiving a successful authorization response, the client displays the user code and the verification URI to the end user and instructs them to visit the URI. The authorizing user navigates to the verification URI and is redirected to the authorization server with the session state code. The authorization server redirects the user back with the authorization code granted and the original state parameter.

Request example $ open https://oauth.semrush.com/dag/auth/verify_code?code=ABCD-WXYZ

3. Device Access Token Request

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

Request parameters

NameDescription
grant_type*The value MUST be set to urn:ietf:params:oauth:grant-type:device_code
device_code*The the device verification code, device_code from the device authorization response, defined in Section 1
Fields marked with an asterisk (*) are required

Request example $ curl https://oauth.semrush.com/dag/device/token -d device_code=abcd1234abcd1234abcd1234abcd1234abcd1234abcd1234 -d grant_type=urn:ietf:params:oauth:grant-type:device_code Response example { "access_token": "xyz567xyz567xyz567xyz567xyz567", "token_type": "Bearer", "expires_in": 604800, "refresh_token": "pqr098pqr098pqr098pqr098pqr098" }

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

  • authorization_pending
  • slow_down
  • access_denied
  • expired_token
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
success* boolean Status of the request
status_code* int HTTP status code
request_id string Unique ID of the request
Fields marked with an asterisk (*) are mandatory, otherwise 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
code* int Error code
message* string Error message
description string Error description
Fields marked with an asterisk (*) are mandatory, otherwise 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" } }

Site Audit API

Requiered scopes

Access token should be issued with following scopes to access to this API section.
NameDescription
siteaudit.infoGet information about your "Site Audit" projects and reports.
Price: 100 API units per request

This request allows you to get a list of Siteaudit campaigns for your account.

Request method

GET

Endpoint

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

Response example

{ "data": { "campaigns": [ { "campaign_id": 123, "name": "Campaign name", "url": "campaign.url" }, { "campaign_id": 1234, "name": "Campaign2 name", "url": "campaign2.url" } ] } }
Price: 100 API units per request

This request allows you to get the status of the Siteaudit campaign by ID.

Request method

GET

Endpoint

https://api.semrush.com/apis/v4/siteaudit/campaigns/{campaign_id:[0-9]+}/status

Response example

{ "data": { "campaign_id": 123, "status": "FINISHED" } }

This request allows you to get a list of tasks for your Site Audit campaign.

Request method

GET

Endpoint

https://api.semrush.com/apis/v4/siteaudit/campaigns/{campaign_id:[0-9]+}/tasks

Response example

{ "data": { "tasks": [ { "id": "6133a19", "title": "title", "url": "http://example/", "howToFix": "howToFix", "comment": "comment" } ] } }
Price: 10000 API units per request

This request allows you to get the Site Audit Overview report.

Request method

GET

Endpoint

https://api.semrush.com/apis/v4/siteaudit/campaigns/{campaign_id:[0-9]+}/reports/overview

Response example

{ "data": { "campaign_id": 12345, "name": "example", "url": "example", "status": "FINISHED", "last_audit": 1590000000000, "pages_crawled": 100, "pages_limit": 100, "summary": { "errors": 6, "warnings": 543, "notices": 114, "blocked": 2, "redirected": 3, "healthy": 11, "have_issues": 84, "have_issues_delta": 1, "errors_delta": 2, "warnings_delta": -13, "notices_delta": -81 }, "current_snapshot": { "quality": { "value": 76, "delta": 2 }, "thematic_scores": { "https": { "value": 99 }, "int_seo": { "value": 100 }, "crawlability": { "value": 94, "delta": 4 }, "performance": { "value": 98, "delta": -2 }, "linking": { "value": 96, "delta": 2 } } } } }
Price: 100 API units per request

This request allows you to create a new project and set up a Site Audit campaign.

Request method

POST

Endpoint

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

Request body

{ "name": "Example", "pages_limit": 1000, "start_crawl_url": "https://www.example.com/landing/" }

Response example

{ "data": { "project_id": 123 } }
Price: 100 API units per request

This request allows you to start a new audit for an existing campaign.

Request method

POST

Endpoint

https://api.semrush.com/apis/v4/siteaudit/campaigns/{campaign_id:[0-9]+}/recrawl

Response example

{ "data": { "campaign_id": 123, "status": "RUNNING" } }