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

Site Audit

Projects divider Last updated: April 30, 2024

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}

Issue IDs

Value Description
1 5xx errors
2 4xx errors
3 Title tag is missing or empty
4 Blocked from crawling
6 Duplicate title tag
7 Duplicate content
8 Broken internal links
9 Pages not crawled
10 DNS resolution issue
11 We couldn’t open the page’s URL
13 Broken internal images
15 Duplicate meta descriptions
16 Invalid robots.txt format
17 Invalid sitemap.xml format
18 Incorrect pages found in sitemap.xml
19 www resolve issues
20 Viewport not configured
21 Large HTML page size
22 Missing canonical tags in AMP pages
26 Non-secure pages
27 Certificate Expiration
28 Old security protocol version
29 Certificate registered to incorrect name
30 Issues with mixed content
32 Neither canonical URL nor 301 redirect from HTTP homepage
33 Redirect chains and loops
34 AMP Pages with HTML Issues
35 AMP Pages with Style and Layout Issues
36 AMP Pages with Templating Issues
38 Broken canonical URLs
39 Multiple canonical URLs
40 Meta refresh redirects
41 Broken internal JavaScript and CSS files
42 Insecure encryption algorithms
43 Sitemap file too large
44 Malformed links
45 Structured data that contains markup errors
46 Viewport width not set
111 Slow page load speed
12 Broken external links
14 Broken external images
31 Links lead to HTTP pages for HTTPS site
101 Title element is too short
102 Title element is too long
103 Missing h1
104 Multiple h1 tags
105 Duplicate content in h1 and title
106 Missing meta description
108 Too many on-page links
109 Temporary redirects
110 Missing ALT attributes
112 Low text to HTML ratio
113 Too many URL parameters
114 Missing hreflang and lang attributes
115 Encoding not declared
116 Doctype not declared
117 Low word count
120 Incompatible plugins used
121 Frames used
122 Underscores in URL
123 Nofollow attributes in internal links
124 Sitemap.xml not specified in robots.txt
125 Sitemap.xml not found
126 HTTPS encryption not used
127 No SNI support
128 HTTP URLs in sitemap.xml for HTTPS site
129 Uncompressed pages
130 Disallowed internal resources
131 Uncompressed JavaScript and CSS files
132 Uncached JavaScript and CSS files
133 Too large JavaScript and CSS total size
134 Too many JavaScript and CSS files
135 Unminified JavaScript and CSS files
136 Warning - Too long URLs
201 Too long URLs
202 Nofollow attributes in external links
203 Robots.txt not found
205 No HSTS support
206 Orphaned pages (Google Analytics)
207 Orphaned sitemap pages
208 Pages have high Document Interactive Time
209 Blocked by X-Robots-Tag: noindex HTTP header
210 Disallowed external resources
211 Broken external JavaScript and CSS files
212 Page crawl depth
213 Pages with only one internal link
214 Permanent redirects
215 Resources formatted as page links
216 Links with no anchor text
217 Links with non-descriptive anchor text
218 External pages or resources with 403 HTTP status code
Show all

Enable Site Audit tool

Price: 100 API units per request

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

About the Site Audit configuration ›

Request parameters
Name Value/Type Description
key* string

The API key for your Semrush account.

domain* string

The project URL.

scheduleDay integer

Specifies the day of the week (from 1 to 7) for periodic execution; use 0 for manual start.

notify boolean

Specifies whether an email notification is sent after the audit is completed.

allow array of strings

Masks the Allow directive in the project.

disallow array of strings

Masks the Disallow directive in the project.

pageLimit* integer

The number of crawled pages.

userAgentType integer

The type of user agent. Available values:

0: SemrushBot Desktop

1: SemrushBot Mobile

2: GoogleBot Desktop

3: GoogleBot Mobile

removedParameters array of strings

Specifies URL parameters to be excluded from the audit scope.

crawlSubdomains boolean

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

true: SemrushBot will crawl the selected domain and its subdomains.

false: SemrushBot will crawl only the selected domain.

respectCrawlDelay boolean

Specifies whether SemrushBot will follow the Crawl-delay directive in robots.txt. Available values:

true: SemrushBot will follow the Crawl-delay directive in robots.txt.

false: SemrushBot will crawl pages with a one-second interval.

