Site Audit

Projects

Last updated: April 30, 2024

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}

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

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
}

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
}

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

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"
    }
  ]
}

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 (POST)

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

Response example

{
  "snapshot_id": "54102d92e4b0f889a040c9c8"
}

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
}

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
}

Price: 100 API units per request info

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
}

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
}

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

Price: 10000 API units per request info

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
}

Site Audit

Basic doc

About Site audit API

Filters

Issue IDs

Enable Site Audit tool

Request parameters

Edit campaign

Request parameters

Get list of campaign snapshots

Request parameters

Response parameters

Get text descriptions about issues

Request parameters

Response parameters

Run audit

Request parameters

Response parameters

Get information about campaign

Request parameters

Response parameters

Get information about snapshot

Request parameters

Response parameters

Detailed report for issue

Request parameters

Response parameters

Get page ID by URL

Request parameters

Response parameters

Get information about a page

Request parameters

Response parameters

Get snaphots history

Request parameters

Response parameters