Skip to content
TrueProxies Docs

Get a service

GET
/v1/services/{id}
curl --request GET \
  --url https://api.trueproxies.com/v1/services/2489E9AD-2EE2-8E00-8EC9-32D5F69181C0 \
  --header 'Authorization: Bearer <token>'

Connection hosts, available ports, capabilities, status, expiry and effective limits. Does not return the proxy password.

Authorizations

Section titled “Authorizations”

Parameters

Section titled “Parameters”

Path Parameters

Section titled “Path Parameters”
id
required
string format: uuid

Query Parameters

Section titled “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.

Responses

Section titled “Responses”

200

Section titled “200”

Ok

Media typeapplication/json
object
auto_pay
required

Automatic renewal is on (automatic top-up on GB plans). The saved card is charged without the customer paying the invoice.

boolean
auto_pay_available
required

Automatic renewal can be turned on for this service now.

boolean
auto_pay_last_failure
required
Any of:
object
at
required
string format: date-time
reason
required
string
billing_read_only
required

Existing access remains available, but this service cannot be topped up or renewed. New plan purchases are separate.

boolean
capabilities
required
Array<string>
city
string
comparison_pass

Free private comparison with fixed speed and expiry; cannot be purchased, topped up or renewed.

boolean
connects_per_second
required

Effective limit for this service.

integer
created_at
required
string format: date-time
depleted
boolean
display_name
required

Unlimited service names reflect their actual speed and term; offer_key retains the original billing plan.

string
expires_at
string format: date-time
grace_until
string format: date-time
host
required
string
id
required

Internal API identifier. Use reference for customer-facing display.

string format: uuid
ips

The service’s IPs in order, for isp_dedicated; empty until they are set up.

Array<object>

One IP of an isp_dedicated service and the gateway port that reaches it.

object
exit_ip
required

The IP traffic leaves from; null until it is known.

string | null
host
required
string
index
required
integer
port
required
integer
label

The customer’s own name for this service. Absent when not set; show display_name then.

string
<= 40 characters
max_connections
required

Effective limit for this service.

integer
offer_key
required
string
pool

A carrier sold as isp_dedicated, a country and the provider its IPs are registered to.

object
carrier
required
string
country
required
string
in_stock
required
boolean
key
required
string
terms
required
Array<string>
Allowed values: day week month
ports
required
object
http
required
integer
https
required
integer
socks5
required
integer
product
required
string
Allowed values: residential_ipv4_gb residential_ipv4_unlimited datacenter_ipv6 trial residential_ipv6 isp_dedicated residential_ipv4_premium residential_ipv4_lite residential_ipv4_unlimited_pro
quantity

IPs bought, for isp_dedicated.

integer
>= 1
reference
required

Stable, unique customer-facing reference.

string
/^SVC-[0-9]{6,}$/
renewal_price_cents

What the next renewal, or a top-up with the same pack, charges. A service keeps the price it was bought or last changed plan at when the catalog price changes. Absent when the service does not renew.

integer format: int64
renewals_enabled
required
boolean
speed_bps

0 for paid residential_ipv4_gb means no additional TrueProxies speed cap. Private comparison passes have a fixed 50000000 bps cap. residential_ipv4_unlimited retains its positive plan speed. Upstream capacity and availability still apply. Trials and datacenter plans retain their speed limits.

integer format: int64
starts_at
string format: date-time
status
required
string
Allowed values: pending active expired closed suspended failed
term
string
Allowed values: hour day week month
term_label

Actual fixed duration for a free Unlimited grant, such as 3 hours. Overrides the recurring term label in customer views.

string
trial_product

The Unlimited product a free trial (offer_key ipv4_unlimited_trial_1h) runs as, or will start as before its first request. Upgrade plan moves the trial within this product. Absent on other services.

string
Allowed values: residential_ipv4_unlimited residential_ipv4_unlimited_pro
trial_started_at

First recorded trial traffic; absent until the first request starts the 30-minute window.

string format: date-time
udp_ports

The only destination ports UDP over SOCKS5 reaches on this service (443 and 19302 on Unlimited Pro and on a free trial that runs as Unlimited Pro). Absent when any port the gateway allows works.

Array<integer>
usage_source
required
string
Allowed values: node
username_base
required
string
whitelist_entries
integer
Example
{
  "pool": {
    "terms": [
      "day"
    ]
  },
  "product": "residential_ipv4_gb",
  "reference": "SVC-001001",
  "status": "pending",
  "term": "hour",
  "trial_product": "residential_ipv4_unlimited",
  "usage_source": "node"
}

400

Section titled “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

Section titled “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

Section titled “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

Section titled “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

Section titled “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

Section titled “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

Section titled “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

Section titled “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"
}