Shadowsocks API reference and data availability

Free API & downloads: 24-hour access

Get access here before using the API or downloading a dataset. Your key and download links expire after 24 hours. Return to this page and press the button to get new access; it does not renew automatically.

Checking access…

Protected by Google reCAPTCHA. Google’s Privacy Policy and Terms of Service apply.

For permanent access, tell us your name, email and intended use. Requests are reviewed individually.

Already saved files are not revoked. A configuration may stop working earlier if its third-party server changes. Individual OpenVPN checks still use their existing single-use download token.

Request example

curl -H 'Authorization: Bearer YOUR_24_HOUR_KEY' -H 'Accept: application/json' \
  'https://publicvpnlist.com/api/v1/servers?protocol=shadowsocks&status=online&sort=last_checked&order=desc&per_page=50'

The response is paginated. Keep the returned id for details at /api/v1/servers/{id}, cache the ETag, and treat last_checked_at as technical evidence rather than a privacy guarantee.

What each Shadowsocks record means

Shadowsocks uses encrypted TCP/UDP proxy endpoints. A usable public configuration requires a supported AEAD cipher and password. PublicVPNList does not publish rows inferred from an open port or incomplete relay metadata.

Endpoints and filters

Use protocol=shadowsocks consistently. Omitting it selects OpenVPN for backward compatibility.

• Server list JSON — data, meta.total, meta.page and links.next.
• Countries and counts.
• Protocol statistics.
• Snapshot version, expiry and export links.
• Protocol snapshot health.

Filter by country=US, transport=tcp, port=443, status=online, fresh_within=3600, min_speed=1, max_latency=500 or min_uptime=90. Metric filters exclude rows where that measurement is unknown.

Use page=1&per_page=50 (maximum 200), fields=id,protocol,country_code,server_page_url, and sort=speed|latency|uptime|last_checked|score|first_seen with order=asc|desc. Follow links.next until null. Compare the returned version if the dataset updates during pagination.

Download metadata in bulk

These complete metadata exports include all records in this protocol snapshot, without pagination. They contain links to configurations, not embedded passwords or client keys.

Add &country=US to restrict an export to one country. The TXT format is UTF-8 TSV. Export responses include ETag, Last-Modified, X-Dataset-Version and X-Checksum-SHA256. See all export formats.

Errors and empty catalogs

A successful empty response is HTTP 200 with data: [], meta.total: 0 and links.next: null. It means no checked records are currently published for this protocol, not a broken API. TUIC, WireGuard and IKEv2 require usable configurations and successful full checks before rows can appear.

API errors: 401 missing or expired access key, 400 invalid or repeated parameter, 404 missing record, 405 unsupported method, 429 rate limit, 503 unavailable protocol snapshot. The JSON API permits 60 requests per minute; respect Retry-After. GET/HEAD support conditional caching (304), and OPTIONS provides CORS preflight; data requests require a Bearer key or the 24-hour browser access cookie. Unknown values remain null. Common examples and complete field reference.

Freshness, safety and caching

Only checks no older than 72 hours can enter the protocol snapshot. Every row requires a real client tunnel, a successful HTTPS request and a public exit IP different from the checker’s direct address. Unknown third-party endpoints can still log or alter traffic; use end-to-end encryption and avoid sensitive accounts.

Snapshot version: 20261023T230459Z-003dc0153845. API JSON routes are excluded from search indexing; this documentation page is the canonical explanation; search indexing depends on the publication gate above.