Overview

Jump to AboutAbout

The Site Audit API v4 lets you set up Site Audit for your projects, run audits, and get their results: audit reports, issues, audited pages, the JavaScript impact report, and the internal linking report.

https://api.semrush.com/apis/v4/site-audit/v1

A Site Audit campaign belongs to a project: its campaign_id is the project ID. Learn how to get your project ID ›

Jump to WorkflowWorkflow

A typical integration goes through these steps:

1. Create a campaign. Call Create Campaign with your project ID and the initial crawl settings: the domain, the page limit, the user agent, the crawl source, and optionally a recurring schedule.
2. Configure the crawl. Adjust the settings with Update Campaign Settings or Patch Campaign Settings. If the campaign crawls a list of URLs, set the list with Update Crawl URLs. If the site is password-protected or blocks bots, add credentials with Update Basic Auth or Update Web Bot Auth.
3. Start an audit. Call Start Audit. The audit runs in the background: the call returns 202 Accepted with the ID of the audit report it will produce.
4. Track progress. Poll Get Audit Progress until stage is FINISHED or ERROR. To end an audit early, use Stop Audit to keep the pages crawled so far, or Abort Audit to discard them.
5. Get the results. After the audit finishes, get the data with the following endpoints:
   • Audit reports and their history: List Audit Reports, Get Audit Report
   • Issues found: List Issue Reports, Get Issue Report
   • Audited pages: List Audited Pages, Get Audited Page, Get Audited Page Issues
   • JavaScript impact: Get JS Impact Changed Pages, Get JS Impact Details
   • Internal linking: Get Linking Report

Issue reports always describe the latest successfully finished audit.

For authorization, the response format, and error messages, refer to the Projects API overview.

Jump to Advanced filteringAdvanced filtering

Endpoints that return lists accept standard query parameters for sorting and pagination. Some of them also accept a filter parameter for cases where the standard parameters aren’t enough, and you need operators such as >, CONTAINS, or logical disjunction such as OR.

The filter parameter is available in List Audited Pages and Get Issue Report. Each endpoint’s filter description lists the fields you can filter by and any field-specific restrictions.

Jump to SyntaxSyntax

The filter parameter uses the following format: Field Operator Value.

?filter=url STARTS_WITH "https://example.com/blog/" AND NOT (title = "" OR title CONTAINS "draft")

Combine conditions with AND, OR, and NOT, and group them with parentheses. URL-encode the filter value when you send the request.

Jump to Supported operatorsSupported operators

• CONTAINS, STARTS_WITH, ENDS_WITH, LIKE, and WORD_MATCH ignore case. =, !=, and IN are case-sensitive.
• LIKE takes a pattern: % matches any sequence of characters, and _ matches a single character. To match %, _, or \ literally, escape them as \%, \_, and \\.
• WORD_MATCH matches a whole word. _ counts as part of a word; -, /, and . don’t.
• To negate an operator, add the NOT_ prefix, for example NOT_IN or NOT_CONTAINS.

Jump to Data typesData types

• Strings: Always wrap in double quotes. To include a double quote in a string, write it twice: "27"" Monitor" stands for 27" Monitor. A backslash is an ordinary character.
• Timestamps: ISO 8601 strings in double quotes, for example "2026-09-01T00:00:00Z".
• Lists: Use parentheses and separate items with commas, for example ("Home", "About us").

Jump to LimitsLimits

A filter expression can contain up to 2,048 characters, 20 conditions, and 100 values in one IN list. If the expression is malformed, exceeds a limit, or uses a field or operator that the endpoint doesn’t support, the API returns 400 Bad Request with an error message that starts with filter: and lists what’s allowed.