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.
Exclusive Access
Rate Limiting
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:
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) andclient_secret(Secret Key).
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.
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
Endpoints
Authentication Endpoint
This endpoint allows clients to authenticate using their client credentials.
The client identifier issued to the client during the registration process.
The client secret issued to the client during the registration process.
POST /public/v1/auth/public_auth HTTP/1.1
Host: api.app.perfectscale.io
Authorization: Bearer JWT
Content-Type: application/json
Accept: */*
Content-Length: 43
{
"client_id": "text",
"client_secret": "text"
}{
"access_token": "text",
"expires_in": 1
}Clusters Endpoint
GET /public/v1/clusters HTTP/1.1
Host: api.app.perfectscale.io
Authorization: Bearer JWT
Accept: */*
OK
{
"data": [
{
"uid": "text",
"name": "text",
"cloud": "aws",
"region": "text",
"createdAt": "2025-07-12T05:42:43.333Z",
"lastTransmittedAt": "2025-07-12T05:42:43.333Z"
}
]
}The period for which carbon emission is calculated
GET /public/v1/clusters/{cluster_uid} HTTP/1.1
Host: api.app.perfectscale.io
Authorization: Bearer JWT
Accept: */*
OK
{
"data": {
"uid": "text",
"name": "text",
"cloud": "aws",
"region": "text",
"createdAt": "2025-07-12T05:42:43.333Z",
"lastTransmittedAt": "2025-07-12T05:42:43.333Z",
"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.
The unique identifier for the cluster
GET /public/v1/clusters/{cluster_uid}/workloads HTTP/1.1
Host: api.app.perfectscale.io
Authorization: Bearer JWT
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.
Get cluster_uid directly from PerfectScale UI:
Go to the
OverviewtabClick the three-dot button located next to the needed cluster
Get cluster UID Click the
Copy Cluster UIDbutton -> now, your cluster_uid is copied.
Cluster UID copied
Get cluster_uid with the following command:
kubectl get namespace kube-system -o=jsonpath='{.metadata.uid}'Get the full list of clusters via API and extract cluster_uids from it.
Deleting an API Token
In certain situations, you may find it necessary to delete an API token.
Follow these easy steps:
Click on the
Profilebutton in the bottom left corner and selectOrganization Settings.In the pop-up window, navigate to the
API Tokenstab.Click the hamburger on the right-hand side, select
Delete API Token, and click theDeletebutton.
Deleting a cluster
There may be situations where you need to remove a cluster from PerfectScale. You can seamlessly delete a cluster using Public API:
DELETE /public/v1/clusters/{cluster_uid} HTTP/1.1
Host: api.app.perfectscale.io
Authorization: Bearer JWT
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.
How to list all cluster UIDs
You can seamlessly list all the clusters' UIDs of the tenant by using the following API:
GET /public/v1/clusters HTTP/1.1
Host: api.app.perfectscale.io
Authorization: Bearer JWT
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"
}
]
}Last updated