Overview

Jump to AboutAbout

Projects API includes several endpoint groups:

  • Projects API lets you get information about your projects and manage them. A project acts as a workspace for a specific website or client, where you access the related tools and data in one place.
  • Site Audit API lets you set up Site Audit for your projects, run audits, and get their results: issues, audited pages, and site-wide reports.

Jump to Get accessGet access

To use the Projects and Site Audit APIs, you must have the SEO Business subscription and available API units. Learn more about the Standard API ›

Jump to AuthorizationAuthorization

Projects and Site Audit APIs in Version 4 require a Version 4 API key which is assigned to each user after subscribing to Semrush.

You’ll find your API key in the API keys section of your Semrush profile. If your API key is unavailable there, refer to API access.

Jump to Response formatResponse format

The Projects and Site Audit APIs return a JSON object with a top-level meta object followed by either a data object or an error object, but not both.

Key
Type
Description
success
boolean
Whether the request succeeded.
status_code
integer
HTTP status code.
request_id
string
Unique ID of the request. Include it when contacting Semrush Customer Support.

Endpoints that return lists also add pagination fields to meta, such as limit, offset, and total_count, and echo the sorting and filtering parameters applied.

Jump to Error messagesError messages

When a request fails, the Projects and Site Audit APIs return a structured error response: the meta object with success set to false, followed by an error object.

Error response example
JSON
{
  "meta": {
    "success": false,
    "status_code": 403,
    "request_id": "a29952029c10a47e5876d86256e59455"
  },
  "error": {
    "code": 403,
    "message": "Forbidden",
    "retryable": false,
    "details": []
  }
}

Jump to Error fieldsError fields

Field
Description
error.code
Error code. Usually matches the HTTP status code.
error.message
Error description.
error.retryable
Indicates whether retrying the same request may succeed.
error.details
Optional error-specific details, such as the request field that caused the error.

Jump to HTTP status codesHTTP status codes

HTTP code
Description
400 Bad Request
The request contains invalid parameters or can’t be processed in the resource’s current state.
401 Unauthorized
Authentication failed or credentials are missing.
403 Forbidden
The authenticated user doesn’t have permission to perform the operation.
404 Not Found
The requested resource, such as a project, campaign, or audit report, wasn’t found.
409 Conflict
The request conflicts with the current state of the resource.
429 Too Many Requests
The request rate is too high.
499 Client Closed Request
The client closed the connection before the request completed.
500 Internal Server Error
An unexpected server error occurred.
501 Not Implemented
The requested operation isn’t implemented.
503 Service Unavailable
The service is temporarily unavailable.
504 Gateway Timeout
The request timed out while waiting for a backend service.

Jump to Project IDProject ID

To make requests using the Projects and Site Audit methods, you need to get your project ID. In the Site Audit API, the project ID is passed as campaign_id.

Jump to Get your project IDGet your project ID

  1. Navigate the main Projects page and select the required project.
  2. Check the page URL displayed in your browser’s address bar. It’ll look as follows: https://www.semrush.com/projects/6647718
  3. The number after projects is your project ID. In this example, it’s 6647718. Copy and save it for future requests.

Jump to Get multiple project IDsGet multiple project IDs

You can use the List Projects request that returns a list of all your projects, including their IDs and basic information.

Last updated: November 13, 2026

Was this page helpful?