API documentation

Good Proxies uses a single /api/ endpoint. All filters, output modes and JSON tuning options are controlled through GET parameters. Error responses are returned as a JSON envelope with code, message and timestamp.

• Every request starts with key and can then be extended with filters for proxy type, anonymity, speed, ping, freshness, country, city, port and service compatibility.
• The output mode is selected with get: txt by default, plus json, txt.file and json.file.
• JSON output supports additional controls: fields, split_ip, format=array|object, wrap and pretty.
• Response localisation is controlled by lang. With lang=en, the API returns city_en when an English city name is available.

On success the API returns a proxy list; on failure it returns JSON with status, code, message and timestamp, and sometimes extra context such as retry_after, daily_limit or used_subnets.

Limits depend not only on the plan itself but also on the key mode. The backend currently enforces the following windows and quotas.

• Premium key: burst limit of up to 5 requests per 5 seconds per key. When exceeded, the API returns 429 RATE_LIMIT_EXCEEDED with retry_after.
• The demo key: no more than 2 requests per minute per IP, capped at 50 proxies per response, and if works is omitted the backend defaults it to 90.
• Temporary links temp_...: no more than 2 requests per hour per link and 2 requests per hour per IP, capped at 30 proxies per response.
• Normal premium keys are also checked against the daily request budget and the daily unique-subnet quota allowed by the plan.
• If count is omitted, the API falls back to the internal limit for your key; demo and temporary modes override that with their own hard caps.

Instead of a separate developer endpoint, the current implementation exposes two special modes inside the same /api/: the demo test key and temporary links prefixed with temp_.

• The demo key is useful for the first request, JSON compatibility checks and quick client validation.
• A temporary link is validated separately and expires on its own schedule; if it fails you get TEMP_KEY_INVALID.
• Both modes use their own rate-limit windows and do not replace a full dashboard key.

Requests follow a simple pattern: start with the key, add filters, then choose the output mode. In practice, the easiest path is to configure the filters in the web UI and copy the URL, then append only the parameters that the UI does not expose.

• Start with key and add filters such as type, anon, country, city, service, ping, speed, time, works and count.
• If countries must be excluded, pass country_mode=except or the short alias cm=except.
• For JSON, set get=json and optionally add fields, split_ip=1, format=object or wrap=1.
• For TXT with protocol prefixes, use type_prefix=1. For file download instead of inline output, switch to txt.file or json.file.

Good Proxies supports TXT and JSON output. File-download modes return the same content with different response headers.

• The lang=en path localises city names through city_en when available.
• Country filtering supports exclusion mode via country_mode=except or cm=except.
• JSON mode supports field whitelisting via fields, split IP/port output, object format and response envelopes through wrap=1.
• The API can filter service compatibility for smtp, telegram, avito, google and mail.
• TXT output supports type_prefix=1, while demo and temporary keys enforce separate request-rate and response-size caps.