Developer
Telephone
United States
+1 (800) 815 - 9959
10:00 AM - 5:00 PM (EST/EDT)
Monday - Friday
Site Audit
Projects
Last updated: August 18, 2021
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
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 |
* 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 | 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
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
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
}