contacts

Telephone

United States

dropdown button

United States

Canada

United Kingdom

Spain

France

Italy

Germany

Australia

+1 (800) 815 - 9959

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

Monday - Friday

mobile-menu

Site Audit

Projects divider Last updated: August 18, 2021

Basic doc

About Site audit API

Below you will find methods that can be divided into 2 groups: Management, Reports.

Management

Allows you to enable Site Audit tool and edit an existing Site Audit’s campaign.

Where {ID} - id of the project.

The base URL

https://api.semrush.com/management/v1/projects/{ID}/siteaudit

Reports

A set of reports about your product.

The base URL

https://api.semrush.com/reports/v1/projects/{ID}/siteaudit

Filters

To apply a filter to a report, add the filter parameter with a URL-encoded string.

Filter string format

[+-]|field|operator|value1;...;valueN

Parameter Values Description
sign "+" or "-" Include or exclude
field string Filter by the specified field
operation Bw, Ew, Eq, Co Bw - begins withEw - ends withEq - equalsCo - contains
values string List of values separated by ';'

Example filter string

+|source_url|Co|semrush;site_audit

If you want to apply a number of filters, keep adding the filter parameter.

Example

https://api.semrush.com/reports/v1/projects/{ID}/siteaudit/snapshot/{snapshotId}/issue/{issueId}?filter={filter1}&filter={filter2}&filter={filter3}

Enable the site audit tool

Price: 100 API units per request

This request allows you to enable the Site Audit tool for a project, which will allow you to schedule audits, include or exclude pages from the crawl, and set the number of pages to crawl.

Request parameters
Name Value/Type Description
key* String

An identification key assigned to a user after subscribing to Semrush that is available via Profile page

domain

Project URL

scheduleDay

run periodically day(1..7) if 0 - manual start

notify

Email notification about the finished audit

allow

Mask ALLOW in this project

disallow

Mask DISALLOW in this project

pageLimit

Number of crawled page

userAgentType

Type of user agent. Available values:

0 - SEMrushBot Desktop
1 - SEMrushBot Mobile
2 - GoogleBot Desktop
3 - GoogleBot Mobile

removedParameters

Specifies URL parameters to be excluded from the audit scope

crawlSubdomains

Specifies whether to crawl subdomains of the selected domain. Available values:

true - SEMrushBot will crawl the selected domain, including its subdomains

false - SEMrushBot will crawl the selected domain, excluding its subdomains

respectCrawlDelay

Specifies whether SEMrushBot should follow the “crawl-delay” directive in robots.txt. Available values:

true - SemushBot will follow the “crawl-delay” directive in robots.txt

false - SemrushBot will crawl pages with an interval of 1 second

* Fields marked by an asterisk (*) are required

Endpoint (POST)

https://api.semrush.com/management/v1/projects/{ID}/siteaudit/enable?key=YOUR_API_KEY

Request example

{
  "domain": "www.mysite.com",
  "scheduleDay": 1,
  "notify": false,
  "allow": [
    "",
    "",
    ""
  ],
  "disallow": [
    "",
    "",
    ""
  ],
  "pageLimit": 1000,
  "userAgentType": 2,
  "removedParameters": [
    "",
    "",
    ""
  ],
  "crawlSubdomains": true,
  "respectCrawlDelay": false
}

Edit a campaign

Price: 100 API units per request

This request allows you to edit an existing Site Audit’s campaign, which will allow you to reschedule audits, change the scope of pages to crawl and the number of pages.

Request parameters
Name Value/Type Description
key* String

An identification key assigned to a user after subscribing to Semrush that is available via Profile page

domain

Project URL

scheduleDay

run periodically day(1..7) if 0 - manual start

notify

Email notification about the finished audit

allow

Mask ALLOW in this project

disallow

Mask DISALLOW in this project

pageLimit

Number of crawled page

userAgentType

Type of user agent. Available values:

0 - SEMrushBot Desktop
1 - SEMrushBot Mobile
2 - GoogleBot Desktop
3 - GoogleBot Mobile

