CEEMS API (1.0)
Download OpenAPI specification:Download
OpenAPI specification (OAS) for the CEEMS REST API.
See the Interactive Docs to try CEEMS API methods without writing code, and get the complete schema of resources exposed by the API.
If basic auth is enabled, all the endpoints require authentication.
All the endpoints, except health
, swagger
, debug
and demo
,
must send a user-agent header.
Timestamps must be specified in milliseconds, unless otherwise specified.
List clusters
This endpoint will list all the cluster IDs in the CEEMS DB. The
current user is always identified by the header X-Grafana-User
in
the request.
This will list all the cluster IDs in the DB. This is primarily used to verify the CEEMS load balancer's backend IDs that should match with cluster IDs.
Authorizations:
header Parameters
X-Grafana-User required | string Current user name |
Responses
Response samples
- 200
- 401
- 500
{- "data": [
- {
- "id": "string",
- "manager": "string"
}
], - "error": "string",
- "errorType": "",
- "status": "string",
- "warnings": [
- "string"
]
}
Demo Units/Usage endpoints
This endpoint returns sample response for units and usage models. This
endpoint do not require the setting of X-Grafana-User
header as it
only returns mock data for each request. This can be used to introspect
the response models for different resources.
The endpoint requires a path parameter resource
which takes either:
units
which returns a mock units responseusage
which returns a mock usage response.
The mock data is generated randomly for each request and there is no guarantee that the data has logical sense.
path Parameters
resource required | string Enum: "units" "usage" Whether to return mock units or usage data |
Responses
Response samples
- 200
- 500
{- "data": [
- {
- "avg_cpu_mem_usage": {
- "property1": 0,
- "property2": 0
}, - "avg_cpu_usage": {
- "property1": 0,
- "property2": 0
}, - "avg_gpu_mem_usage": {
- "property1": 0,
- "property2": 0
}, - "avg_gpu_usage": {
- "property1": 0,
- "property2": 0
}, - "cluster_id": "string",
- "group": "string",
- "num_units": 0,
- "project": "string",
- "resource_manager": "string",
- "total_cpu_emissions_gms": {
- "property1": 0,
- "property2": 0
}, - "total_cpu_energy_usage_kwh": {
- "property1": 0,
- "property2": 0
}, - "total_gpu_emissions_gms": {
- "property1": 0,
- "property2": 0
}, - "total_gpu_energy_usage_kwh": {
- "property1": 0,
- "property2": 0
}, - "total_ingress_stats": {
- "property1": 0,
- "property2": 0
}, - "total_io_read_stats": {
- "property1": 0,
- "property2": 0
}, - "total_io_write_stats": {
- "property1": 0,
- "property2": 0
}, - "total_outgress_stats": {
- "property1": 0,
- "property2": 0
}, - "total_time_seconds": {
- "property1": 0,
- "property2": 0
}, - "user": "string"
}
], - "error": "string",
- "errorType": "",
- "status": "string",
- "warnings": [
- "string"
]
}
Show project details
This endpoint will show details of the queried project of current user. The
current user is always identified by the header X-Grafana-User
in
the request.
The details include list of users in that project. If current user attempts to query a project that they are not part of, empty response will be returned
Authorizations:
query Parameters
project | Array of strings Project |
cluster_id | Array of strings Cluster ID |
header Parameters
X-Grafana-User required | string Current user name |
Responses
Response samples
- 200
- 401
- 500
{- "data": [
- {
- "cluster_id": "string",
- "name": "string",
- "resource_manager": "string",
- "tags": [
- null
], - "uid": "string",
- "users": [
- null
]
}
], - "error": "string",
- "errorType": "",
- "status": "string",
- "warnings": [
- "string"
]
}
Admin ednpoint to fetch project details
This endpoint will show details of the queried project. The
current user is always identified by the header X-Grafana-User
in
the request.
The user who is making the request must be in the list of admin users configured for the server.
The details include list of users in that project. If current user attempts to query a project that they are not part of, empty response will be returned
Authorizations:
query Parameters
project | Array of strings Project |
cluster_id | Array of strings Cluster ID |
header Parameters
X-Grafana-User required | string Current user name |
Responses
Response samples
- 200
- 401
- 500
{- "data": [
- {
- "cluster_id": "string",
- "name": "string",
- "resource_manager": "string",
- "tags": [
- null
], - "uid": "string",
- "users": [
- null
]
}
], - "error": "string",
- "errorType": "",
- "status": "string",
- "warnings": [
- "string"
]
}
User endpoint for fetching compute units
This user endpoint will fetch compute units of the current user. The
current user is always identified by the header X-Grafana-User
in
the request.
If multiple query parameters are passed, for instance, ?uuid=<uuid>&project=<project>
,
the intersection of query parameters are used to fetch compute units rather than
the union. That means if the compute unit's uuid
does not belong to the queried
project, null response will be returned.
In order to return the running compute units as well, use the query parameter running
.
If to
query parameter is not provided, current time will be used. If from
query parameter is not used, a default query window of 24 hours will be used.
It means if to
is provided, from
will be calculated as to
- 24hrs.
To limit the number of fields in the response, use field
query parameter. By default, all
fields will be included in the response if they are non-empty.
Authorizations:
query Parameters
cluster_id | Array of strings Cluster ID |
uuid | Array of strings Unit UUID |
project | Array of strings Project |
running | boolean Whether to fetch running units |
from | string From timestamp |
to | string To timestamp |
field | Array of strings Fields to return in response |
header Parameters
X-Grafana-User required | string Current user name |
Responses
Response samples
- 200
- 401
- 403
- 500
{- "data": [
- {
- "allocation": { },
- "avg_cpu_mem_usage": {
- "property1": 0,
- "property2": 0
}, - "avg_cpu_usage": {
- "property1": 0,
- "property2": 0
}, - "avg_gpu_mem_usage": {
- "property1": 0,
- "property2": 0
}, - "avg_gpu_usage": {
- "property1": 0,
- "property2": 0
}, - "cluster_id": "string",
- "created_at": "string",
- "created_at_ts": 0,
- "elapsed": "string",
- "ended_at": "string",
- "ended_at_ts": 0,
- "group": "string",
- "name": "string",
- "project": "string",
- "resource_manager": "string",
- "started_at": "string",
- "started_at_ts": 0,
- "state": "string",
- "tags": { },
- "total_cpu_emissions_gms": {
- "property1": 0,
- "property2": 0
}, - "total_cpu_energy_usage_kwh": {
- "property1": 0,
- "property2": 0
}, - "total_gpu_emissions_gms": {
- "property1": 0,
- "property2": 0
}, - "total_gpu_energy_usage_kwh": {
- "property1": 0,
- "property2": 0
}, - "total_ingress_stats": {
- "property1": 0,
- "property2": 0
}, - "total_io_read_stats": {
- "property1": 0,
- "property2": 0
}, - "total_io_write_stats": {
- "property1": 0,
- "property2": 0
}, - "total_outgress_stats": {
- "property1": 0,
- "property2": 0
}, - "total_time_seconds": {
- "property1": 0,
- "property2": 0
}, - "user": "string",
- "uuid": "string"
}
], - "error": "string",
- "errorType": "",
- "status": "string",
- "warnings": [
- "string"
]
}
Admin endpoint for fetching compute units.
This admin endpoint will fetch compute units of any user, compute unit and/or project. The
current user is always identified by the header X-Grafana-User
in
the request.
The user who is making the request must be in the list of admin users configured for the server.
If multiple query parameters are passed, for instance, ?uuid=<uuid>&user=<user>
,
the intersection of query parameters are used to fetch compute units rather than
the union. That means if the compute unit's uuid
does not belong to the queried
user, null response will be returned.
In order to return the running compute units as well, use the query parameter running
.
If to
query parameter is not provided, current time will be used. If from
query parameter is not used, a default query window of 24 hours will be used.
It means if to
is provided, from
will be calculated as to
- 24hrs.
To limit the number of fields in the response, use field
query parameter. By default, all
fields will be included in the response if they are non-empty.
Authorizations:
query Parameters
cluster_id | Array of strings Cluster ID |
uuid | Array of strings Unit UUID |
project | Array of strings Project |
user | Array of strings User name |
running | boolean Whether to fetch running units |
from | string From timestamp |
to | string To timestamp |
field | Array of strings Fields to return in response |
header Parameters
X-Grafana-User required | string Current user name |
Responses
Response samples
- 200
- 401
- 403
- 500
{- "data": [
- {
- "allocation": { },
- "avg_cpu_mem_usage": {
- "property1": 0,
- "property2": 0
}, - "avg_cpu_usage": {
- "property1": 0,
- "property2": 0
}, - "avg_gpu_mem_usage": {
- "property1": 0,
- "property2": 0
}, - "avg_gpu_usage": {
- "property1": 0,
- "property2": 0
}, - "cluster_id": "string",
- "created_at": "string",
- "created_at_ts": 0,
- "elapsed": "string",
- "ended_at": "string",
- "ended_at_ts": 0,
- "group": "string",
- "name": "string",
- "project": "string",
- "resource_manager": "string",
- "started_at": "string",
- "started_at_ts": 0,
- "state": "string",
- "tags": { },
- "total_cpu_emissions_gms": {
- "property1": 0,
- "property2": 0
}, - "total_cpu_energy_usage_kwh": {
- "property1": 0,
- "property2": 0
}, - "total_gpu_emissions_gms": {
- "property1": 0,
- "property2": 0
}, - "total_gpu_energy_usage_kwh": {
- "property1": 0,
- "property2": 0
}, - "total_ingress_stats": {
- "property1": 0,
- "property2": 0
}, - "total_io_read_stats": {
- "property1": 0,
- "property2": 0
}, - "total_io_write_stats": {
- "property1": 0,
- "property2": 0
}, - "total_outgress_stats": {
- "property1": 0,
- "property2": 0
}, - "total_time_seconds": {
- "property1": 0,
- "property2": 0
}, - "user": "string",
- "uuid": "string"
}
], - "error": "string",
- "errorType": "",
- "status": "string",
- "warnings": [
- "string"
]
}
Verify unit ownership
This endpoint will check if the current user is the owner of the
queried UUIDs. The current user is always identified by the header X-Grafana-User
in
the request.
A response of 200 means that the current user is the owner of the queried UUIDs. Any other response code should be treated as the current user not being the owner of the queried units.
The ownership check passes if any of the following conditions are true
:
- If the current user is the direct owner of the compute unit.
- If the current user belongs to the same account/project/namespace as the compute unit. This means the users belonging to the same project can access each others compute units.
The above checks must pass for all the queried units. If the check does not pass for at least one queried unit, a response 403 will be returned.
Any 500 response codes should be treated as failed check as well.
Authorizations:
query Parameters
uuid | Array of strings Unit UUID |
header Parameters
X-Grafana-User required | string Current user name |
Responses
Response samples
- 200
- 401
- 403
- 500
{- "data": [
- null
], - "error": "string",
- "errorType": "",
- "status": "string",
- "warnings": [
- "string"
]
}
Usage statistics
This endpoint will return the usage statistics current user. The
current user is always identified by the header X-Grafana-User
in
the request.
A path parameter mode
is required to return the kind of usage statistics.
Currently, two modes of statistics are supported:
current
: In this mode the usage between two time periods is returned based onfrom
andto
query parameters.global
: In this mode the total usage statistics are returned. For instance, if the retention period of the DB is set to 2 years, usage statistics of last 2 years will be returned.
The statistics can be limited to certain projects by passing project
query,
parameter.
If to
query parameter is not provided, current time will be used. If from
query parameter is not used, a default query window of 24 hours will be used.
It means if to
is provided, from
will be calculated as to
- 24hrs.
To limit the number of fields in the response, use field
query parameter. By default, all
fields will be included in the response if they are non-empty.
Authorizations:
path Parameters
mode required | string Enum: "current" "global" Whether to get usage stats within a period or global |
query Parameters
cluster_id | Array of strings cluster ID |
project | Array of strings Project |
from | string From timestamp |
to | string To timestamp |
field | Array of strings Fields to return in response |
header Parameters
X-Grafana-User required | string Current user name |
Responses
Response samples
- 200
- 401
- 500
{- "data": [
- {
- "avg_cpu_mem_usage": {
- "property1": 0,
- "property2": 0
}, - "avg_cpu_usage": {
- "property1": 0,
- "property2": 0
}, - "avg_gpu_mem_usage": {
- "property1": 0,
- "property2": 0
}, - "avg_gpu_usage": {
- "property1": 0,
- "property2": 0
}, - "cluster_id": "string",
- "group": "string",
- "num_units": 0,
- "project": "string",
- "resource_manager": "string",
- "total_cpu_emissions_gms": {
- "property1": 0,
- "property2": 0
}, - "total_cpu_energy_usage_kwh": {
- "property1": 0,
- "property2": 0
}, - "total_gpu_emissions_gms": {
- "property1": 0,
- "property2": 0
}, - "total_gpu_energy_usage_kwh": {
- "property1": 0,
- "property2": 0
}, - "total_ingress_stats": {
- "property1": 0,
- "property2": 0
}, - "total_io_read_stats": {
- "property1": 0,
- "property2": 0
}, - "total_io_write_stats": {
- "property1": 0,
- "property2": 0
}, - "total_outgress_stats": {
- "property1": 0,
- "property2": 0
}, - "total_time_seconds": {
- "property1": 0,
- "property2": 0
}, - "user": "string"
}
], - "error": "string",
- "errorType": "",
- "status": "string",
- "warnings": [
- "string"
]
}
Admin Usage statistics
This admin endpoint will return the usage statistics of queried user. The
current user is always identified by the header X-Grafana-User
in
the request.
The user who is making the request must be in the list of admin users configured for the server.
A path parameter mode
is required to return the kind of usage statistics.
Currently, two modes of statistics are supported:
current
: In this mode the usage between two time periods is returned based onfrom
andto
query parameters.global
: In this mode the total usage statistics are returned. For instance, if the retention period of the DB is set to 2 years, usage statistics of last 2 years will be returned.
The statistics can be limited to certain projects by passing project
query,
parameter.
If to
query parameter is not provided, current time will be used. If from
query parameter is not used, a default query window of 24 hours will be used.
It means if to
is provided, from
will be calculated as to
- 24hrs.
To limit the number of fields in the response, use field
query parameter. By default, all
fields will be included in the response if they are non-empty.
Authorizations:
path Parameters
mode required | string Enum: "current" "global" Whether to get usage stats within a period or global |
query Parameters
cluster_id | Array of strings cluster ID |
project | Array of strings Project |
from | string From timestamp |
to | string To timestamp |
field | Array of strings Fields to return in response |
header Parameters
X-Grafana-User required | string Current user name |
Responses
Response samples
- 200
- 401
- 403
- 500
{- "data": [
- {
- "avg_cpu_mem_usage": {
- "property1": 0,
- "property2": 0
}, - "avg_cpu_usage": {
- "property1": 0,
- "property2": 0
}, - "avg_gpu_mem_usage": {
- "property1": 0,
- "property2": 0
}, - "avg_gpu_usage": {
- "property1": 0,
- "property2": 0
}, - "cluster_id": "string",
- "group": "string",
- "num_units": 0,
- "project": "string",
- "resource_manager": "string",
- "total_cpu_emissions_gms": {
- "property1": 0,
- "property2": 0
}, - "total_cpu_energy_usage_kwh": {
- "property1": 0,
- "property2": 0
}, - "total_gpu_emissions_gms": {
- "property1": 0,
- "property2": 0
}, - "total_gpu_energy_usage_kwh": {
- "property1": 0,
- "property2": 0
}, - "total_ingress_stats": {
- "property1": 0,
- "property2": 0
}, - "total_io_read_stats": {
- "property1": 0,
- "property2": 0
}, - "total_io_write_stats": {
- "property1": 0,
- "property2": 0
}, - "total_outgress_stats": {
- "property1": 0,
- "property2": 0
}, - "total_time_seconds": {
- "property1": 0,
- "property2": 0
}, - "user": "string"
}
], - "error": "string",
- "errorType": "",
- "status": "string",
- "warnings": [
- "string"
]
}
Show user details
This endpoint will show details of the current user. The
current user is always identified by the header X-Grafana-User
in
the request.
The details include list of projects that user is currently a part of.
Authorizations:
query Parameters
cluster_id | Array of strings Cluster ID |
header Parameters
X-Grafana-User required | string Current user name |
Responses
Response samples
- 200
- 401
- 500
{- "data": [
- {
- "cluster_id": "string",
- "name": "string",
- "projects": [
- null
], - "resource_manager": "string",
- "tags": [
- null
], - "uid": "string"
}
], - "error": "string",
- "errorType": "",
- "status": "string",
- "warnings": [
- "string"
]
}
Admin endpoint for fetching user details of _any_ user.
This endpoint will show details of the queried user(s). The
current user is always identified by the header X-Grafana-User
in
the request.
The user who is making the request must be in the list of admin users configured for the server.
The details include list of projects that user is currently a part of.
Authorizations:
query Parameters
user | Array of strings User name |
cluster_id | Array of strings Cluster ID |
header Parameters
X-Grafana-User required | string Current user name |
Responses
Response samples
- 200
- 401
- 500
{- "data": [
- {
- "cluster_id": "string",
- "name": "string",
- "projects": [
- null
], - "resource_manager": "string",
- "tags": [
- null
], - "uid": "string"
}
], - "error": "string",
- "errorType": "",
- "status": "string",
- "warnings": [
- "string"
]
}