Public API

Learn how to programmatically interact with PerfectScale, enabling automation, data retrieval, and integration with your existing workflows

The API is exclusively available for our paying customers, allowing them to interact with the platform programmatically. Check the following information to get acquainted with the PerfectScale rate-limiting policy and authentication process. To explore the API, use the attached Swagger documentation.

The PerfectScale public API is a premium feature available only with our EXPERT package for PerfectScale’s paying customers. Contact [email protected] to learn more about how to gain access to this feature.

PerfectScale API implements a rate-limiting policy to ensure fair usage and maintain the quality of service. The rate limit is set at 10 requests per minute per client.

Authentication

To interact with the PerfectScale API, a token is required. To get the token, follow the steps below:

1. Retrieve Client Credentials:

   • Go to https://app.perfectscale.io.

   • Click on your user avatar located at the bottom left corner of the page.

   • Select Organization Settings from the menu.

   • In the pop-up window, navigate to the API Tokens tab.

   • Click on Generate Token.

   • Assign a Read Only Role to the new token.

   • Upon creation, you will be provided with a client_id (Client ID) and client_secret (Secret Key).

2. Obtain Access Token:

   • Make a POST request to the Authentication Endpoint with the following payload:

   {
     "client_id": "your_client_id",
     "client_secret": "your_client_secret"
   }

   • The API will respond with a token payload, which will contain your access token.

3. Access Other Endpoints:

   • With the obtained access token, you can make authorized requests to other endpoints of the PerfectScale API. Include the token in the Authorization header of your HTTP requests as follows:

   Authorization: Bearer your_access_token

Authentication Endpoint

Public authentication for clients

post

This endpoint allows clients to authenticate using their client credentials.

Authorizations

auth

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Body

application/json

client_idstringRequired

The client identifier issued to the client during the registration process.

client_secretstringRequired

The client secret issued to the client during the registration process.

Responses

200

Authentication successful

application/json

400

Bad request, client credentials are missing or incorrect.

401

Unauthorized, client authentication failed.

500

Internal server error

post

/auth/public_auth

HTTPcURLJavaScriptPython

POST /public/v1/auth/public_auth HTTP/1.1
Host: api.app.perfectscale.io
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 43

{
  "client_id": "text",
  "client_secret": "text"
}

{
  "access_token": "text",
  "expires_in": 1
}

Clusters Endpoint

get

Authorizations

auth

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Responses

200

OK

application/json

get

/clusters

HTTPcURLJavaScriptPython

GET /public/v1/clusters HTTP/1.1
Host: api.app.perfectscale.io
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

200

OK

{
  "data": [
    {
      "uid": "text",
      "name": "text",
      "cloud": "aws",
      "region": "text",
      "createdAt": "2026-01-24T09:24:24.314Z",
      "lastTransmittedAt": "2026-01-24T09:24:24.314Z"
    }
  ]
}

get

Authorizations

auth

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Path parameters

cluster_uidstringRequired

Query parameters

periodstringOptional

The period for which carbon emission is calculated

Responses

200

OK

application/json

get

/clusters/{cluster_uid}

HTTPcURLJavaScriptPython

GET /public/v1/clusters/{cluster_uid} HTTP/1.1
Host: api.app.perfectscale.io
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

200

OK

{
  "data": {
    "uid": "text",
    "name": "text",
    "cloud": "aws",
    "region": "text",
    "createdAt": "2026-01-24T09:24:24.314Z",
    "lastTransmittedAt": "2026-01-24T09:24:24.314Z",
    "emission": {
      "ANY_ADDITIONAL_PROPERTY": 1
    }
  }
}

Workloads Endpoint

Ensure that the following request includes the cluster_uid parameter, as it is mandatory. Follow the instructions provided in order to obtain this value.

List all workloads in a specified cluster

get

Authorizations

auth

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Path parameters

cluster_uidstringRequired

The unique identifier for the cluster

Responses

200

A list of workloads

application/json

404

Cluster not found

500

Internal server error

get

/clusters/{cluster_uid}/workloads

HTTPcURLJavaScriptPython

GET /public/v1/clusters/{cluster_uid}/workloads HTTP/1.1
Host: api.app.perfectscale.io
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

