Telephone
United States
+1 (800) 815 - 9959
10:00 AM - 5:00 PM (EST/EDT)
Monday - Friday
Need help?
Telephone
United States
+1 (800) 815 - 9959
10:00 AM - 5:00 PM (EST/EDT)
Monday - Friday
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
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 |
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.
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 |
notify | boolean | Specifies whether an email notification is sent after the audit is completed. |
allow | array of strings | Masks the |
disallow | array of strings | Masks the |
pageLimit* | integer | The number of crawled pages. |
userAgentType | integer | The type of user agent. Available values:
|
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:
|
respectCrawlDelay | boolean | Specifies whether SemrushBot will follow the
|
* Fields marked by an asterisk (*) are required
Endpoint (POST)
Request example
{ "domain": "www.mysite.com", "scheduleDay": 1, "notify": false, "allow": [ "", "", "" ], "disallow": [ "", "", "" ], "pageLimit": 1000, "userAgentType": 2, "removedParameters": [ "", "", "" ], "crawlSubdomains": true, "respectCrawlDelay": false }
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.
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 |
notify | boolean | Specifies whether an email notification is sent after the audit is completed. |
allow | array of strings | Masks the |
disallow | array of strings | Masks the |
pageLimit* | integer | The number of crawled pages. |
userAgentType | integer | The type of user agent. Available values:
|
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:
|
respectCrawlDelay | boolean | Specifies whether SemrushBot will follow the
|
jsRendering | string | Specifies whether SemrushBot will render JavaScript files during crawling. Available values:
|
* Fields marked by an asterisk (*) are required
Endpoint (POST)
Request example
{ "domain": "www.mysite.com", "scheduleDay": 1, "notify": false, "allow": [ "", "", "" ], "disallow": [ "", "", "" ], "pageLimit": 1000, "userAgentType": 2, "removedParameters": [ "", "", "" ], "crawlSubdomains": true, "respectCrawlDelay": false }
This request lets you get a list of previous audit IDs along with their completion dates.
Name | Value/Type | Description |
---|---|---|
key* | string | The API key for your Semrush account. |
* Fields marked by an asterisk (*) are required
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 |
* Fields marked by an asterisk (*) are required
Endpoint (GET)
Response example
{ "snapshots": [ { "snapshot_id": "540d9e420cf2e0c1006966e3", "finish_date": 1410178856809 }, { "snapshot_id": "54102bd20cf2e0c100696a10", "finish_date": 1410345954754 } ] }
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.
Name | Value/Type | Description |
---|---|---|
key* | string | The API key for your Semrush account. |
* Fields marked by an asterisk (*) are required
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)
Response example
{ "issues": [ { "id": 14, "title": "Broken external images", "title_page": "##count## external images are broken", "url_column": "Image URL", "info_column": "HTTP Code" } ] }
This request lets you run an audit.
Name | Value/Type | Description |
---|---|---|
key* | string | The API key for your Semrush account. |
* Fields marked by an asterisk (*) are required
Name | Value/Type | Description |
---|---|---|
snapshot_id | string | The snapshot ID for the audit. |
* Fields marked by an asterisk (*) are required
Endpoint (POST)
Response example
{ "snapshot_id": "54102d92e4b0f889a040c9c8" }
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.
Name | Value/Type | Description |
---|---|---|
key* | string | The API key for your Semrush account. |
* Fields marked by an asterisk (*) are required
Name | Value/Type | Description |
---|---|---|
id | integer | The project ID. |
url | string | The project URL. |
name | string | The project name. |
status | string | The audit status: |
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:
|
respectCrawlDelay | boolean | Specifies whether SemrushBot will follow the
|
user_agent_type | integer | The type of user agent. Available values:
|
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 |
mask_disallow | array of strings | Masks the |
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)
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 }
This request provides you with an overview of an audit, including the website’s score, issues, and the number of performed checks.
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
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)
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 }
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.
Name | Value/Type | Description |
---|---|---|
key* | string | The API key for your Semrush account. |
* Fields marked by an asterisk (*) are required
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)
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 }
This request helps you get an ID of a crawled page.
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
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)
Response example
{ "data": [ { "url": "http://semrush.com", "page_id": "54102d9e0cf2e0c100696c88" } ], "total": 178 }
This request allows you to get information about a page, and to get a list of its issues.
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
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)
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" }
Alternative price:
10000 API units
by one snapshot
This request lets you see audit results for a selected period.
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
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 |
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)
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 }