Projects

The Projects API v4 lets you get information about your folders (formerly called projects) and manage them.

To use Projects API methods, pass your API key in the request header: Authorization: Apikey <YOUR_API_KEY>.

Jump to List ProjectsList Projects

This request returns a list of projects you have access to. Use the scope parameter to narrow results by ownership or sharing scope.

Jump to EndpointEndpoint

GEThttps://api.semrush.com/apis/v4/projects/v1/projects

Request Parameters

scope

Scope of projects to return. Defaults to OWN.

- OWN: Projects owned by the current user. - ALL: All projects accessible to the current user. - SHARED: Projects shared with the current user by another owner. - CORPORATE: Projects available under the current user’s corporate account.

Value/Type: string

limit

Maximum number of projects to return. Defaults to 100, maximum 1000.

Value/Type: integer

offset

Number of projects to skip before returning results. Defaults to 0.

Value/Type: integer

Response Parameters

data

Projects matching the requested scope.

Value/Type: array

meta

Value/Type: object
Request example
curl -L 'https://api.semrush.com/apis/v4/projects/v1/projects?scope=OWN&limit=100&offset=0'
  -H 'Authorization: Apikey YOUR_API_KEY'
Response example
JSON
{
  "meta": {
      "request_id": "182d587194adf5096d1b6d5b309f164f",
      "status_code": 200,
      "success": true,
      "scope": "OWN",
      "limit": 100,
      "offset": 0,
      "total_count": 3
  },
  "data": [
      {
          "project_id": 643526670283248,
          "project_name": "Main website",
          "domain": "example.com",
          "domain_unicode": "example.com",
          "owner_id": 123456780,
          "permissions": {
              "read": true,
              "edit": true,
              "delete": true,
              "share": true,
              "downgraded": false
          },
          "tools": [
              {
                  "name": "site_audit"
              },
              {
                  "name": "position_tracking"
              }
          ]
      },
      {
          "project_id": 643526670283312,
          "project_name": "Competitor research",
          "domain": "competitor.com",
          "domain_unicode": "competitor.com",
          "owner_id": 123456780,
          "permissions": {
              "read": true,
              "edit": true,
              "delete": false,
              "share": false,
              "downgraded": true
          },
          "tools": [
              {
                  "name": "position_tracking"
              }
          ]
      },
      {
          "project_id": 643526670283489,
          "project_name": "Tokyo landing",
          "domain": "xn--r8jz45g.jp",
          "domain_unicode": "例え.jp",
          "owner_id": 987654320,
          "permissions": {
              "read": true,
              "edit": false,
              "delete": false,
              "share": false,
              "downgraded": false
          },
          "tools": []
      }
  ]
}

Jump to Get ProjectGet Project

This request returns the full details of a project you have access to.

Jump to EndpointEndpoint

GEThttps://api.semrush.com/apis/v4/projects/v1/projects/:project_id

Path parameters

project_idRequired

Unique identifier of the project to retrieve. Learn how to get your project ID ›

Value/Type: integer

Response Parameters

data

Requested project.

Value/Type: object

meta

Value/Type: object
Request example
curl -L 'https://api.semrush.com/apis/v4/projects/v1/projects/643526670283248'
  -H 'Authorization: Apikey YOUR_API_KEY'
Response example
JSON
{
  "meta": {
      "request_id": "182d587194adf5096d1b6d5b309f164f",
      "status_code": 200,
      "success": true
  },
  "data": {
      "project_id": 643526670283248,
      "project_name": "My project",
      "domain": "example.com",
      "domain_unicode": "example.com",
      "owner_id": 123456780,
      "permissions": {
          "read": true,
          "edit": true,
          "delete": true,
          "share": true,
          "downgraded": false
      },
      "tools": [
          {
              "name": "site_audit"
          },
          {
              "name": "position_tracking"
          }
      ]
  }
}

Jump to Create ProjectCreate Project

This request creates a new project for a domain you want to track. Returns the created project with its assigned ID.

Jump to EndpointEndpoint

POSThttps://api.semrush.com/apis/v4/projects/v1/projects

Body parameters

domainRequired

Domain of the new project without protocol (e.g. example.com).

Value/Type: string

project_nameRequired

Human-readable name for the new project. You can’t use any of the following symbols: ~, `, !, #, %, ', ^, &, *, =, [, ], \, /, {, }, |, ", :, <, >, ?.

Example: My project

Value/Type: string

Response Parameters

data

The newly created project.

Value/Type: object

meta

Value/Type: object
Request example
curl -L -X POST 'https://api.semrush.com/apis/v4/projects/v1/projects'
  -H 'Authorization: Apikey YOUR_API_KEY'
  -H 'Content-Type: application/json'
  -d '{
    "domain": "example.com",
    "project_name": "My project"
  }'
Response example
JSON
{
  "meta": {
      "request_id": "182d587194adf5096d1b6d5b309f164f",
      "status_code": 201,
      "success": true
  },
  "data": {
      "project_id": 643526670283248,
      "project_name": "My project",
      "domain": "example.com",
      "domain_unicode": "example.com",
      "owner_id": 123456780,
      "permissions": {
          "read": true,
          "edit": true,
          "delete": true,
          "share": true,
          "downgraded": false
      },
      "tools": []
  }
}

Jump to Update ProjectUpdate Project

This request renames a project. Only fields present in the request body are updated. Omitted fields remain unchanged.

Jump to EndpointEndpoint

PATCHhttps://api.semrush.com/apis/v4/projects/v1/projects/:project_id

Path parameters

project_idRequired

Unique identifier of the project to update. Learn how to get your project ID ›

Value/Type: integer

Body parameters

project_name

New name for the project. Omit to leave the current name unchanged.

Example: My website project

Value/Type: string

Response Parameters

data

Updated project.

Value/Type: object

meta

Value/Type: object
Request example
curl -L -X PATCH 'https://api.semrush.com/apis/v4/projects/v1/projects/643526670283248'
  -H 'Authorization: Apikey YOUR_API_KEY'
  -H 'Content-Type: application/json'
  -d '{
    "project_name": "Renamed project"
  }'
Response example
JSON
{
  "meta": {
      "request_id": "182d587194adf5096d1b6d5b309f164f",
      "status_code": 200,
      "success": true
  },
  "data": {
      "project_id": 643526670283248,
      "project_name": "Renamed project",
      "domain": "example.com",
      "domain_unicode": "example.com",
      "owner_id": 123456780,
      "permissions": {
          "read": true,
          "edit": true,
          "delete": true,
          "share": true,
          "downgraded": false
      },
      "tools": [
          {
              "name": "site_audit"
          }
      ]
  }
}

Jump to Delete ProjectDelete Project

This request permanently removes a project and all its associated data.

Jump to EndpointEndpoint

DELETEhttps://api.semrush.com/apis/v4/projects/v1/projects/:project_id

Path parameters

project_idRequired

Unique identifier of the project to delete. Learn how to get your project ID ›

Example: 643526670283248

Value/Type: integer

Response Parameters

data

Value/Type: object

meta

Value/Type: object
Request example
curl -L -X DELETE 'https://api.semrush.com/apis/v4/projects/v1/projects/643526670283248'
  -H 'Authorization: Apikey YOUR_API_KEY'
Response example
JSON
{
  "meta": {
      "request_id": "182d587194adf5096d1b6d5b309f164f",
      "status_code": 200,
      "success": true
  },
  "data": {
      "project_id": 643526670283248
  }
}

Last updated: September 1, 2026

Was this page helpful?