Before you start, ensure that you have API Key with Instances -> Read permission (or Read and Write if you want to Delete instances)

​
Retrieving Existing Pods

To view a list of active instances, use the Get Pods endpoint.

curl --request GET \
  --url https://api.primeintellect.ai/api/v1/pods/ \
  --header 'Authorization: Bearer your_api_key'

This is a paginated request, with a default limit of 100 results. To adjust the number of results per page, use query parameters:

curl --request GET \
  --url https://api.primeintellect.ai/api/v1/pods/?offset=0&limit=10 \
  --header 'Authorization: Bearer your_api_key'

This will return a JSON object containing the total number of instances (total_count), the specified limit and offset and the list of pods under data (check out Pod schema for details)

{
  "total_count": 15,
  "offset": 0,
  "limit": 10,
  "data": [...]
}

​
Retrieving a Specific Pod

If you know the podId, you can retrieve details for that specific pod:

curl --request GET \
  --url https://api.primeintellect.ai/api/v1/pods/my_pod_id \
  --header 'Authorization: Bearer your_api_key'

​
Checking Pod Status

After provisioning an instance, retrieve its status to obtain port mappings and connection details using the Get Pod Status endpoint. This request also supports checking multiple instance statuses simultaneously:

curl --request GET \
  --url https://api.primeintellect.ai/api/v1/pods/status/?pod_ids=my_first_pod_id&pod_ids=my_second_pod_id \
  --header 'Authorization: Bearer your_api_key'

It returns a data with the list of object like:

{
  "podId": "my_first_pod_id",
  "providerType": "primeconpute",
  "status": "ACTIVE",
  "sshConnection": "root@135.23.125.123 -p 22",
  "costPerHr": 3.52,
  "primePortMapping": [
    {
      "internal": "22",
      "external": "22",
      "protocol": "TCP",
      "usedBy": "SSH",
      "description": ""
    }
  ],
  "ip": "135.23.125.123",
  "installationFailure": null,
  "installationProgress": 100
}

If the instance has additional open ports, these will be listed under primePortMapping.

In case of an error, installationFailure will be set. Our system will attempt automatic retries, but issues related to the image or configuration may require further action.

​
Deleting a Pod

To delete an instance you no longer need, use the Delete Pod endpoint.

curl --request DELETE \
  --url https://api.primeintellect.ai/api/v1/pods/my_pod_id \
  --header 'Authorization: Bearer your_api_key'

Once a pod is terminated, it is moved to history and becomes inaccessible via the standard Get Pod or Get Pods endpoints. To view historical data, use the Get Pods History endpoint.