No matching sections.

Instant checks

An instant check runs now, from the same distributed fleet your monitors run on, and is gone when you have read it. Use it to test a url before you monitor it, verify a fix, or run a diagnostic - without creating a permanent monitor, and without spending a monitor slot.

Start a check

POST /check, scope check:write. The only member you really need is the address:

curl -X POST 'https://api2.host-tracker.com/check' \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{ "url": "https://example.com", "type": "http" }'

{
  "id": "3f0a…-…",
  "dbId": 2,
  "retryAfter": 5,
  "estimatedDurationSec": 20,
  "resultUrl": "/check/2/3f0a…-…",
  "created": 1785712608
}

retryAfter and estimatedDurationSec are the poll contract, in seconds: wait retryAfter before the first poll, and expect the whole thing to take about estimatedDurationSec. They differ per check type - a ping concludes in a moment, a waterfall does not.

Poll it to a result

GET /check/{dbId}/{id}, scope check:read. Poll until state is done:

{
  "id": "3f0a…-…", "dbId": 2,
  "state": "running",          // running | done
  "url": "https://example.com",
  "type": "http",
  "created": 1785712608,
  "doneAt": null,
  "retryAfter": 3,
  "events": [ /* the locations that have reported so far */ ]
}

The response is incremental: events[] grows as locations report, so a poll before the end is useful rather than empty. retryAfter comes back on each non-terminal poll; when state is done, doneAt is stamped and there is nothing left to wait for.

Per-location events

An instant check is not one answer - it is one answer per monitoring location, which is the whole point of running it on the fleet rather than curling from your laptop. Each entry of events[] is one location's result:

A check where some locations succeed and others fail is the normal, interesting case - it is a routing or regional problem, and it is visible here and nowhere else.

What you can check

GET /check/type is anonymous - no token - and lists every instant-check type with its label, description, an example address, and its own retryAfter / estimatedDurationSec. Read it rather than hardcoding the list.

Today's vocabulary for type:

httppingporttracednsdnsblwhoiswebRiskrusRegBLcrawlwaterfall

Omitting type means http. A row's experimental flag marks a type that may still change, and options carries the type's own extra members where it has any - dnsQuery (which record types a dns check asks for) and deviceEmulation (which device profile a waterfall check's browser emulates) are the two on the request body itself.

Choosing locations

By default a check runs from every location your account may use. Three members narrow that, and they are the same vocabulary a monitor uses:

GET /agent/pool and GET /agent - both anonymous, no token - are where the pool and location names come from. See Monitors for the same clause shape in its permanent form.

History

GET /check lists the account's past instant checks, cursor-paged, narrowed by from/to and type. It is ordered newest-first by design and takes no sort - see the query surface.

Instant check or monitor?