removedParameters

Specifies URL parameters to be excluded from the audit scope

crawlSubdomains

Specifies whether to crawl subdomains of the selected domain. Available values:

true - SEMrushBot will crawl the selected domain, including its subdomains

false - SEMrushBot will crawl the selected domain, excluding its subdomains

respectCrawlDelay

Specifies whether SEMrushBot should follow the “crawl-delay” directive in robots.txt. Available values:

true - SemushBot will follow the “crawl-delay” directive in robots.txt

false - SemrushBot will crawl pages with an interval of 1 second

* Fields marked by an asterisk (*) are required

Endpoint (POST)

https://api.semrush.com/management/v1/projects/{ID}/siteaudit/save?key=YOUR_API_KEY

Request example

{
  "domain": "www.mysite.com",
  "scheduleDay": 1,
  "notify": false,
  "allow": [
    "",
    "",
    ""
  ],
  "disallow": [
    "",
    "",
    ""
  ],
  "pageLimit": 1000,
  "userAgentType": 2,
  "removedParameters": [
    "",
    "",
    ""
  ],
  "crawlSubdomains": true,
  "respectCrawlDelay": false
}

Get a list of a campaign's snapshots

Price: 100 API units per request

This request allows you to get a list of past audits' IDs, including the dates on which they were completed.

Request parameters
Name Value/Type Description
key* String

An identification key assigned to a user after subscribing to SEMrush that is available via Profile page

* Fields marked by an asterisk (*) are required

Response parameters
Name Value/Type Description
snapshot_id

Snapshot id

finish_date

Date when the last audit finished

* Fields marked by an asterisk (*) are required

Endpoint (GET)

https://api.semrush.com/reports/v1/projects/{ID}/siteaudit/snapshots?key=YOUR_API_KEY

Response example

{
  "snapshots": [
    {
      "snapshot_id": "540d9e420cf2e0c1006966e3",
      "finish_date": 1410178856809
    },
    {
      "snapshot_id": "54102bd20cf2e0c100696a10",
      "finish_date": 1410345954754
    }
  ]
}

Get text descriptions about issues

Price: 100 API units per request

This request allows you to get a description of why an issue could be harmful for a website and how it can be fixed.

Request parameters
Name Value/Type Description
key* String

An identification key assigned to a user after subscribing to SEMrush that is available via Profile page

* Fields marked by an asterisk (*) are required

Response parameters
Name Value/Type Description
id

Issue id

title

Issue Title

desc

Issue Description

title_page

Page Title

info_column
count_description
multidata
other_problem_link
desc_with_link

* Fields marked by an asterisk (*) are required

Endpoint (GET)

https://api.semrush.com/reports/v1/projects/{ID}/siteaudit/meta/issues?key=YOUR_API_KEY

Response example

{
  "issues": [
    {
      "id": 1,
      "title": "HTTP 5XX server errors",
      "desc": "5xx errors happen on the server\u2019s side. (500 \u2013 an internal server error; 503 \u2013 a server is unavailable; 507 \u2013 a server is running out of memory, etc.) \n\nHaving a lot of error pages negatively affects both User Experience and a search engine robot\u2019s crawlability, which can lead to less traffic to your website.",
      "title_page": "##count## pages returned 5XX status code upon request",
      "title_detailed": "This page returned 5XX status code on request",
      "info_column": "Code",
      "count_description": "This page returned 5XX status code on request",
      "multidata": false,
      "other_problem_link": "##count## more page on this site has 500 status code",
      "desc_with_link": " ##count## pages  returned 5XX status code upon request"
    }
  ]
}

Run audit

Price: 100 API units per request

This request allows you to run an audit.

Request parameters
Name Value/Type Description
key*

An identification key assigned to a user after subscribing to SEMrush that is available via Profile page

* Fields marked by an asterisk (*) are required

Response parameters
Name Value/Type Description
snapshot_id

Snapshot ID for this audit

* Fields marked by an asterisk (*) are required

Endpoint

