Check a service end to end

POST

/v1/services/{id}/check

curl --request POST \
  --url https://api.trueproxies.com/v1/services/2489E9AD-2EE2-8E00-8EC9-32D5F69181C0/check \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{ "asn": "example", "city": "example", "count": 1, "country": "example", "format": "host:port:user:pass", "job_id": "2489E9AD-2EE2-8E00-8EC9-32D5F69181C0", "lifetime": 1, "project_id": "2489E9AD-2EE2-8E00-8EC9-32D5F69181C0", "protocol": "http", "region": "example", "session": "none", "template": "example" }'

Runs one request through the service from our side and reports the outcome. Rate limited to a few checks a minute. Use it to tell a proxy problem apart from a target that is refusing you.

Authorizations

• customerAPIKey

Parameters

Path Parameters

id

required

string format: uuid

Query Parameters

customer_id

string format: uuid

Owned sub-customer UUID. Resellers only; reads require reseller:read and writes reseller:purchase in addition to the operation scope. X-Customer-Id header is an alternative. Not allowed for me, wallet, trial, API keys, or reseller-management routes.

Request Body^required

Media typeapplication/json

object

asn

1 to 10 digits, without AS prefix. Requires asn capability.

string

<= 10 characters

city

Letters, digits and underscores; normalized to lowercase. Requires city capability.

string

<= 32 characters

count

Number of connection strings. Omission, null and legacy zero values use one.

integer

default: 1 >= 1 <= 1000

country

Two-letter country code; normalized to lowercase. Requires country capability.

string

format

string

default: host:port:user:pass

Allowed values: host:port:user:pass user:pass@host:port user:pass host:port url curl custom

job_id

Owned active job beneath project_id. Only its validated opaque token is included in generated proxy usernames.

string format: uuid

lifetime

Sticky session lifetime in seconds, 60 to 86400, or 1 to 86400 when the service has session_lifetime_seconds. Maximum is 1800 with session_lifetime_30m. Requires session=sticky and session_lifetime capability. Residential IPv4 Unlimited requires whole minutes. Omitted or zero leaves the lifetime unset.

integer

project_id

Owned, active project access. Omit to use main access. Requires current project support.

string format: uuid

protocol

string

default: http

Allowed values: http socks5 https

region

Requires region capability. Services with region_code accept only an ISO 3166-2 subdivision code of 1 to 3 letters or digits without country prefix (for example CA). Other services accept letters, digits and underscores up to 32 characters. Normalized to lowercase in customer usernames.

string

<= 32 characters

session

string

default: none

Allowed values: none sticky rotate

template

Required only for format=custom. A single line of literal text, limited to 512 UTF-8 bytes, with at least one of {HOST}, {PORT}, {USER}, {PASS} or {PROTOCOL}. Other braces and control characters are rejected. Placeholder values are substituted literally without escaping or recursive expansion. {PROTOCOL} is the connection URL scheme (http, https or socks5h).

string

>= 1 characters <= 512 characters

Responses

200

Check result; success=false means the bounded proxy request did not complete successfully.

Media typeapplication/json

object

checked_at

required

string format: date-time

elapsed_ms

required

Duration of this single HTTPS check, including proxy connection setup.

integer format: int64

exit_ip

Public IPv4 or IPv6 exit address returned by ipify when the check succeeds.

string

message

required

Safe status message without proxy credentials or internal transport errors.

string

success

required

boolean

Example^generated

{
  "checked_at": "2026-04-15T12:00:00Z",
  "elapsed_ms": 1,
  "exit_ip": "example",
  "message": "example",
  "success": true
}

400

Error

Media typeapplication/json

object

code

required

string

Allowed values: BAD_REQUEST UNAUTHENTICATED FORBIDDEN NOT_FOUND CONFLICT RATE_LIMITED SERVICE_UNAVAILABLE OFFER_UNAVAILABLE CITY_UNAVAILABLE CAPACITY_UNAVAILABLE INVOICE_NOT_PAYABLE PROVIDER_ERROR PIPE_UNAVAILABLE TRIAL_NOT_ELIGIBLE EMAIL_UNVERIFIED INTERNAL

details

What a client needs to act on the error (ids, flags), never display text.

object

key

additional properties

any

message

required

string

Example

{
  "code": "BAD_REQUEST"
}

401

Error

Media typeapplication/json

object

code

required

string

Allowed values: BAD_REQUEST UNAUTHENTICATED FORBIDDEN NOT_FOUND CONFLICT RATE_LIMITED SERVICE_UNAVAILABLE OFFER_UNAVAILABLE CITY_UNAVAILABLE CAPACITY_UNAVAILABLE INVOICE_NOT_PAYABLE PROVIDER_ERROR PIPE_UNAVAILABLE TRIAL_NOT_ELIGIBLE EMAIL_UNVERIFIED INTERNAL

