Developer API Reference — NEXTPROXY REST API & Telemetry

Gateway Specifications

DUAL-STACK RUNTIME

All endpoints are served with sub-millisecond edge latency via high-throughput memory caching. Compatible with both Node.js edge daemon and PHP hosting environments.

Gateway Origin: http://localhost:3000
Dual Routing: Supports both /api/{endpoint} and api.php?action={endpoint}
Zero Hardcoded Domain: Automatically conforms to your custom domain on deployment
CORS: Access-Control-Allow-Origin: * enabled for all methods

Authentication & Rate Quotas

TIER-BASED QUOTA

Authentication is optional for guest browsing. Supplying a Developer API key unlocks higher throughput quotas, larger batch limits, and IP whitelisting.

Free Community: 60 req/min (Max 100 proxies/batch)
Verified Developer: 600 req/min (Max 2,500 proxies/batch)
Enterprise SLA: 2,400 req/min (Max 10,000 proxies/batch + IP Whitelist)
Pass Token via: X-API-Key: <key> or ?key=<key>

Credit Engine & Lockout Policy

CREDIT-PROTECTED

Developers are provisioned with credits to meter bandwidth and high-frequency scraper traffic. Every verified developer gets 1,000 Free Starter Credits.

Cost: 1 Credit per proxy fetched or endpoint called
Headers: X-Credits-Remaining and X-Credits-Used
Exhaustion Rule: Returns HTTP 402 Payment Required when 0
Key Unlocking: Instant upon recharging credits in the Developer Console

Multi-Format Export Engine RAW TXT • CSV • PAC • CLASH • JSON

Add ?format=... to any proxy endpoint to stream raw data for automated scripts, bots, scrapers, or network clients.

format=txt (Plain Text) One ip:port per line. Perfect for curl loops, Python requests, Puppeteer, Scrapy, and CLI scrapers.

format=pac (Proxy Auto-Config) Generates a standard JavaScript FindProxyForURL script. Direct drop-in into Windows, macOS, and browser proxy settings.

format=clash (YAML) Generates Clash/Shadowrocket/OpenClash compatible YAML configuration profiles.

format=csv (Spreadsheet) Download structured CSV with columns for IP, Port, Protocol, Country, Latency, and Anonymity.

Quick Start Integration

Copy-pasteable code examples for fetching proxies in your preferred language.

cURL Command

curl -s "http://localhost:3000/api/proxies" | jq .

API Endpoints Specification

Comprehensive guide to request parameters, output formats, and real-time response structures.

GET /api/proxies

Returns the real-time filtered pool of active HTTPS, SOCKS4, and SOCKS5 proxy nodes. Supports multi-parameter filtering, sorting, pagination, and multi-format exports.

Query Parameter	Type	Default	Description & Allowed Values
`type` or `protocol`	String	`all`	Filter by protocol: `https`, `socks4`, `socks5`. Comma-separated supported (e.g. `socks4,socks5`).
`country` or `region`	String	`all`	Filter by 2-letter ISO country code (e.g. `US`, `DE`, `NL`, `GB`, `FR`, `SG`, `JP`).
`port`	String	`all`	Filter by specific port numbers (e.g. `8080`, `1080`, `3128`).
`anonymity`	String	`all`	Filter by anonymity level: `elite`, `anonymous`, `transparent`.
`max_latency`	Integer	`0` (off)	Filter proxies with round-trip latency less than or equal to threshold in milliseconds (e.g. `max_latency=50`).
`sort`	String	`none`	Sort order: `fastest` (or `latency_asc`), `slowest`, `port`, `country`.
`limit`	Integer	`100`	Number of nodes to return (Up to 100 for Guest, 2,500 for Developer, 10,000 for Enterprise).
`page`	Integer	`1`	Pagination page index (1-indexed).
`format`	String	`json`	Output serialization format: `json`, `txt`, `csv`, `pac`, `clash`.

Example JSON Response (200 OK)