{
  "meta": {
    "count": 10
  },
  "data": [
    {
      "id": "examplenamespace-deployment-example-test-workload",
      "name": "example-test-workload",
      "type": "Deployment",
      "namespace": "examplenamespace",
      "firstSeen": "2023-04-08T16:51:08Z",
      "lastSeen": "2023-10-22T15:23:22.9Z",
      "runningMinutes": 40265,
      "replicasCounts": {
        "maxCount": 3,
        "avgCount": 2
      },
      "resilienceLevel": "medium",
      "muteStatus": {
        "isMuted": false,
        "expires": null
      },
      "costAnalysis": {
        "past30Days": {
          "totalCost": 1.2111549136128001,
          "wastedCost": 0.370918634267412,
          "costPerHour": 0.370918634267412
        },
        "next30Days": {
          "costIncrease": 1.2111549136128001,
          "potentialSavings": 0.370918634267412
        }
      },
      "workloadLabels": {
        "ANY_ADDITIONAL_PROPERTY": "text"
      },
      "indicators": [
        {
          "name": "OverProvisionedMemRequest",
          "type": "waste",
          "severityLevel": 1
        }
      ],
      "containers": [
        {
          "name": "container-example-name",
          "runningMinutes": 40265,
          "indicators": [
            {
              "name": "OverProvisionedMemRequest",
              "type": "waste",
              "severityLevel": 1
            }
          ],
          "resources": {
            "current": {
              "memoryRequestMiB": 128,
              "memoryLimitMiB": 256,
              "cpuRequestCores": 128,
              "cpuLimitCores": 256
            },
            "recommended": {
              "memoryRequestMiB": 128,
              "memoryLimitMiB": 256,
              "cpuRequestCores": 128,
              "cpuLimitCores": 256
            }
          },
          "usage": {
            "cpuCores": {
              "p90": 0.0015262789745040441,
              "p95": 0.0015262789745040441,
              "p100": 0.07069631706099244
            },
            "memoryMiB": {
              "p90": 0.0015262789745040441,
              "p95": 0.0015262789745040441,
              "p100": 0.07069631706099244
            }
          }
        }
      ]
    }
  ]
}

How to get cluster_uid

There are two options available to obtain the cluster_uid.

1. Get cluster_uid directly from PerfectScale UI:

   • Go to the Overview tab

   • Click the three-dot button located next to the needed cluster

     

     Get cluster UID
   • Click the Copy Cluster UID button -> now, your cluster_uid is copied.

     

     Cluster UID copied
2. Get cluster_uid with the following command:

kubectl get namespace kube-system -o=jsonpath='{.metadata.uid}'

1. Get the full list of clusters via API and extract cluster_uids from it.

Automation Audit Log Endpoint

The Automation Audit Log provides visibility into all actions performed by PerfectScale automation. This endpoint allows teams to programmatically access, retrieve, and filter audit logs and seamlessly integrate them into their existing systems or tools.

The Automation Audit Log shows data from the last 30 days.

Get Automation Audit Logs with Cursor Pagination

post

Retrieves a list of automation audit log entries within a specified time range, using cursor-based pagination.

Authorizations

auth

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Body

application/json

fromstring · date-timeOptional

The start of the time range in ISO 8601 format with UTC timezone (e.g., "2025-09-17T00:00:00Z"). If omitted, defaults to 00:00:00 UTC of the day that is 30 days ago from today.

Constraints:

• Must be in UTC timezone (ends with 'Z' or has '+00:00' offset)
• Cannot be in the future
• Cannot be before 00:00:00 UTC of 30 days ago from today
• Must be before 'to' date when both are provided
• Must be different from 'to' date

Example: If today is 2025-10-17, the earliest allowed value is "2025-09-17T00:00:00Z"

tostring · date-timeOptional

The end of the time range in ISO 8601 format with UTC timezone (e.g., "2025-10-17T23:59:59Z"). If omitted, defaults to the current time in UTC.

Constraints:

• Must be in UTC timezone (ends with 'Z' or has '+00:00' offset)
• Cannot be in the future
• Must be after 'from' date when both are provided
• Must be different from 'from' date

page_sizeinteger · min: 1 · max: 5000Optional

The maximum number of items to return. Defaults to 1000. Must be between 1 and 5000.

Default: 1000

afterstringOptional

An opaque token from the 'next' field in the response's pagination object, used to fetch the next page.

beforestringOptional

An opaque token from the 'previous' field in the response's pagination object, used to fetch the previous page.

cluster_uidsstring[]Optional

Filter by cluster UIDs. Accepts multiple cluster UIDs to filter the audit logs.

namespacesstring[]Optional

