Skip to main content
POST
Exchange Proxies
Exchange all proxies on an order — every assigned IP is released and a fresh set of the same quantity is allocated, preferring servers that did not hold your previous IPs. The endpoint also supports cross-product exchange: send a target product and the same quantity is reassigned from a different datacenter pool. Omit the body (or send {}) to exchange within the same pool with unchanged behavior.
This feature requires the proxy_exchange feature to be enabled for your organization. Without it, requests return 403 Forbidden. Contact support if you need access. This endpoint only works on active datacenter orders (orders scheduled to cancel keep exchange rights until they expire).
Rate limits. Exchange and replace are limited two ways:
  • Per order: one exchange per 15 minutes (a 429 response includes retry_after_seconds).
  • Per API key: at most 10 exchange/replace calls per minute combined, on top of the general 60 req/min limit.

Request

Headers

Path Parameters

string
required
The order ID for which to exchange proxies.

Body Parameters

The body is optional. Omit it (or send {}) for a same-pool exchange. To exchange into a different datacenter pool, provide the target product:
string
The product ID of the datacenter product to move the order into, for example sprint or captcha. Case-sensitive. If it matches the order’s current product, a normal same-pool exchange runs. The aliases product_type and target_product_id are also accepted.

Example Request

Same-pool exchange (unchanged behavior):
Cross-product exchange:
The aliases product_type and target_product_id accept the same value:

Response

Success Response

For a same-pool exchange, previous_product_type and product_type are identical. Some responses also include details.proxies, the full list of new proxies in ip:port:username:password format.

Response Fields

string
Status of the request.
string
Human-readable result message.
object
Exchange operation details.
string
The order ID that was processed.
integer
Number of IPs before the exchange.
integer
Number of IPs after the exchange.
integer
Number of IPs requested (based on order quantity).
integer
Number of IPs that are the same between old and new (should be 0 ideally).
string
The product the order was on before the exchange. Matches product_type for a same-pool exchange.
string
The product the order is on after the exchange.
integer
The proxy port for the order’s current product.

Error Responses

403 Forbidden - Feature Not Enabled

404 Not Found

400 Bad Request - Order Not Active

Orders scheduled to cancel keep exchange rights until they expire; only expired or terminated orders are refused.

400 Bad Request - Wrong Product Type

429 Too Many Requests - Rate Limited

One exchange per order is allowed every 15 minutes, including exchanges made from the dashboard. The retry_after_seconds field tells you how long to wait. Going over the per-key limit of 10 calls per minute returns a different body:

500 Internal Server Error

Other Errors

All of these use the {"response": "error", "message": "..."} shape. Unless the message says otherwise, nothing on the order was changed.

How It Works

1

Request Exchange

You call the exchange endpoint with your order ID.
2

Current IPs Removed

Your current proxy IPs are released.
3

New IPs Assigned

Fresh IPs from the available pool are assigned to your order.
4

Confirmation

The response confirms the exchange with before/after counts.

Requirements

  • Active order: The order must be active, or cancelled but not yet expired (orders scheduled to cancel keep exchange rights until expiration)
  • Datacenter product: Exchange is only available for datacenter proxy products
  • Feature enabled: Your organization must have the proxy_exchange feature enabled
  • Within rate limits: One exchange per order every 15 minutes, and at most 10 exchange/replace calls per minute per API key

Use Cases

  • IP blocked: Get fresh IPs if your current ones are blocked
  • Clean slate: Start with unused IPs for a new project
  • Rotation: Periodic IP rotation for long-running operations

Notes

  • The exchange process takes a few seconds to complete
  • Your proxy username and password remain the same
  • The new IPs are usually different from your previous ones; overlapping_ips reports any that were reassigned
  • Always compare new_count to requested_count. If they differ, the exchange finished with fewer IPs than ordered; contact support
  • A same-pool exchange does not affect your billing or subscription
  • A cross-product exchange switches your subscription to the new product’s price with no proration, and can change your proxy port. Use details.proxy_port from the response
  • To swap a single IP instead of the whole set, use Replace Proxy

Cross-product exchange safety

When moving an order to a different product, changes happen in a safe order:
  • If the target pool cannot fully assign the requested quantity, the old proxies, the order record, and the Stripe subscription are all left unchanged.
  • Stripe is updated only after the new target proxies are fully assigned.
  • Source proxies are deleted only after target assignment and the Stripe update both succeed.
  • If the old proxies can’t be fully removed after the switch, you get a 500 asking you to contact support. Your new proxies and the subscription change are kept.

Getting Access

If you need the proxy exchange feature enabled for your organization:

Contact Support

Email us to enable proxy exchange for your organization.