Dedicated proxies

List dedicated-proxy countries

Parameters

Request example Try it in the Dashboard

curl -X GET "https://papaproxy.net/account_new/api/v1/billing/dedicated/countries"

import requests

resp = requests.get(
    "https://papaproxy.net/account_new/api/v1/billing/dedicated/countries",
    timeout=30,
)
resp.raise_for_status()
print(resp.json())

const resp = await fetch("https://papaproxy.net/account_new/api/v1/billing/dedicated/countries", {
  method: "GET",
});
if (!resp.ok) throw new Error(`HTTP ${resp.status}`);
console.log(await resp.json());

<?php
$ch = curl_init('https://papaproxy.net/account_new/api/v1/billing/dedicated/countries');
curl_setopt_array($ch, [
    CURLOPT_CUSTOMREQUEST => 'GET',
    CURLOPT_RETURNTRANSFER => true,
]);
$response = curl_exec($ch);
$status = curl_getinfo($ch, CURLINFO_RESPONSE_CODE);
var_dump($status, json_decode($response, true));

package main

import (
	"fmt"
	"io"
	"net/http"
)

func main() {
	req, err := http.NewRequest("GET", "https://papaproxy.net/account_new/api/v1/billing/dedicated/countries", nil)
	if err != nil {
		panic(err)
	}
	resp, err := http.DefaultClient.Do(req)
	if err != nil {
		panic(err)
	}
	defer resp.Body.Close()
	data, _ := io.ReadAll(resp.Body)
	fmt.Println(resp.Status, string(data))
}

Responses

• 200 Countries with dedicated IPs in stock. · 6 fields

  Example response · JSONCopy

  {
    "countries": [
      {
        "country": "IL",
        "available_ips": 453
      }
    ],
    "geo_source": "maxmind",
    "product_kind": "proxy_datacenter",
    "offered_kinds": [
      "proxy_datacenter",
      "proxy_isp"
    ]
  }

  Field	Type	Description
  countries	array of object	Countries with at least one IP available.
  countries[].country required	string	ISO 3166-1 alpha-2 country code.
  countries[].available_ips required	integer	Number of dedicated IPs currently available.
  geo_source	string	Geo source the counts are for.One of: maxmind, ripeDefault: "maxmind"
  product_kind	string	Product the counts are for.One of: proxy_datacenter, proxy_ispDefault: "proxy_datacenter"
  offered_kinds	array of string	Dedicated products you can order.

• 422 Validation error: a field is missing or has the wrong type or value.

  Example · JSONCopy

  {
    "detail": "Validation error"
  }

  Error format

• 429 Too many requests: the per-account limit is 60 requests per minute, shared by all keys and the MCP server. Retry with exponential backoff.

  Example · JSONCopy

  {
    "detail": "Too Many Requests"
  }

  Error format

Get a dedicated-proxy quote

Request body

Request example Try it in the Dashboard

curl -X POST "https://papaproxy.net/account_new/api/v1/billing/dedicated/quote" \
  -H "Content-Type: application/json" \
  -d '{"segments": [{"country": "IL", "count": 2}], "period_months": 3}'

import requests

resp = requests.post(
    "https://papaproxy.net/account_new/api/v1/billing/dedicated/quote",
    json={
        "segments": [
            {
                "country": "IL",
                "count": 2
            }
        ],
        "period_months": 3
    },
    timeout=30,
)
resp.raise_for_status()
print(resp.json())

const resp = await fetch("https://papaproxy.net/account_new/api/v1/billing/dedicated/quote", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    "segments": [
      {
        "country": "IL",
        "count": 2
      }
    ],
    "period_months": 3
  }),
});
if (!resp.ok) throw new Error(`HTTP ${resp.status}`);
console.log(await resp.json());

<?php
$ch = curl_init('https://papaproxy.net/account_new/api/v1/billing/dedicated/quote');
curl_setopt_array($ch, [
    CURLOPT_CUSTOMREQUEST => 'POST',
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => [
        'Content-Type: application/json',
    ],
    CURLOPT_POSTFIELDS => json_encode([
        'segments' => [[
            'country' => 'IL',
            'count' => 2
        ]],
        'period_months' => 3
    ]),
]);
$response = curl_exec($ch);
$status = curl_getinfo($ch, CURLINFO_RESPONSE_CODE);
var_dump($status, json_decode($response, true));

package main

import (
	"fmt"
	"io"
	"net/http"
	"strings"
)

func main() {
	req, err := http.NewRequest("POST", "https://papaproxy.net/account_new/api/v1/billing/dedicated/quote", strings.NewReader(`{"segments": [{"country": "IL", "count": 2}], "period_months": 3}`))
	if err != nil {
		panic(err)
	}
	req.Header.Set("Content-Type", "application/json")
	resp, err := http.DefaultClient.Do(req)
	if err != nil {
		panic(err)
	}
	defer resp.Body.Close()
	data, _ := io.ReadAll(resp.Body)
	fmt.Println(resp.Status, string(data))
}