https://api.semrush.com/reports/v1/projects/{ID}/siteaudit/launch?key=YOUR_API_KEY

Response example

{
  "snapshot_id": "54102d92e4b0f889a040c9c8"
}

Get information about a campaign

Price: 100 API units per request

This request allows you to get an overview of the last audit, including the number of found issues errors, warnings, and notices, the number of passed and failed checks, the number of crawled pages and the rest of pages to crawl, and the date of the last audit, etc.

Request parameters
Name Value/Type Description
key*

An identification key assigned to a user after subscribing to SEMrush that is available via Profile page

* Fields marked by an asterisk (*) are required

Response parameters
Name Value/Type Description
id

Project ID

url

Project URL

name

Project name

status

Audit’s status: Running, Finished, Checking, or Saving

errors

Number of errors found during the last audit

warnings

Number of warnings found during the last audit

notices

Number of notices found during the last audit

broken

Number of broken pages

blocked

Number of pages blocked from crawling

redirected

Number of redirecting pages

healthy

Number of healthy pages

haveIssues

Number of pages with issues

haveIssuesDelta

Difference in the number of issues found during the previous and last audits

defects

List of issue IDs detected on crawled pages and the number of times each issue was detected

markups

Number of markups detected on crawled pages. Supported markups are: Twitter Card, Open Graph, Schema.org, microfomats

depths

Number of clicks required for SEMrushBot to reach an analyzed page from the homepage

crawlSubdomains

Indicates whether SEMrushBot crawled subdomains of the selected of the analyzed domain:

true - SEMrushBot crawled the analyzed domain, including its subdomains

false - SEMrushBot crawled the analyzed domain, excluding its subdomains

respectCrawlDelay

Indicates whether SEMrushBot followed the “crawl-delay” directive in robots.txt:

true - SEMrushBot followed the “crawl-delay” directive in robots.txt

false - SEMrushBot crawled pages with an interval of 1 second

canonical

Indicates whether an analyzed page is marked with the rel=“canonical” link element

user_agent_type

Type of user agent:

0 - SEMRushBot Desktop
1 - SEMRushBot Mobile
2 - GoogleBot Desktop
3 - GoogleBot Mobile

last_audit

Date of the last audit

last_failed_audit

Date of the last site audit failure

next_audit

Date of next scheduled audit

running_pages_crawled

Number of pages crawled during the running audit

running_pages_limit

Crawled pages' limit for the running audit

pages_crawled

Number of crawled pages

pages_limit

Crawled pages limit

total_checks

Total checks made during the last audit

errors_delta

Difference in the number of errors found during the previous and last audits

warnings_delta

Difference in the number of warnings found during the previous and last audits

notices_delta

Difference in the number of notices found during the previous and last audits

mask_allow

Mask ALLOW in this project

mask_disallow

Mask DISALLOW in this project

removedParameters

URL parameters excluded from the audit scope

excluded_checks

IDs of issues (errors, warnings and notices) excluded from the audit scope

* Fields marked by an asterisk (*) are required

Endpoint (GET)

https://api.semrush.com/reports/v1/projects/{ID}/siteaudit/info?key=YOUR_API_KEY

Response example

{
  "id": 4594705336925861,
  "name": "test",
  "url": "semrush.com",
  "status": "FINISHED",
  "errors": 228,
  "warnings": 391,
  "notices": 9,
  "broken": 0,
  "blocked": 0,
  "redirected": 2,
  "healthy": 1,
  "haveIssues": 2,
  "haveIssuesDelta": 0,
  "defects": {
    "109": 2
  },
  "markups": {
    "twitterCard": 0,
    "openGraph": 0,
    "schemaOrg": 0,
    "microfomats": 0
  },
  "depths": {
    "0": 3
  },
  "crawlSubdomains": true,
  "respectCrawlDelay": false,
  "canonical": 0,
  "user_agent_type": 2,
  "last_audit": 1410346398040,
  "last_failed_audit": 0,
  "next_audit": -1,
  "running_pages_crawled": 178,
  "running_pages_limit": 500,
  "pages_crawled": 178,
  "pages_limit": 500,
  "total_checks": 22725,
  "errors_delta": 0,
  "warnings_delta": 0,
  "notices_delta": 0,
  "mask_allow": [],
  "mask_disallow": [],
  "removedParameters": [
    "rr",
    "r",
    "p"
  ],
  "excluded_checks": null
}

