API
Measurements
Run an on-demand measurement across residential or datacenter vantages and receive results in a single HTTP call.
On this page
Start a measurement
POST/v1/measurements
Answers 202 with the measurement id, requested and assigned node counts, and credits_reserved.
| Field | Required | What it is |
|---|---|---|
type | Yes | http, tcp_connect or icmp_ping. |
target | Yes | A hostname or an IP address (not a full URL; pass HTTP paths in params.path). |
port | No | TCP destination port. Unverified targets may use 80, 443, 8080, 8443; verified targets may use any non-restricted port. |
family | No | ipv4 or ipv6. |
locations | No | Up to 10 selectors { country, limit, network, asn }. country is an ISO-3166-1 alpha-2 code or ANY. network filters by any, residential, datacenter, or mobile. asn pins a specific autonomous system number. |
limit | No | Default node count per location (1..10). |
max_credits | No | Maximum credits this measurement may reserve. Returns 422 max_credits_exceeded if exceeded. |
params | No | Check-specific parameters. See defaults below. |
{
"type": "http",
"target": "example.com",
"max_credits": 5,
"locations": [
{ "country": "DE", "limit": 2, "network": "residential" },
{ "country": "US", "limit": 1, "network": "datacenter", "asn": 13335 }
],
"params": { "method": "HEAD", "path": "/" }
}
One measurement can request up to 10 locations, 10 nodes per location, and 50 nodes in total. Credits are reserved only for assigned nodes and settled automatically when probes complete or time out, releasing any unused shortfall. Whenever 0 probes succeed (outcome == "ok"), credits_charged is guaranteed 0.
Read results (with synchronous ?wait=)
GET/v1/measurements/{id}?wait=10
Returns the measurement and its per-node results. Pass ?wait=1..15 (seconds) to long-poll until all assigned probes finish in one HTTP call.
curl -sS "https://api.hopbits.io/v1/measurements/$MEAS_ID?wait=10" \
-H "Authorization: Bearer $HOPBITS_KEY"
| Field | What it is |
|---|---|
status | in-progress while nodes are probing, or finished once complete. |
requested, assigned | How many vantages were requested and how many online nodes took the job. |
credits_reserved, credits_charged | Credits reserved on dispatch and final settled cost after completion (0 whenever 0 probes succeed). |
failure_reason, retry_after_seconds, diagnostic_message | Optional diagnostic fields emitted when probes are blocked or fail (for example "rate_limited" with retry_after_seconds: 300 on unverified per-target cooldown, "no_capable_nodes", "target_denied", or "timeout"). |
params | Effective check parameters, including applied defaults. |
results | Per-node array containing privacy-safe node pseudonym, country, asn, network_class (residential, datacenter, mobile), outcome (ok, rate_limited, timeout, not_run, ...), optional error, measured_at, and check result timings. |
Default options
| Type | Defaults |
|---|---|
http | method GET, scheme https, path /, timeout_ms 10000, port 443. |
tcp_connect | timeout_ms 5000, port 443. |
icmp_ping | interval_ms 1000, timeout_ms 2000, packets 3..16. |
Live network coverage & capabilities
GET/v1/kinds
Lists registered measurement kinds, transports, allowed ports, and per-probe credit costs.
GET/v1/network
Returns exact live node counts globally and per country, broken down by residential, datacenter, mobile, distinct ASNs, and capabilities. Never exposes node IDs or IP addresses.
GET/v1/coverage
Alias of GET /v1/network returning the same live country and network-class breakdown.
{
"online_nodes": 3,
"online": "3",
"residential_nodes": 3,
"datacenter_nodes": 0,
"mobile_nodes": 0,
"countries": [
{
"country": "LT",
"count": "1",
"nodes": 1,
"residential": 1,
"datacenter": 0,
"mobile": 0,
"asns": 1,
"capabilities": ["http", "icmp_ping", "tcp_connect"]
},
{
"country": "RO",
"count": "2",
"nodes": 2,
"residential": 2,
"datacenter": 0,
"mobile": 0,
"asns": 2,
"capabilities": ["http", "icmp_ping", "tcp_connect"]
}
]
}