Overview

Jump to AboutAbout

Projects API includes several endpoint groups:

  • Projects API accessible via an API key and using OAuth 2.0 lets you get information about your folders (formerly called projects) and manage them.
  • Position Tracking API lets you monitor keyword rankings, visibility, and competitors’ performance across search engines and locations. It provides access to ranking data for specific keywords, devices, and regions.
  • Site Audit API lets you automatically crawl websites, identify technical SEO issues, and retrieve structured reports about site health and performance. With this API, you can run new audits, monitor ongoing crawl progress, and access detailed reports on errors, warnings, and notices.

Jump to Get accessGet access

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

Jump to AuthorizationAuthorization

Different Projects API endpoints require different authorization methods:

Jump to ResponseResponse

Result
Code
Success
HTTP 200
Error
HTTP 400

All endpoints in the Projects API return responses in JSON format.

Jump to Error messagesError messages

The Projects (API key), Position Tracking, and Site Audit APIs return error messages in the following format:

Error message format
JSON
{
  "code": "{ERROR_CODE}",
  "message": "{ERROR_MESSAGE}"
}
ERROR_CODE
ERROR_MESSAGE
integer
string
Machine-parseable codes.
Descriptive error text.

In addition to a descriptive error text, error messages contain machine-parsable codes. While the text for an error message may change, the codes will stay the same.

Error code
Error message
Recommended action
70
API key hash failure
Double-check that your API key is correct and valid.
120
Wrong key-ID pair
Check that the API key is correct. You can find your key in the Subscription info section.
121
Wrong format or empty hash
Check that the API key is correct. You can find your key in the Subscription info section.
122
Wrong format or empty key
Check that the API key is correct. You can find your key in the Subscription info section.
130
API disabled
Upgrade your subscription plan to get access to the API.
131
Limit exceeded
The API request limit for the requested report has been reached. Contact the Semrush Support Team.
132
API units balance is zero
You have used all your API units. To continue using the API, recharge your API unit balance or upgrade your subscription.
134
Total limit exceeded
The total API request limit has been reached. Contact the Semrush Support Team.
511
Unknown error
Contact the Semrush Support Team and provide them with your API request.
512
Can’t find project with project_id {ID}
Check that the project ID is correct.
513
Invalid ‘tool_id’
Check that the tool ID is correct.
515
Campaign already exists
A campaign with the same parameters already exists. Create a new one.
519
Missing mandatory URL parameter
Check that you have added all the required parameters in the request URL.
520
Invalid tag name
Check that the tag name is correct.
521
Projects limit exceed, projects created: {projects_count}, user limit are {projects_limit}
You have reached the limit of projects for your account. To create a new project, delete an existing one.
522
Keywords limit exceed, keywords limit {keywords_limit} already tracked keywords {keywords_count}
You have reached the limit of keywords for your account. To add new keywords, buy more keywords or remove some of the existing ones.

The Projects API (OAuth 2.0) uses HTTP status codes, like the Local API.

Jump to Project and campaign IDsProject and campaign IDs

To make requests using the Projects, Position Tracking, and Site Audit API methods, you need to get your project and campaign IDs.

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 your campaign IDGet your campaign ID

  1. Open your campaign using the Position Tracking tool.
  2. Check the page URL displayed in your browser’s address bar. It’ll look as follows: https://www.semrush.com/tracking/landscape/6647718_272401.html?domain_1=wikipedia.org
  3. The number before the underscore represents the project ID. In this example, it’s 6647718. The full number including the underscore is the campaign ID. In this example, it’s 6647718_272401. Copy these numbers and save them for future requests.

Jump to Get multiple project and campaign IDsGet multiple project and campaign IDs

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

To find the IDs for multiple campaigns within a project, use the Get a list of campaigns request specifying the project ID you need.

Last updated: March 10, 2026

Was this page helpful?