{
  "status": "success",
  "count": 2,
  "totalMatching": 8733,
  "page": 1,
  "limit": 2,
  "clientTier": "Verified Developer Tier",
  "proxies": [
    {
      "ip": "138.201.223.97",
      "port": "8080",
      "type": "https",
      "protocol": "https",
      "country": "DE",
      "latency": 26,
      "anonymity": "anonymous",
      "status": "active"
    },
    {
      "ip": "45.150.53.132",
      "port": "1080",
      "type": "socks5",
      "protocol": "socks5",
      "country": "US",
      "latency": 31,
      "anonymity": "elite",
      "status": "active"
    }
  ]
}

GET /api/random

Returns a single rotating proxy node dynamically chosen from the active cluster matching your filters. When called with format=txt, returns raw ip:port with zero parsing overhead—perfect for scraping scripts that rotate on every HTTP request.

Example Response with format=txt (200 OK)

144.31.203.98:1080

GET /api/ip

High-precision client IP reflector and anonymity verification endpoint. Used by automated workers to confirm that their outgoing traffic is successfully masking their real origin IP through a NextProxy node.

Example JSON Response (200 OK)

{
  "ip": "194.26.29.11",
  "country": "DE",
  "countryName": "Germany",
  "protocol": "HTTPS",
  "userAgent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64)",
  "clientTier": "Enterprise SLA",
  "headers": {
    "x-forwarded-for": null,
    "cf-connecting-ip": null,
    "x-real-ip": null
  },
  "timestamp": "2026-09-14T00:45:00.000Z"
}

GET /api/telegram-proxies

Returns all active Telegram Dedicated MTProto Proxies with 256-bit cryptographic secrets, server hostnames, ports, country codes, and direct URI links. Supports ?format=links for raw tg://proxy links or ?format=web for https://t.me/proxy links.

Example Response (200 OK)

{
  "status": "success",
  "count": 1,
  "proxies": [
    {
      "server": "138.201.223.97",
      "port": "8443",
      "secret": "dd104462821249bd7ac519130220c25d09",
      "country": "DE",
      "type": "telegram",
      "tgLink": "tg://proxy?server=138.201.223.97&port=8443&secret=dd104462821249bd7ac519130220c25d09",
      "webLink": "https://t.me/proxy?server=138.201.223.97&port=8443&secret=dd104462821249bd7ac519130220c25d09"
    }
  ]
}

GET /api/all-proxies

Returns the unified combined cluster pool, incorporating HTTPS, SOCKS4, SOCKS5, and Telegram MTProto dedicated nodes into one aggregated collection.

GET /api/countries

Returns real-time geographic telemetry including total nodes available, active cluster health, and average round-trip latency in milliseconds for every country in the pool.

Example Response (200 OK)

{
  "status": "success",
  "totalCountries": 12,
  "countries": [
    { "code": "US", "name": "United States", "count": 2140, "avgLatencyMs": 34, "status": "operational" },
    { "code": "DE", "name": "Germany", "count": 1820, "avgLatencyMs": 28, "status": "operational" },
    { "code": "NL", "name": "Netherlands", "count": 1450, "avgLatencyMs": 22, "status": "operational" }
  ]
}

GET /api/protocols

Returns telemetry on protocol coverage across the edge backbone, standard transit port assignments, encryption protocols, and cipher details.

GET /api/stats

Retrieves global cluster status, real-time node count per protocol (HTTPS, SOCKS4, SOCKS5, Telegram), client tier verification, and ingestion daemon refresh intervals.

GET /api/health

Liveness check and SLA status endpoint for monitoring agents (e.g. UptimeRobot, Datadog, Prometheus).

GET /api/verify-proxy

Executes real-time TCP socket connection probing against a specified target or comma-separated batch list. Returns latency in milliseconds and status.

Query Parameter	Required	Format	Description
`target`	Optional	`ip:port`	Single proxy target (e.g. `138.201.223.97:8080`).
`targets`	Optional	`ip1:port,ip2:port`	Batch list up to 25 targets separated by commas.

Interactive API Playground

Execute real HTTP requests directly against your local NextProxy edge cluster with live telemetry.

GATEWAY READY

Quick Test Presets:

API Endpoint URL

Optional API Key (X-API-Key) Use Demo Key

          Status: Idle
          Latency: 0ms
          Rate Limit: 60/60
        

Click "Execute Request" or any quick preset to inspect live API output...