* 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 campaign

Price: 100 API units per request

This request lets you edit an existing Site Audit campaign to reschedule audits and change the scope of pages to crawl and the number of pages.

About the Site Audit configuration ›

Request parameters
Name Value/Type Description
key* string

The API key for your Semrush account.

domain* string

The project URL.

scheduleDay integer

Specifies the day of the week (from 1 to 7) for periodic execution; use 0 for manual start.

notify boolean

Specifies whether an email notification is sent after the audit is completed.

allow array of strings

Masks the Allow directive in the project.

disallow array of strings

Masks the Disallow directive in the project.

pageLimit* integer

The number of crawled pages.

userAgentType integer

The type of user agent. Available values:

0: SemrushBot Desktop

1: SemrushBot Mobile

2: GoogleBot Desktop

3: GoogleBot Mobile

removedParameters array of strings

Specifies URL parameters to be excluded from the audit scope.

crawlSubdomains boolean

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

true: SemrushBot will crawl the selected domain and its subdomains.

false: SemrushBot will crawl only the selected domain.

respectCrawlDelay boolean

Specifies whether SemrushBot will follow the Crawl-delay directive in robots.txt. Available values:

true: SemrushBot will follow the Crawl-delay directive in robots.txt.

false: SemrushBot will crawl pages with a one-second interval.

jsRendering string

Specifies whether SemrushBot will render JavaScript files during crawling. Available values:

RENDER_ALL: Allows the bot to render JavaScript files.

DISABLED: The bot will crawl only the HTML files.

* 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 list of campaign snapshots

Price: 100 API units per request

This request lets you get a list of previous audit IDs along with their completion dates.

Request parameters
Name Value/Type Description
key* string

The API key for your Semrush account.

* Fields marked by an asterisk (*) are required

Response parameters
Name Value/Type Description
snapshot_id string

The snapshot ID.

finish_date integer

The timestamp in the Unix format showing when the last audit was completed, such as 1410178856809.

* 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 lets you get a detailed explanation of an issue and its cause. That helps you understand why an issue could be harmful to a website and how it can be fixed.

About the Site Audit Issues report ›

Request parameters
Name Value/Type Description
key* string

The API key for your Semrush account.

* Fields marked by an asterisk (*) are required

Response parameters
Name Value/Type Description
id integer

The issue ID.

title string

The issue title.

title_page string

The page title.

url_column string

The URL with the issue.

info_column string

The issue description.

* 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": 14,
      "title": "Broken external images",
      "title_page": "##count## external images are broken",
      "url_column": "Image URL",
      "info_column": "HTTP Code"
    }
  ]
}

Run audit

Price: 100 API units per request

This request lets you run an audit.

Request parameters
Name Value/Type Description
key* string

The API key for your Semrush account.

* Fields marked by an asterisk (*) are required

Response parameters
Name Value/Type Description
snapshot_id string

The snapshot ID for the 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 campaign

Price: 100 API units per request

This request provides you with a summary of the most recent audit. It includes information on the number of issues found, such as Errors, Warnings, and Notices, as well as the number of checks that passed or failed. Also, it shows the number of pages crawled and the pages yet to be crawled, along with the date of the last audit.

About the Site Audit Issues report ›

Request parameters
Name Value/Type Description
key* string

The API key for your Semrush account.

* Fields marked by an asterisk (*) are required

Response parameters
Name Value/Type Description
id integer

The project ID.

url string

The project URL.

name string

The project name.

status string

The audit status: RUNNING, FINISHED, CHECKING, or SAVING.

errors integer

The number of errors found during the last audit.

warnings integer

The number of warnings found during the last audit.

notices integer

The number of notices found during the last audit.

broken integer

The number of broken pages.

blocked integer

The number of pages blocked from crawling.

redirected integer

The number of redirecting pages.

healthy integer

The number of healthy pages.

haveIssues integer

The number of pages with issues.

haveIssuesDelta integer

The difference in the number of issues found during the previous and last audits.

defects object

The list of issue IDs detected on crawled pages and the number of times each issue was detected.

markups object

The number of markups detected on crawled pages. Supported markups are Twitter Card, Open Graph, Schema.org, and microformats.

depths object

The number of clicks required for SemrushBot to reach the analyzed page from the homepage.

