> ## Documentation Index
> Fetch the complete documentation index at: https://docs.primeintellect.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Managing Pods

> How to get pods, statuses and delete instances

<Info>Before you start, ensure that you have [API Key](./api-keys) with `Instances -> Read` permission (or `Read and
    Write` if you want to `Delete` instances)</Info>

## Retrieving Existing Pods

To view a list of active instances, use the [Get Pods](./pods/get-pods) endpoint.

```bash theme={null}
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:

```bash theme={null}
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](./pods/get-pod) for details)

```json theme={null}
{
  "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:

```bash theme={null}
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](./pods/status) endpoint. This request also supports checking multiple instance statuses simultaneously:

```bash theme={null}
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:

```json theme={null}
{
  "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`.

<Info>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.</Info>

## Deleting a Pod

To delete an instance you no longer need, use the [Delete Pod](./pods/delete-pod) endpoint.

```bash theme={null}
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](./pods/get-pod) or [Get Pods](./pods/get-pods) endpoints. To view historical data, use the [Get Pods History](./pods/get-pods-history) endpoint.