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.
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
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.
Authentication successful
Bad request, client credentials are missing or incorrect.
Unauthorized, client authentication failed.
Internal server error
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
OK
GET /public/v1/clusters HTTP/1.1
Host: api.app.perfectscale.io
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*
OK
{
"data": [
{
"uid": "text",
"name": "text",
"cloud": "aws",
"region": "text",
"createdAt": "2025-10-23T20:41:41.011Z",
"lastTransmittedAt": "2025-10-23T20:41:41.011Z"
}
]
}The period for which carbon emission is calculated
OK
GET /public/v1/clusters/{cluster_uid} HTTP/1.1
Host: api.app.perfectscale.io
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*
OK
{
"data": {
"uid": "text",
"name": "text",
"cloud": "aws",
"region": "text",
"createdAt": "2025-10-23T20:41:41.011Z",
"lastTransmittedAt": "2025-10-23T20:41:41.011Z",
"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
A list of workloads
Cluster not found
Internal server error
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.
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.
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.
Retrieves a list of automation audit log entries within a specified time range, using cursor-based pagination.
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"
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
The maximum number of items to return. Defaults to 1000. Must be between 1 and 5000.
1000An opaque token from the 'next' field in the response's pagination object, used to fetch the next page.
An opaque token from the 'previous' field in the response's pagination object, used to fetch the previous page.
Filter by cluster UIDs. Accepts multiple cluster UIDs to filter the audit logs.
Filter by Kubernetes namespaces. Accepts multiple namespaces to filter the audit logs.
OK
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": "2025-10-23T20:41:41.011Z",
"to": "2025-10-23T20:41:41.011Z",
"page_size": 1000,
"after": "text",
"before": "text",
"cluster_uids": [
"text"
],
"namespaces": [
"text"
]
}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:
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:
OK
No content
NotFound
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.
How to list all cluster UIDs
You can seamlessly list all the clusters' UIDs of the tenant by using the following API:
A list of all clusters
Bad Request
Unauthorized
Internal server error
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"
}
]
}Last updated
Was this helpful?