Responses

• 200 Price quote. Check segments[].available before ordering. · 20 fields

  Example response · JSONCopy

  {
    "unit_millicents": 220000,
    "total_price_cents": 1188,
    "ip_count": 2,
    "min_ips_per_order": 1,
    "segments": [
      {
        "country": "IL",
        "count": 2,
        "available": 453
      }
    ],
    "geo_source": "maxmind",
    "product_kind": "proxy_datacenter",
    "dedicated_class": "dc",
    "period_months": 3,
    "monthly_price_cents": 440,
    "segment_monthly_cents": 440,
    "addon_monthly_cents": 0,
    "discount_pct": 10,
    "partner_discount_pct": null,
    "promo_code": null,
    "promo_discount_cents": 0,
    "total_before_promo_cents": 1188
  }

  Field	Type	Description
  unit_millicents	integer	Monthly price per IP, in millicents (thousandths of a cent). Depends on the total IP count.
  total_price_cents	integer	Total for the whole term, in cents. Pass it as expected_total_cents when ordering.
  ip_count	integer	Total number of IPs.
  min_ips_per_order	integer	Minimum IPs per order (1 for dedicated proxies).
  segments	array of object	Requested countries with current stock.
  segments[].country	string	ISO 3166-1 alpha-2 country code.
  segments[].count	integer	Requested number of IPs.
  segments[].available	integer	IPs currently in stock. If it's lower than count, an order fails with 409 dedicated_out_of_stock.
  geo_source	string	Geo source used.One of: maxmind, ripeDefault: "maxmind"
  product_kind	string	Product priced.One of: proxy_datacenter, proxy_ispDefault: "proxy_datacenter"
  dedicated_class	string	dc for datacenter, isp for ISP.
  period_months	integer	Term in months.
  monthly_price_cents	integer	Monthly price, including add-ons, before the term discount.
  segment_monthly_cents	integer	Monthly price of the IPs alone.
  addon_monthly_cents	integer	Monthly price of add-ons.
  discount_pct	integer	Term discount, in percent.
  partner_discount_pct	integer, nullable	Partner discount, in percent, if your account has one.
  promo_code	string, nullable	Applied promo code.
  promo_discount_cents	integer	Promo discount, in cents.
  total_before_promo_cents	integer	Total before the promo discount, in cents.

• 422 Validation error: an empty segments list, a count below 1, a country that isn't an ISO code, or an unsupported period_months.

  Example · JSONCopy

  {
    "detail": "Validation error"
  }

  Error format

• 429 Too many requests: the per-account limit is 60 requests per minute, shared by all keys and the MCP server. Retry with exponential backoff.

  Example · JSONCopy

  {
    "detail": "Too Many Requests"
  }

  Error format

• 500 Currently returned for an unrecognized promo_code instead of a validation error. Check the promo code and retry without it. — error format

Order dedicated proxies

Parameters

Request body

Request example Try it in the Dashboard

curl -X POST "https://papaproxy.net/account_new/api/v1/billing/dedicated/order" \
  -H "Authorization: Bearer $PAPAPROXY_API_KEY" \
  -H "Idempotency-Key: dedicated-order-2026-001" \
  -H "Content-Type: application/json" \
  -d '{"segments": [{"country": "IL", "count": 1}], "expected_total_cents": 220, "whitelist_ips": ["203.0.113.10"], "use_balance": true}'

import os

import requests

resp = requests.post(
    "https://papaproxy.net/account_new/api/v1/billing/dedicated/order",
    headers={
        "Authorization": f"Bearer {os.environ['PAPAPROXY_API_KEY']}",
        "Idempotency-Key": "dedicated-order-2026-001",
    },
    json={
        "segments": [
            {
                "country": "IL",
                "count": 1
            }
        ],
        "expected_total_cents": 220,
        "whitelist_ips": [
            "203.0.113.10"
        ],
        "use_balance": True
    },
    timeout=30,
)
resp.raise_for_status()
print(resp.json())

