Get started API units balance

Need help? dropdown button

contacts

Telephone

United States

dropdown button

United States

Canada

United Kingdom

Spain

France

Italy

Germany

Australia

+1 (800) 815 - 9959

10:00 AM - 5:00 PM (EST/EDT)

Monday - Friday

mobile-menu

Basic docs

Projects divider Last updated: August 18, 2021

About

Projects API allows users to create, edit and manage projects that use The Site Audit and Position Tracking tools. By using Projects API, you can track your web rivals’ and your own keyword rankings, discover local competitors, and fix websites’ on-page issues from one location, and much more.

Auth

All API requests use such HTTP methods such as POST, PUT, GET or DELETE with JSON parameters and must contain your API Key. You can find info how to get your in How to get API documentation.

If you sent an API call example, replace your key with a placeholder (e.g. https://api.semrush.com/?key=<key>).

Your API key also gives an access to your API units balance, so please don’t share it publicly.

Exposing your credentials can result in your account being compromised, which leads to unexpected charges.

Response

Result Code
Success HTTP 200
Error HTTP 400

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

Error messages

Projects API error messages are returned in a specific format:

{ "code": "{ERROR_CODE}", "message": "{ERROR_MESSAGE}" }

ERROR_CODE integer Machine-parseable codes.
ERROR_MESSAGE string Descriptive error text.

In addition to 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.
Show all

Project 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.

Get 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.

Get 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 number following the underscore is the campaign ID. In this example, it's 272401. Copy these numbers and save them for future requests.
Project and campaign IDs in the address bar

Get 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.