details

What a client needs to act on the error (ids, flags), never display text.

object

key

additional properties

any

message

required

string

Example

{
  "code": "BAD_REQUEST"
}

403

Error

Media typeapplication/json

object

code

required

string

Allowed values: BAD_REQUEST UNAUTHENTICATED FORBIDDEN NOT_FOUND CONFLICT RATE_LIMITED SERVICE_UNAVAILABLE OFFER_UNAVAILABLE CITY_UNAVAILABLE CAPACITY_UNAVAILABLE INVOICE_NOT_PAYABLE PROVIDER_ERROR PIPE_UNAVAILABLE TRIAL_NOT_ELIGIBLE EMAIL_UNVERIFIED INTERNAL

details

What a client needs to act on the error (ids, flags), never display text.

object

key

additional properties

any

message

required

string

Example

{
  "code": "BAD_REQUEST"
}

404

Error

Media typeapplication/json

object

code

required

string

Allowed values: BAD_REQUEST UNAUTHENTICATED FORBIDDEN NOT_FOUND CONFLICT RATE_LIMITED SERVICE_UNAVAILABLE OFFER_UNAVAILABLE CITY_UNAVAILABLE CAPACITY_UNAVAILABLE INVOICE_NOT_PAYABLE PROVIDER_ERROR PIPE_UNAVAILABLE TRIAL_NOT_ELIGIBLE EMAIL_UNVERIFIED INTERNAL

details

What a client needs to act on the error (ids, flags), never display text.

object

key

additional properties

any

message

required

string

Example

{
  "code": "BAD_REQUEST"
}

409

Error

Media typeapplication/json

object

code

required

string

Allowed values: BAD_REQUEST UNAUTHENTICATED FORBIDDEN NOT_FOUND CONFLICT RATE_LIMITED SERVICE_UNAVAILABLE OFFER_UNAVAILABLE CITY_UNAVAILABLE CAPACITY_UNAVAILABLE INVOICE_NOT_PAYABLE PROVIDER_ERROR PIPE_UNAVAILABLE TRIAL_NOT_ELIGIBLE EMAIL_UNVERIFIED INTERNAL

details

What a client needs to act on the error (ids, flags), never display text.

object

key

additional properties

any

message

required

string

Example

{
  "code": "BAD_REQUEST"
}

429

Error

Media typeapplication/json

object

code

required

string

Allowed values: BAD_REQUEST UNAUTHENTICATED FORBIDDEN NOT_FOUND CONFLICT RATE_LIMITED SERVICE_UNAVAILABLE OFFER_UNAVAILABLE CITY_UNAVAILABLE CAPACITY_UNAVAILABLE INVOICE_NOT_PAYABLE PROVIDER_ERROR PIPE_UNAVAILABLE TRIAL_NOT_ELIGIBLE EMAIL_UNVERIFIED INTERNAL

details

What a client needs to act on the error (ids, flags), never display text.

object

key

additional properties

any

message

required

string

Example

{
  "code": "BAD_REQUEST"
}

500

Error

Media typeapplication/json

object

code

required

string

Allowed values: BAD_REQUEST UNAUTHENTICATED FORBIDDEN NOT_FOUND CONFLICT RATE_LIMITED SERVICE_UNAVAILABLE OFFER_UNAVAILABLE CITY_UNAVAILABLE CAPACITY_UNAVAILABLE INVOICE_NOT_PAYABLE PROVIDER_ERROR PIPE_UNAVAILABLE TRIAL_NOT_ELIGIBLE EMAIL_UNVERIFIED INTERNAL

details

What a client needs to act on the error (ids, flags), never display text.

object

key

additional properties

any

message

required

string

Example

{
  "code": "BAD_REQUEST"
}

503

Error

Media typeapplication/json

object

code

required

string

Allowed values: BAD_REQUEST UNAUTHENTICATED FORBIDDEN NOT_FOUND CONFLICT RATE_LIMITED SERVICE_UNAVAILABLE OFFER_UNAVAILABLE CITY_UNAVAILABLE CAPACITY_UNAVAILABLE INVOICE_NOT_PAYABLE PROVIDER_ERROR PIPE_UNAVAILABLE TRIAL_NOT_ELIGIBLE EMAIL_UNVERIFIED INTERNAL

details

What a client needs to act on the error (ids, flags), never display text.

object

key

additional properties

any

message

required

string

Example

{
  "code": "BAD_REQUEST"
}