Appearance
Fresh 🌱
Check proxy health ​
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.
OpenAPI ​
yaml
openapi: 3.1.0
info:
title: Kernel API
description: Developer tools and cloud infrastructure for AI agents to use web browsers
version: 0.1.0
servers:
- url: https://api.onkernel.com
description: API Server
security:
- bearerAuth: []
tags:
- name: Browsers
description: Create and manage browser sessions.
- name: Browser Replays
description: Record and manage browser session video replays.
- name: Profiles
description: Create, list, retrieve, and delete browser profiles.
- name: Browser Filesystem
description: Read, write, and manage files on the browser instance.
- name: Browser Computer Controls
description: Control mouse, keyboard, and screen on the browser instance.
- name: Browser Playwright
description: Execute Playwright code against the browser instance.
- name: Browser Processes
description: Execute and manage processes on the browser instance.
- name: Browser Logs
description: Stream logs from the browser instance.
- name: Extensions
description: Create, list, retrieve, and delete browser extensions.
- name: Proxies
description: Create and manage proxy configurations for routing browser traffic.
- name: Browser Pools
description: Create and manage browser pools for acquiring and releasing browsers.
- name: Managed Auth
description: >-
Create and manage auth connections for automated credential capture and
login.
- name: Credentials
description: Create and manage credentials for authentication.
- name: Credential Providers
description: Configure external credential providers like 1Password.
- name: Apps
description: List applications and versions.
- name: Deployments
description: Create and manage app deployments and stream deployment events.
- name: Invocations
description: Invoke actions and stream or query invocation status and events.
- name: Projects
description: Create and manage projects for resource isolation within an organization.
paths:
/proxies/{id}/check:
post:
tags:
- Proxies
summary: Check proxy health
description: >-
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.
operationId: postProxiesByIdCheck
parameters:
- name: id
in: path
required: true
schema:
type: string
requestBody:
required: false
content:
application/json:
schema:
$ref: '#/components/schemas/ProxyCheckRequest'
responses:
'200':
description: Health check completed
content:
application/json:
schema:
$ref: '#/components/schemas/Proxy'
'400':
$ref: '#/components/responses/BadRequest'
'401':
$ref: '#/components/responses/Unauthorized'
'403':
$ref: '#/components/responses/Forbidden'
'404':
$ref: '#/components/responses/NotFound'
'422':
$ref: '#/components/responses/UnprocessableEntity'
'500':
$ref: '#/components/responses/InternalError'
security:
- bearerAuth: []
x-codeSamples:
- lang: JavaScript
source: |-
import Kernel from '@onkernel/sdk';
const client = new Kernel({
apiKey: process.env['KERNEL_API_KEY'], // This is the default and can be omitted
});
const response = await client.proxies.check('id');
console.log(response.id);
- lang: Python
source: |-
import os
from kernel import Kernel
client = Kernel(
api_key=os.environ.get("KERNEL_API_KEY"), # This is the default and can be omitted
)
response = client.proxies.check(
id="id",
)
print(response.id)
- lang: Go
source: "package main\n\nimport (\n\t\"context\"\n\t\"fmt\"\n\n\t\"github.com/kernel/kernel-go-sdk\"\n\t\"github.com/kernel/kernel-go-sdk/option\"\n)\n\nfunc main() {\n\tclient := kernel.NewClient(\n\t\toption.WithAPIKey(\"My API Key\"),\n\t)\n\tresponse, err := client.Proxies.Check(\n\t\tcontext.TODO(),\n\t\t\"id\",\n\t\tkernel.ProxyCheckParams{},\n\t)\n\tif err != nil {\n\t\tpanic(err.Error())\n\t}\n\tfmt.Printf(\"%+v\\n\", response.ID)\n}\n"
components:
schemas:
ProxyCheckRequest:
type: object
description: Optional parameters for the proxy health check.
properties:
url:
type: string
description: >-
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.
Proxy:
type: object
description: Configuration for routing traffic through a proxy.
required:
- type
properties:
id:
type: string
name:
type: string
description: Readable name of the proxy.
type:
type: string
description: >
Proxy type to use. In terms of quality for avoiding bot-detection,
from best to worst: `mobile` > `residential` > `isp` > `datacenter`.
enum:
- datacenter
- isp
- residential
- mobile
- custom
protocol:
type: string
description: Protocol to use for the proxy connection.
enum:
- http
- https
default: https
bypass_hosts:
type: array
description: Hostnames that should bypass the parent proxy and connect directly.
items:
type: string
status:
type: string
description: Current health status of the proxy.
enum:
- available
- unavailable
last_checked:
type: string
format: date-time
description: Timestamp of the last health check performed on this proxy.
ip_address:
type: string
description: IP address that the proxy uses when making requests.
example: 192.168.1.1
config:
description: Configuration specific to the selected proxy `type`.
oneOf:
- $ref: '#/components/schemas/DatacenterProxyConfig'
- $ref: '#/components/schemas/IspProxyConfig'
- $ref: '#/components/schemas/ResidentialProxyConfig'
- $ref: '#/components/schemas/MobileProxyConfig'
- $ref: '#/components/schemas/CustomProxyConfig'
discriminator:
propertyName: type
mapping:
datacenter:
$ref: '#/components/schemas/DatacenterProxyConfig'
isp:
$ref: '#/components/schemas/IspProxyConfig'
residential:
$ref: '#/components/schemas/ResidentialProxyConfig'
mobile:
$ref: '#/components/schemas/MobileProxyConfig'
custom:
$ref: '#/components/schemas/CustomProxyConfig'
DatacenterProxyConfig:
type: object
description: Configuration for a datacenter proxy.
properties:
country:
type: string
description: ISO 3166 country code. Defaults to US if not provided.
example: US
IspProxyConfig:
type: object
description: Configuration for an ISP proxy.
properties:
country:
type: string
description: ISO 3166 country code. Defaults to US if not provided.
example: US
ResidentialProxyConfig:
type: object
description: Configuration for residential proxies.
properties:
country:
type: string
description: ISO 3166 country code.
example: US
city:
type: string
description: >-
City name (no spaces, e.g. `sanfrancisco`). If provided, `country`
must also be provided.
example: sanfrancisco
state:
type: string
description: Two-letter state code.
example: CA
zip:
type: string
description: US ZIP code.
example: '94107'
asn:
type: string
description: >-
Autonomous system number. See
https://bgp.potaroo.net/cidr/autnums.html
example: AS15169
os:
type: string
description: Operating system of the residential device.
deprecated: true
x-deprecated-reason: os selection not supported by proxy provider
enum:
- windows
- macos
- android
MobileProxyConfig:
x-hidden: true
x-deprecated: true
x-deprecated-reason: Mobile proxies not reliable enough from our proxy provider
type: object
description: Configuration for mobile proxies.
properties:
country:
type: string
description: ISO 3166 country code
example: US
city:
type: string
description: >-
City name (no spaces, e.g. `sanfrancisco`). If provided, `country`
must also be provided.
example: sanfrancisco
state:
type: string
description: Two-letter state code.
example: CA
zip:
type: string
description: US ZIP code.
example: '94107'
asn:
type: string
description: >-
Autonomous system number. See
https://bgp.potaroo.net/cidr/autnums.html
example: AS15169
carrier:
type: string
description: Mobile carrier.
enum:
- a1
- aircel
- airtel
- att
- celcom
- chinamobile
- claro
- comcast
- cox
- digi
- dt
- docomo
- dtac
- etisalat
- idea
- kyivstar
- meo
- megafon
- mtn
- mtnza
- mts
- optus
- orange
- qwest
- reliance_jio
- robi
- sprint
- telefonica
- telstra
- tmobile
- tigo
- tim
- verizon
- vimpelcom
- vodacomza
- vodafone
- vivo
- zain
- vivabo
- telenormyanmar
- kcelljsc
- swisscom
- singtel
- asiacell
- windit
- cellc
- ooredoo
- drei
- umobile
- cableone
- proximus
- tele2
- mobitel
- o2
- bouygues
- free
- sfr
- digicel
CustomProxyConfig:
type: object
description: Configuration for a custom proxy (e.g., private proxy server).
required:
- host
- port
properties:
host:
type: string
description: Proxy host address or IP.
example: 127.0.0.1
port:
type: integer
description: Proxy port.
example: 8080
username:
type: string
description: Username for proxy authentication.
example: user123
has_password:
type: boolean
description: Whether the proxy has a password.
example: true
Error:
type: object
required:
- code
- message
properties:
code:
type: string
description: Application-specific error code (machine-readable)
example: bad_request
message:
type: string
description: Human-readable error description for debugging
example: 'Missing required field: app_name'
details:
type: array
description: Additional error details (for multiple errors)
items:
$ref: '#/components/schemas/ErrorDetail'
inner_error:
$ref: '#/components/schemas/ErrorDetail'
ErrorDetail:
type: object
properties:
code:
type: string
description: Lower-level error code providing more specific detail
example: invalid_input
message:
type: string
description: Further detail about the error
example: Provided version string is not semver compliant
responses:
BadRequest:
description: Bad Request - invalid input
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
Unauthorized:
description: Unauthorized - missing or invalid authorization token
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
Forbidden:
description: Forbidden - insufficient permissions or plan
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
NotFound:
description: Resource not found
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
UnprocessableEntity:
description: Unprocessable Entity - request was valid but the operation failed
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
InternalError:
description: Internal Server Error
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
securitySchemes:
bearerAuth:
type: http
scheme: bearer