crawlSubdomains boolean

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

true: SemrushBot will crawl the selected domain and its subdomains.

false: SemrushBot will crawl only the selected domain.

respectCrawlDelay boolean

Specifies whether SemrushBot will follow the Crawl-delay directive in robots.txt. Available values:

true: SemrushBot will follow the Crawl-delay directive in robots.txt.

false: SemrushBot will crawl pages with a one-second interval.

user_agent_type integer

The type of user agent. Available values:

0: SemrushBot Desktop

1: SemrushBot Mobile

2: GoogleBot Desktop

3: GoogleBot Mobile

last_audit integer

The date of the last audit.

last_failed_audit integer

The date of the last site audit failure.

next_audit integer

The date of next scheduled audit.

running_pages_crawled integer

The number of pages crawled during the running audit.

running_pages_limit integer

The crawled pages' limit for the running audit.

pages_crawled integer

The number of crawled pages.

pages_limit integer

The The crawled pages' limit.

total_checks integer

The number of total checks made during the last audit.

errors_delta integer

The difference in the number of errors found during the previous and last audits.

warnings_delta integer

The difference in the number of warnings found during the previous and last audits.

notices_delta integer

The difference in the number of notices found during the previous and last audits.

mask_allow array of strings

Masks the Allow directive in the project.

mask_disallow array of strings

Masks the Disallow directive in the project.

removedParameters array of strings

Specifies URL parameters to be excluded from the audit scope.

excluded_checks array of integers

The IDs of issues, such as 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,
  "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 snapshot

Price: 10000 API units per request

This request provides you with an overview of an audit, including the website’s score, issues, and the number of performed checks.

About the Site Audit Issues report ›

Request parameters
Name Value/Type Description
key* string

The API key for your Semrush account.

snapshot_id* string

The snapshot ID.

* Fields marked by an asterisk (*) are required

Response parameters
Name Value/Type Description
quality.value integer

The website's score.

quality.delta integer

The difference in scores a website received during the previous and last audits.

snapshot_id string

The snapshot ID.

pages_crawled integer

The number of crawled pages.

finish_date integer

The date when the last audit finished in the Unix format.

warnings|errors|notices.id integer

The issue ID.

warnings|errors|notices.count integer

The number of found issues.

warnings|errors|notices.delta integer

The difference in the number of issues found during the previous and last audits.

warnings|errors|notices.checks integer

The number of performed checks.

* 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 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.

About the Site Audit Issues report ›

Request parameters
Name Value/Type Description
key* string

The API key for your Semrush account.

* Fields marked by an asterisk (*) are required

Response parameters
Name Value/Type Description
limit integer

The result limit on one page.

page integer

The page number.

total integer

The total number of results per request.

issue_id integer

The issue ID.

target_url string

The target URL. For example, in the case of a broken link issue, the target URL provided will demonstrate a webpage that returns an error status.

page_id string

The page ID.

source_url string

The URL of the webpage on which an error was 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": [
    {
      "target_url": "http://semrush.com/errors/404.html",
      "page_id": "54102d9e0cf2e0c100696c88",
      "source_url": "http://semrush.com"
    }
  ],
  "issue_id": 8
}

Get page ID by 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

The API key for your Semrush account.

url* string

The URL for the search; contains match.

limit integer, default is 10

The data line limit.

* Fields marked by an asterisk (*) are required

Response parameters
Name Value/Type Description
page_id string

The page ID.

total integer

The 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={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 lets you see audit results for a selected period.

Request parameters
Name Value/Type Description
key* string

The API key for your Semrush account.

limit* integer, default is 7

The limit.

offset* integer, default is 0

The offset.

* Fields marked by an asterisk (*) are required

Response parameters
Name Value/Type Description
quality.value integer

The website's score.

quality.delta integer

The difference in scores a website received during the previous and last audits.

snapshot_id string

The snapshot ID.

pages_crawled integer

The number of crawled pages.

finish_date integer

The timestamp in the Unix format showing when the last audit was completed, such as 1410346398040.

warnings|errors|notices.id integer

The issue ID.

warnings|errors|notices.count integer

The number of found issues.

warnings|errors|notices.delta integer

The difference in the number of issues found during the previous and last audits.

warnings|errors|notices.checks integer

The number of performed checks.

* 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
}