# IP management

This page covers the operational lifecycle of your ISP IPs: replacing dead ones, refreshing batches, extending billing periods, and releasing IPs you no longer need.

## Replace a dead IP

Sometimes an IP gets flagged by a specific target site (e.g. Cloudflare reputation drop). helodata's policy:

* **First 14 days after purchase**: free replacement, no questions asked.
* **After 14 days**: up to **10% of the batch** can be replaced per billing period at no extra cost. Beyond that, replacements are billed at the per-IP rate.

To replace:

1. **Dashboard → ISP → My IPs → {Batch}** — click the **Replace** button on the row.
2. Pick a reason (optional but helps us improve pool quality).
3. New IP is provisioned in 1–5 minutes; the dead IP is released immediately.

Via API:

```bash
curl -X POST \
     -H "Authorization: Bearer API_KEY" \
     -H "Content-Type: application/json" \
     -d '{"reason": "target-blocked"}' \
     "https://api.helodata.com/v1/isp/ips/{ip_id}/replace"
```

## Refresh an entire batch

If a large fraction of a batch has become unusable for a target, request a **batch refresh** — every IP gets replaced in one operation. This counts as the full batch's 14-day allowance, so use sparingly:

```bash
curl -X POST -H "Authorization: Bearer API_KEY" \
     "https://api.helodata.com/v1/isp/batches/{batch_id}/refresh"
```

Available once per batch per billing period.

## Extend / renew

Subscriptions auto-renew at the end of each billing period if you have a payment method and sufficient balance. Without auto-renew:

* 7 days before expiry: warning email
* 3 days before: second warning
* On expiry: IPs become unreachable; batch enters a 7-day grace where you can renew and recover the same IPs
* After grace: IPs are released back to the pool and given to other customers

To renew manually:

**Dashboard → ISP → My IPs → {Batch} → Renew**

Or via API:

```bash
curl -X POST -H "Authorization: Bearer API_KEY" \
     -d '{"months": 1}' \
     "https://api.helodata.com/v1/isp/batches/{batch_id}/renew"
```

## Release IPs

When you no longer need IPs:

1. **Dashboard → ISP → My IPs → {Batch} → Release** — releases the entire batch
2. **Per-IP release** — click the trash icon on individual IP rows (the batch keeps the rest)

Released IPs are **not** refunded mid-period. They are removed from your account immediately and re-enter the inventory pool.

## Transferring IPs between sub-users

ISP IPs are owned by the **account**, not by a specific sub-user. To re-assign:

1. **Dashboard → ISP → My IPs → {Batch} → Settings → Sub-user** — pick a different sub-user
2. Re-download the list — the password changes (it's the new sub-user's password); the IP+port stays the same

Useful when reorganizing teams or migrating workloads.

## Monitoring batch health

The dashboard shows a per-batch health score derived from:

* Recent error rates per IP
* Replacement count
* Concurrent connection peaks
* Time since last successful request

Health < 80 triggers an alert (configurable under **Dashboard → Alerts**). A consistently-low score over multiple billing periods usually means the workload is over-saturating the batch — consider buying more IPs.

## API summary

| Action              | Endpoint                            |
| ------------------- | ----------------------------------- |
| List batches        | `GET /v1/isp/batches`               |
| List IPs in a batch | `GET /v1/isp/batches/{id}/ips`      |
| Replace one IP      | `POST /v1/isp/ips/{id}/replace`     |
| Refresh whole batch | `POST /v1/isp/batches/{id}/refresh` |
| Renew               | `POST /v1/isp/batches/{id}/renew`   |
| Release             | `DELETE /v1/isp/batches/{id}`       |

Full schemas: [Orders API](/api-reference/orders.md).


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.helodata.com/products/overview-2/ip-management.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.