const resp = await fetch("https://papaproxy.net/account_new/api/v1/billing/dedicated/order", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.PAPAPROXY_API_KEY}`,
    "Idempotency-Key": "dedicated-order-2026-001",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    "segments": [
      {
        "country": "IL",
        "count": 1
      }
    ],
    "expected_total_cents": 220,
    "whitelist_ips": [
      "203.0.113.10"
    ],
    "use_balance": true
  }),
});
if (!resp.ok) throw new Error(`HTTP ${resp.status}`);
console.log(await resp.json());

<?php
$ch = curl_init('https://papaproxy.net/account_new/api/v1/billing/dedicated/order');
curl_setopt_array($ch, [
    CURLOPT_CUSTOMREQUEST => 'POST',
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => [
        'Authorization: Bearer ' . getenv('PAPAPROXY_API_KEY'),
        'Idempotency-Key: dedicated-order-2026-001',
        'Content-Type: application/json',
    ],
    CURLOPT_POSTFIELDS => json_encode([
        'segments' => [[
            'country' => 'IL',
            'count' => 1
        ]],
        'expected_total_cents' => 220,
        'whitelist_ips' => ['203.0.113.10'],
        'use_balance' => true
    ]),
]);
$response = curl_exec($ch);
$status = curl_getinfo($ch, CURLINFO_RESPONSE_CODE);
var_dump($status, json_decode($response, true));

package main

import (
	"fmt"
	"io"
	"net/http"
	"os"
	"strings"
)

func main() {
	req, err := http.NewRequest("POST", "https://papaproxy.net/account_new/api/v1/billing/dedicated/order", strings.NewReader(`{"segments": [{"country": "IL", "count": 1}], "expected_total_cents": 220, "whitelist_ips": ["203.0.113.10"], "use_balance": true}`))
	if err != nil {
		panic(err)
	}
	req.Header.Set("Authorization", "Bearer "+os.Getenv("PAPAPROXY_API_KEY"))
	req.Header.Set("Idempotency-Key", "dedicated-order-2026-001")
	req.Header.Set("Content-Type", "application/json")
	resp, err := http.DefaultClient.Do(req)
	if err != nil {
		panic(err)
	}
	defer resp.Body.Close()
	data, _ := io.ReadAll(resp.Body)
	fmt.Println(resp.Status, string(data))
}

Responses

• 201 The order was created. Check payment_required and amount_due_cents. · 10 fields

  Example response · JSONCopy

  {
    "service_id": "1300d2ec-f511-573c-9869-93c88c501084",
    "status": "active",
    "ip_count": 1,
    "total_price_cents": 220,
    "period_months": 1,
    "monthly_price_cents": 220,
    "balance_applied_cents": 220,
    "amount_due_cents": 0,
    "payment_required": false,
    "intent_id": null
  }

  Field	Type	Description
  service_id	string (uuid)	ID of the new service.
  status	string	active when the order is paid, pending while amount_due_cents is unpaid.
  ip_count	integer	Number of IPs ordered.
  total_price_cents	integer	Total for the term, in cents.
  period_months	integer	Term in months.
  monthly_price_cents	integer	Monthly price, in cents.
  balance_applied_cents	integer	Part of the total covered by your wallet balance. A retry with the same Idempotency-Key returns 0 here, because nothing is charged again.
  amount_due_cents	integer	Amount still to be paid, in cents.
  payment_required	boolean	true when amount_due_cents must still be paid in the Dashboard.
  intent_id	string (uuid), nullable	ID of the pending payment, if any.

• 400 The Idempotency-Key was already used with a different request body.

  Example · JSONCopy

  {
    "detail": "Idempotency-Key reused with a different dedicated order body"
  }

  Error format

• 401 The API key is missing, malformed, revoked, or expired, or the account is inactive.

  Example · JSONCopy

  {
    "detail": "Invalid or revoked API key."
  }

  Error format

• 403 The API key lacks scope services:write.

  Example · JSONCopy

  {
    "detail": "API key is missing required scope: services:write"
  }

  Error format

• 409 The price changed, or a country doesn't have enough IPs in stock. Nothing is charged.

  Example · price changed · JSONCopy

  {
    "detail": {
      "code": "price_changed",
      "actual_total_cents": 220
    }
  }

  Example · out of stock · JSONCopy

  {
    "detail": {
      "code": "dedicated_out_of_stock",
      "per_country": {
        "US": {
          "requested": 1,
          "available": 0
        }
      }
    }
  }

  Error format

• 422 Validation error, a missing Idempotency-Key header or expected_total_cents, or no whitelisted IP.

  Example · idempotency key required · JSONCopy

  {
    "detail": {
      "code": "idempotency_key_required",
      "message": "Idempotency-Key header is required (1..128 chars)."
    }
  }

  Example · price confirmation required · JSONCopy

  {
    "detail": {
      "code": "price_confirmation_required",
      "message": "expected_total_cents is required (price confirmation)."
    }
  }

  Example · whitelist required · JSONCopy

  {
    "detail": {
      "error": "WHITELIST_REQUIRED",
      "message": "A proxy service requires at least one whitelisted IP at order time. …"
    }
  }

  Error format

• 429 Too many requests: the per-account limit is 60 requests per minute, shared by all keys and the MCP server. Retry with exponential backoff.

  Example · JSONCopy

  {
    "detail": "Too Many Requests"
  }

  Error format