Developer
Telephone
United States
+1 (800) 815 - 9959
10:00 AM - 5:00 PM (EST/EDT)
Monday - Friday
Site Audit
Projects
Last updated: March 26, 2024
Last updated: March 26, 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 the site audit tool
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 |
|
| 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
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 |
|
| 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 |
|
| jsRendering | Specifies whether the SemushBot should render JavaScript files during crawling. Available values: |
* 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
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
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
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
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 |
|
| 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
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
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 | ||
| 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 URL
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={url}&limit={limit}&key=YOUR_API_KEY
Response example
{
"data": [
{
"url": "http://semrush.com",
"page_id": "54102d9e0cf2e0c100696c88"
}
],
"total": 178
}
Get information about a page
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
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
}