Get information about a snapshot

Price: 10000 API units per request

This request allows you to get an overview of an audit, including the website’s score, issues, its number of performed checks, etc.

Request parameters
Name Value/Type Description
key*

An identification key assigned to a user after subscribing to Semrush that is available via Profile page

snapshot_id String

Snaphot Id, or latest snapshot

* Fields marked by an asterisk (*) are required

Response parameters
Name Value/Type Description
quality.value

Website's score

quality.delta

Difference in scores a website received during the previous and last audits

snapshot_id

Snapshot ID

pages_crawled

Crawled pages

finish_date

Date when the last audit finished

warnings|errors|notices.id

Issue ID

warnings|errors|notices.count

Number of found issues

warnings|errors|notices.delta

Difference in the number of issues found during the previous and last audits

warnings|errors|notices.checks

The number of performed checks for errors, warnings, or notices

* Fields marked by an asterisk (*) are required

Endpoint (GET)

https://api.semrush.com/reports/v1/projects/{ID}/siteaudit/snapshot?key=YOUR_API_KEY&snapshot_id={snapshot_id}

Response example

{
  "quality": {
    "value": 42,
    "delta": 0
  },
  "errors": [
    {
      "id": 1,
      "count": 4,
      "delta": 0,
      "checks": 174
    }
  ],
  "warnings": [
    {
      "id": 101,
      "count": 2,
      "delta": 0,
      "checks": 127
    }
  ],
  "notices": [
    {
      "id": 201,
      "count": 1,
      "delta": 0,
      "checks": 127
    }
  ],
  "snapshot_id": "54102d92e4b0f889a040c9c8",
  "pages_crawled": 178,
  "finish_date": 1410346398040
}

Detailed report for an issue

Price: 100 API units per request info

Alternative price:
100 API units by one issue

This report provides a description of an issue, when that issue was detected, as well as the URLs of affected pages. Works only for the last snapshot.

Response parameters
Name Value/Type Description
limit

Limit result on one page

page

Page number

total

Total number of results per request

issue_id

Issue ID

title

The title of a page on which an error has been detected

info

Issue's description

first_seen

First seen

last_seen

Date when an issue was last noticed

target_url

Target URL (for example, for a broken link issue, a URL of a webpage returning an error status will be shown)

page_id

Page ID

source_url

The URL of a webpage on which an error has been detected

* Fields marked by an asterisk (*) are required

Endpoint (GET)

https://api.semrush.com/reports/v1/projects/{ID}/siteaudit/snapshot/{snapshotId}/issue/

Request example

https://api.semrush.com/reports/v1/projects/{ID}/siteaudit/snapshot/{snapshotId}/issue/{issueId}?page={page}&filter={filter}&sort={sort}&limit={limit}&key=YOUR_API_KEY

Response example

{
  "limit": 10,
  "page": 1,
  "total": 101,
  "data": [
    {
      "title": "Web Tutorials  \u2022  Mike & Associates",
      "info": "404",
      "first_seen": 1410178856809,
      "last_seen": 1410346398040,
      "target_url": "http://semrush.com/errors/404.html",
      "page_id": "54102d9e0cf2e0c100696c88",
      "source_url": "http://semrush.com"
    }
  ],
  "issue_id": 8
}

Get page id by an url

Price: 100 API units per request

This request helps you get an ID of a crawled page.

Request parameters
Name Value/Type Description
key* String

An identification key assigned to a user after subscribing to SEMrush that is available via Profile page

url* String

url for search(contains match)

limit integer default 10

limit data line

* Fields marked by an asterisk (*) are required

Response parameters
Name Value/Type Description
page_id