Filter by Kubernetes namespaces. Accepts multiple namespaces to filter the audit logs.

Responses

200

OK

application/json

post

/automation/audit_logs

HTTPcURLJavaScriptPython

POST /public/v1/automation/audit_logs HTTP/1.1
Host: api.app.perfectscale.io
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 161

{
  "from": "2026-01-24T09:24:24.314Z",
  "to": "2026-01-24T09:24:24.314Z",
  "page_size": 1000,
  "after": "text",
  "before": "text",
  "cluster_uids": [
    "text"
  ],
  "namespaces": [
    "text"
  ]
}

200

OK

{
  "data": [
    {
      "started_at": "2024-03-08T12:00:00Z",
      "cluster_name": "cluster-1",
      "cluster_uid": "cluster_1",
      "workload_id": "workload_1",
      "workload_name": "workload-1",
      "workload_type": "deployment",
      "namespace": "default",
      "labels": {
        "ANY_ADDITIONAL_PROPERTY": "value"
      },
      "container": {
        "name": "test_name_1",
        "cpu": {
          "cpuCoresRequest": 2,
          "recommendCpuCoresRequest": 2,
          "cpuCoresLimits": 3,
          "recommendCpuCoresLimits": 5,
          "cpuRequestImpact": 3,
          "cpuLimitImpact": 3,
          "cpuRequestChangePercent": 50,
          "cpuLimitChangePercent": 50,
          "cpuRequestChangeAbsolute": 3,
          "cpuLimitChangeAbsolute": 3
        },
        "memory": {
          "memMiBRequest": 2,
          "recommendMemMiBRequest": 2,
          "memMiBLimits": 3,
          "recommendMemMiBLimits": 3,
          "memMiBRequestImpact": 3,
          "memMiBLimitImpact": 3,
          "memRequestChangePercent": 50,
          "memLimitChangePercent": 50,
          "memMiBRequestChangeAbsolute": 3,
          "memMiBLimitChangeAbsolute": 3
        }
      }
    }
  ],
  "meta": {
    "pagination": {
      "has_next": true,
      "next": "text",
      "has_prev": true,
      "prev": "text",
      "page_size": 1
    }
  }
}

Deleting an API Token

In certain situations, you may find it necessary to delete an API token.

Follow these easy steps:

1. Click on the Profile button in the bottom left corner and select Organization Settings.

2. In the pop-up window, navigate to the API Tokens tab.

3. Click the hamburger on the right-hand side, select Delete API Token, and click the Delete button.

Delete API token

Deleting a cluster

The endpoint removes the cluster from PerfectScale without deleting the cluster itself.

There may be situations where you need to remove a cluster from PerfectScale. You can seamlessly delete a cluster using Public API:

delete

Authorizations

auth

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Path parameters

cluster_uidstringRequired

Responses

200

OK

No content

404

NotFound

delete

/clusters/{cluster_uid}

HTTPcURLJavaScriptPython

DELETE /public/v1/clusters/{cluster_uid} HTTP/1.1
Host: api.app.perfectscale.io
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

No content

How to get cluster UID

To get a cluster UID with a few clicks, navigate to the Overview tab, hover over the needed cluster, and click the three dots button. Then click Copy Cluster UID so that it will be automatically copied to the clipboard.

Get cluster UID

How to list all cluster UIDs

You can seamlessly list all the clusters' UIDs of the tenant by using the following API:

List all clusters for a tenant

get

Authorizations

auth

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Responses

200

A list of all clusters

application/json

400

Bad Request

401

Unauthorized

500

Internal server error

get

/clusters

HTTPcURLJavaScriptPython

GET /public/v1/clusters HTTP/1.1
Host: api.app.perfectscale.io
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

{
  "data": [
    {
      "cloud": "aws",
      "createdAt": "2023-04-10T16:29:16.257006Z",
      "lastTransmittedAt": "2024-06-27T18:14:31.033028Z",
      "name": "amazing-app1",
      "region": "us-east-1",
      "uid": "e6fa8a83-644a-457d-99ad-2887ead9346c"
    },
    {
      "cloud": "azure",
      "createdAt": "2023-05-07T12:13:19.440393Z",
      "lastTransmittedAt": "2024-06-27T18:13:47.909722Z",
      "name": "amazing-app2",
      "region": "West Europe",
      "uid": "561d0f72-ed93-4386-b6af-dc41973fc2ab"
    }
  ]
}