Skip to content
TrueProxies Docs

Get service usage

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

Traffic counters are bytes; GB balances are decimal gigabytes (1 GB = 1,000,000,000 bytes). Read last_updated_at and provider_observed_at for freshness. Provider balances are present for GB services.

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
allowance_bytes
required
integer format: int64
bytes_in
required

Bytes the proxy read from the client, which is the customer’s upload.

integer format: int64
bytes_out
required

Bytes the proxy wrote back to the client, which is the customer’s download.

integer format: int64
current_period_used_bytes

Traffic counted against the current allowance period. Lifetime totals remain in bytes_in and bytes_out.

integer format: int64
gb_allocated

Informational provider balance in decimal GB; billing uses node byte counters.

number
gb_remaining

Informational provider balance in decimal GB; billing uses node byte counters.

number
gb_used

Informational provider balance in decimal GB; billing uses node byte counters.

number
last_updated_at
required
string format: date-time
next_reset_at

Next scheduled allowance reset; a past timestamp means confirmation is pending.

string format: date-time
period_started_at

Start of the current confirmed allowance period, when applicable.

string format: date-time
provider_observed_at
string format: date-time
provider_usage_informational
required
boolean
reconciliation
object
drift_ratio
required
number
observed_at
required
string format: date-time
status
required

Compares the change in vendor balance with the change in node counters between two consecutive observations, hourly. baseline is the first observation for a service, which has no predecessor to compare with and therefore reports zero drift; it is not a statement that the two figures agree. Billing always uses the node counters.

string
Allowed values: baseline ok drift reset stale
usage_drift_bytes
required
integer format: int64
remaining_bytes
required

Node allowance remaining, floored at zero.

integer format: int64
service_id
required
string format: uuid
traffic_batches

Traffic packs in expiry order. Old traffic keeps its deadline; new traffic lasts 30 days.

Array<object>
object
expires_at
required
string format: date-time
granted_bytes
required
integer format: int64
id
required
string format: uuid
remaining_bytes
required
integer format: int64
usage_source
required

Billing usage comes from durable, deduplicated node byte counters.

string
Allowed values: node
Example
{
  "provider_usage_informational": true,
  "reconciliation": {
    "status": "baseline"
  },
  "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"
}