page id

total

Total number of results per request

* Fields marked by an asterisk (*) are required

Endpoint (GET)

https://api.semrush.com/reports/v1/projects/{ID}/siteaudit/page/list?url_contains={url}&limit={limit}&key=YOUR_API_KEY

Response example

{
  "data": [
    {
      "url": "http://semrush.com",
      "page_id": "54102d9e0cf2e0c100696c88"
    }
  ],
  "total": 178
}

Get information about a page

Price: 1000 API units per request

This request allows you to get information about a page, and to get a list of its issues.

Request parameters
Name Value/Type Description
key* String

An identification key assigned to a user after subscribing to SEMrush that is available via Profile page

pageId* String

page ID

* Fields marked by an asterisk (*) are required

Response parameters
Name Value/Type Description
weight

This page's weight

title

This page's title

url

URL

notices|warnings|errors.id

Issue ID

notices|warnings|errors.discovered

Date when an issue was first noticed

notices|warnings|errors.info

Issue's description

notices|warnings|errors.target_url

Target URL (for example, for a broken link issue, a URL of a webpage returning an error status will be shown)

notices|warnings|errors.total

Total Issues

page_id

Page ID

* Fields marked by an asterisk (*) are required

Endpoint (GET)

https://api.semrush.com/reports/v1/projects/{ID}/siteaudit/page/{pageId}?key=YOUR_API_KEY

Response example

{
  "weight": 0,
  "title": "Web Tutorials  \u2022  Mike & Associates",
  "url": "http://semrush.com",
  "notices": [
    {
      "id": 202,
      "data": [
        {
          "discovered": 1410178856809,
          "info": null,
          "target_url": "http://%/test.com"
        }
      ],
      "total": 8
    }
  ],
  "warnings": [
    {
      "id": 110,
      "data": [
        {
          "discovered": 1410178856809,
          "info": null,
          "target_url": "http://semrush.com/index_files/html.jpg"
        }
      ],
      "total": 200
    }
  ],
  "errors": [
    {
      "id": 8,
      "data": [
        {
          "discovered": 1410178856809,
          "info": "503",
          "target_url": "http://semrush.com/errors/503.html"
        }
      ],
      "total": 101
    }
  ],
  "page_id": "54102d9e0cf2e0c100696c88"
}

Get snaphots history

Price: 10000 API units per request info

Alternative price:
10000 API units by one snapshot

This request allows you to see audits’ results for a selected period.

Request parameters
Name Value/Type Description
key*
limit* Integer default 7

limit

offset* Integer default 0

offset

* Fields marked by an asterisk (*) are required

Response parameters
Name Value/Type Description
quality.value

Website's score

quality.delta

Difference in scores a website received during the previous and last audits

snapshot_id

Snapshot ID

pages_crawled

Crawled pages

finish_date

Date when the last audit finished

warnings|errors|notices.id

Issue ID

warnings|errors|notices.count

Number of found issues

warnings|errors|notices.delta

Difference in the number of issues found during the previous and last audits

warnings|errors|notices.checks

the number of performed checks for errors, warnings, or notices

* Fields marked by an asterisk (*) are required

Endpoint (GET)

https://api.semrush.com/reports/v1/projects/{ID}/siteaudit/history?limit={limit}&offset={offset}&key=YOUR_API_KEY

Response example

{
  "data": [
    {
      "quality": {
        "value": 42,
        "delta": 0
      },
      "errors": [
        {
          "id": 1,
          "count": 4,
          "delta": 0,
          "checks": 174
        }
      ],
      "warnings": [
        {
          "id": 101,
          "count": 2,
          "delta": 0,
          "checks": 127
        }
      ],
      "notices": [
        {
          "id": 201,
          "count": 1,
          "delta": 0,
          "checks": 127
        }
      ],
      "snapshot_id": "54102d92e4b0f889a040c9c8",
      "pages_crawled": 178,
      "finish_date": 1410346398040
    }
  ],
  "total": 0,
  "limit": 0,
  "offset": 0
}