Projects

The Projects API 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: July 22, 2026

Was this page helpful?