---
title: "Check proxy health"
method: POST
path: "/proxies/{id}/check"
tags: ["Proxies"]
---

# Check proxy health

`POST /proxies/{id}/check`

Run a health check on the proxy to verify it's working. Optionally specify a URL to test reachability against a specific target. For ISP and datacenter proxies, this reliably tests whether the target site is reachable from the proxy's stable exit IP. For residential and mobile proxies, the exit node varies between requests, so this validates proxy configuration and connectivity rather than guaranteeing site-specific reachability.

## Path parameters

- `id` string, required

## Request body

- ProxyCheckRequest — Optional parameters for the proxy health check.
  - `url` string — An optional URL to test reachability against. If provided, the proxy check will test connectivity to this URL instead of the default test URLs. Only HTTP and HTTPS schemes are allowed, and the URL must resolve to a public IP address. For ISP and datacenter proxies, the exit IP is stable, so a successful check reliably indicates that subsequent browser sessions will reach the target site with the same IP. For residential and mobile proxies, the exit node changes between requests, so a successful check validates proxy configuration but does not guarantee that a subsequent browser session will use the same exit IP or reach the same site — it is useful for verifying credentials and connectivity, not for predicting site-specific behavior. When provided, the check result does not update the proxy's health status, since a failure may indicate a problem with the target site rather than the proxy itself.

## Response `200`

Health check completed

- Proxy — Configuration for routing traffic through a proxy.
  - `bypass_hosts` string[] — Hostnames that should bypass the parent proxy and connect directly.
  - `config` union — Configuration specific to the selected proxy `type`.
    - DatacenterProxyConfig — Configuration for a datacenter proxy.
      - `country` string — ISO 3166 country code. Defaults to US if not provided.
    - IspProxyConfig — Configuration for an ISP proxy.
      - `country` string — ISO 3166 country code. Defaults to US if not provided.
    - ResidentialProxyConfig — Configuration for residential proxies.
      - `asn` string — Autonomous system number. See https://bgp.potaroo.net/cidr/autnums.html
      - `city` string — City name (no spaces, e.g. `sanfrancisco`). If provided, `country` must also be provided.
      - `country` string — ISO 3166 country code.
      - `os` 'windows' | 'macos' | 'android' — Operating system of the residential device.
      - `state` string — Two-letter state code.
      - `zip` string — US ZIP code.
    - MobileProxyConfig — Configuration for mobile proxies.
      - `city` string — Provider city alias. Mobile carrier routing can make observed geo vary.
      - `country` string — ISO 3166 country code
      - `state` string — US-only state code. Mobile carrier routing can make observed geo vary.
    - CustomProxyConfig — Configuration for a custom proxy (e.g., private proxy server).
      - `has_ca_bundle` boolean — Whether the proxy has a custom CA bundle configured.
      - `has_password` boolean — Whether the proxy has a password.
      - `host` string, required — Proxy host address or IP.
      - `port` integer, required — Proxy port.
      - `username` string — Username for proxy authentication.
  - `id` string
  - `ip_address` string — IP address that the proxy uses when making requests.
  - `last_checked` string, date-time — Timestamp of the last health check performed on this proxy.
  - `name` string — Readable name of the proxy.
  - `protocol` 'http' | 'https' — Protocol to use for the proxy connection.
  - `status` 'available' | 'unavailable' — Current health status of the proxy.
  - `type` 'datacenter' | 'isp' | 'residential' | 'mobile' | 'custom', required — Proxy type to use. In terms of quality for avoiding bot-detection, from best to worst: `mobile` > `residential` > `isp` > `datacenter`.

## Other responses

- `400` — Bad Request – invalid input
- `401` — Unauthorized – missing or invalid authorization token
- `403` — Forbidden – insufficient permissions or plan
- `404` — Resource not found
- `422` — Unprocessable Entity – request was valid but the operation failed
- `500` — Internal Server Error

---

[API](https://skmtc.net/onkernel/apis/kernel-api.md) · [All operations](https://skmtc.net/onkernel/apis/kernel-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/onkernel/kernel-api/revisions/858365328f92/schema)