Proxy checks

The proxy checks endpoint verifies a proxy configuration and reports its exit location. It is the programmatic equivalent of the Check proxy button in the dashboard: you hand it a configuration and it tells you where that configuration actually comes out. All requests go to https://api.nodemaven.com/api/v2/base/ and carry the header Authorization: x-api-key YOUR_API_KEY. See the NodeMaven API overview for the shared basics.

Endpoint

Method	Path	What it does	Request body	Responses
`POST`	`/proxy-checks/location`	Dry-run a proxy configuration and verify its exit location	`LocationCheckRequest`	200, 403, 422

It is a POST, but it is a dry run. It verifies a configuration without committing to it, so sending a POST here does not provision anything. Use it freely to validate a configuration before you rely on it.

LocationCheckRequest

Field	Required	Notes
`credentials`	Yes	The credentials for the proxy being checked
`config`	Yes	The proxy configuration to verify
`timeout_seconds`	No	Integer, in seconds

credentials and config are both nested objects.

credentials

Field	Type	Required
`username`	string	Yes
`password`	string	Yes

config

Field	Type	Required	Accepted values	Default
`proxy_type`	string	Yes	`residential`, `mobile`, `isp`
`protocol`	string	No	`http`, `socks5`	`http`
`session_mode`	string	No	`rotating`, `sticky`, `no_rotation`	`rotating`
`ttl_seconds`	integer	No	Minimum 1
`targeting`	object	No

Only proxy_type is required inside config. Leave protocol and session_mode out and the check runs as an HTTP rotating session. session_mode is where you request a sticky session. Set session_mode to sticky and use ttl_seconds to say how long that session should hold its IP. ttl_seconds only has meaning for a sticky session.

targeting

targeting is an object whose fields all narrow where the proxy exits. Every field is optional, and every field is a string:

Field	Type
`country`	string
`region`	string
`city`	string
`isp`	string
`zipcode`	string

The three proxy types and the targeting fields are the same ones you use when you build a proxy username, so a configuration that checks out here is a configuration you can then use directly.

curl -X POST https://api.nodemaven.com/api/v2/base/proxy-checks/location \
  -H "Authorization: x-api-key YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "credentials": {
      "username": "USERNAME",
      "password": "PASSWORD"
    },
    "config": {
      "proxy_type": "residential",
      "protocol": "http",
      "session_mode": "sticky",
      "ttl_seconds": 600,
      "targeting": {
        "country": "us",
        "city": "chicago"
      }
    },
    "timeout_seconds": 30
  }'

The example above checks a residential proxy on a sticky session that holds its IP for 600 seconds, exiting in Chicago, United States.

Test your proxies covers checking a proxy from the dashboard.
Wrong IP location is the troubleshooting page for when the exit location is not what you expected.

Platform API

Product APIs

Endpoint

LocationCheckRequest

credentials

config

targeting

​Endpoint

​LocationCheckRequest

​credentials

​config

​targeting

​Related reading

Endpoint

LocationCheckRequest

credentials

config

targeting

Related reading