Hosts API

Read host telemetry from your API's servers: the server list, fleet summary, metric series, per-server traffic, saturation, restarts and latency correlation.

This page as Markdown

When host telemetry is on for a bucket, each server running the SDK reports CPU, memory, event-loop and garbage-collection health. Separately, every captured request records which server handled it. These operations read both: which servers you have and how they are doing, which one is slower than its peers, at what concurrency latency starts to climb, and whether a slowdown lined up with a server in trouble. See Servers for the same views in the app, and Update bucket to turn host telemetry on.

Plan: servers report health on plans that include Host telemetry, at the reporting interval the plan allows. Per-server traffic, saturation, server endpoints and stability come from the requests themselves, so they work without host telemetry. Permissions: any member, or a user or administrator API token.

Common query parameters

Every operation on this page takes these filters:

environmentSid (query, string): The environment to report on. Required unless you pass instanceSid: a server belongs to exactly one environment, and mixing environments would pool unrelated fleets.
bucketSid (query, string): Only servers sending traffic to this bucket.
instanceSid (query, string): Only one server process. A process gets a new instance id each time it starts.
machineId (query, string): Only one machine, across restarts.
startTime (query, string): Start of the range (ISO 8601, UTC, ending in Z). Required everywhere except List servers.
endTime (query, string): End of the range. Required everywhere except List servers.

List servers

GET https://api.apitraffic.io/v1/accounts/{accountSid}/hosts

Returns the servers that have reported host telemetry, with their latest readings. Servers that stopped reporting stay in the list with the time they went quiet, so a server that crashed overnight does not just disappear.

Path parameters

accountSid (path, string, required): The account identifier.

Query parameters

The common filters, plus:

limit (query, integer): Servers to return, 1 to 500.

Response

sourceState (string): absent (no server has ever reported), pending (being set up) or ready.
instances (object[]): One entry per server process.

instance

instanceSid (string): The process.
machineId (string): The machine, stable across restarts.
displayName (string): A readable name for the server.
hostname (string): Host or pod name, when identity capture is on.
serviceName (string): Your service’s name, and serviceVersion its version.
sdkName (string): The SDK, with sdkVersion, nodeVersion and platform.
region (string): The region, when reported.
gitSha (string): The deployed commit, when reported.
bucketSid (string): The bucket, and environmentSid the environment.
cadence (string): How often it was reporting: quiet, normal or elevated.
firstSeen (string): First report, and lastSeen the latest.
sampleCount (number): Reports received.
cpuTotalPct (number): Latest CPU use, percent.
eventLoopDelayP99Ms (number): Event-loop delay, 99th percentile.
eventLoopUtilization (number): Event-loop utilization, 0 to 1.
heapUsedPct (number): Heap in use, percent of the limit.
rssBytes (number): Resident memory.
memUsedPct (number): Machine memory in use, percent.
loadAvg1 (number): One-minute load average.
inFlightRequests (number): Requests in progress.
uptimeSec (number): Process uptime.
configSource (string): Where the process got the configuration it runs on: live, cache, mirror, pinned (its offline definitions) or none. pinned on a running server usually means it cannot reach ApiTraffic.
pinnedConfigHash (string): The configHash of the offline definitions file on its disk, when there is one. Compare it with Get config hash to see whether the file is stale.

bash

curl "https://api.apitraffic.io/v1/accounts/acc_2mXq7RbT4kPz9WvN3cHd8LsYfQa/hosts?environmentSid=prd7k2" \
  -H "Authorization: Bearer $APITRAFFIC_TOKEN"

const accountSid = 'acc_2mXq7RbT4kPz9WvN3cHd8LsYfQa';
const response = await fetch(`https://api.apitraffic.io/v1/accounts/${accountSid}/hosts?environmentSid=prd7k2`, {
  headers: { Authorization: `Bearer ${process.env.APITRAFFIC_TOKEN}` },
});
const { instances } = await response.json();

json

{
  "sourceState": "ready",
  "instances": [
    {
      "instanceSid": "ins_k8f2a1",
      "machineId": "m_7f3a91c2e4",
      "displayName": "acme-api-1",
      "hostname": "acme-api-1",
      "serviceName": "acme-store-api",
      "serviceVersion": "v2026.10.20",
      "sdkName": "@apitraffic/express",
      "sdkVersion": "2.4.0",
      "nodeVersion": "22.11.0",
      "platform": "linux",
      "region": "us-east-1",
      "gitSha": "9d3c5a1e7b2f4d6a8c0e1b3d5f7a9c2e4b6d8f0a",
      "bucketSid": "k3m9p2x",
      "environmentSid": "prd7k2",
      "cadence": "normal",
      "firstSeen": "2026-10-20T10:01:12.000Z",
      "lastSeen": "2026-10-20T11:58:00.000Z",
      "sampleCount": 59,
      "cpuTotalPct": 21.4,
      "eventLoopDelayP99Ms": 11.2,
      "eventLoopUtilization": 0.18,
      "heapUsedPct": 41.7,
      "rssBytes": 182452224,
      "memUsedPct": 63.1,
      "loadAvg1": 0.42,
      "inFlightRequests": 3,
      "uptimeSec": 7008,
      "configSource": "live",
      "pinnedConfigHash": "sha256:9f2b1c4a7e08d3f5b6c1a2d4e8f09b3c5d7e1f2a4b6c8d0e2f4a6b8c0d2e4f6a"
    }
  ]
}

Get fleet summary

GET https://api.apitraffic.io/v1/accounts/{accountSid}/hosts/summary

Returns fleet-wide averages and peaks for a time range.

Path parameters

accountSid (path, string, required): The account identifier.

Query parameters

The common filters.

Response

instanceCount (number): Server processes seen, and machineCount machines.
sampleCount (number): Reports received.
avgCpuTotalPct (number): Average CPU, with maxCpuTotalPct the peak.
avgEventLoopDelayP99Ms (number): Average event-loop delay (p99), with maxEventLoopDelayP99Ms.
avgHeapUsedPct (number): Average heap use, with maxHeapUsedPct.
avgMemUsedPct (number): Average machine memory use.
totalRequests (number): Requests the fleet handled.

bash

curl -G https://api.apitraffic.io/v1/accounts/acc_2mXq7RbT4kPz9WvN3cHd8LsYfQa/hosts/summary \
  -H "Authorization: Bearer $APITRAFFIC_TOKEN" \
  --data-urlencode 'environmentSid=prd7k2' \
  --data-urlencode 'startTime=2026-10-19T00:00:00.000Z' \
  --data-urlencode 'endTime=2026-10-20T00:00:00.000Z'

const accountSid = 'acc_2mXq7RbT4kPz9WvN3cHd8LsYfQa';
const params = new URLSearchParams({
  environmentSid: 'prd7k2',
  startTime: '2026-10-19T00:00:00.000Z',
  endTime: '2026-10-20T00:00:00.000Z',
});
const response = await fetch(`https://api.apitraffic.io/v1/accounts/${accountSid}/hosts/summary?${params}`, {
  headers: { Authorization: `Bearer ${process.env.APITRAFFIC_TOKEN}` },
});
const summary = await response.json();

json

{
  "instanceCount": 4,
  "machineCount": 2,
  "sampleCount": 1438,
  "avgCpuTotalPct": 18.9,
  "maxCpuTotalPct": 71.2,
  "avgEventLoopDelayP99Ms": 12.4,
  "maxEventLoopDelayP99Ms": 188.0,
  "avgHeapUsedPct": 39.5,
  "maxHeapUsedPct": 68.3,
  "avgMemUsedPct": 61.0,
  "totalRequests": 10412
}

Get host metric series

GET https://api.apitraffic.io/v1/accounts/{accountSid}/hosts/timeseries

Charts one host metric over time, for the fleet or per server. Every point has both an average and a peak, because an average across many servers hides the one that is pinned.

Path parameters

accountSid (path, string, required): The account identifier.

Query parameters

The common filters, plus:

metric (query, string, required): cpu, eventLoopDelay, eventLoopDelayMean, eventLoopUtilization, heapUsedPct, rssBytes, memUsedPct, loadAvg1, gcPauseTotalMs, gcMajorCount, inFlight, requests or activeHandles.
bucket (query, string): Period width: minute, 10min, hour, 2hr, day or month. Defaults to minute for a range of an hour or less when servers report at least once a minute, otherwise 10min.
perInstance (query, boolean): true returns one series per server instead of a fleet aggregate.
limit (query, integer): Most rows, 1 to 500.

Response

points (object[]): One entry per period (and server, with perInstance): period, instanceSid, value (the average), peak (the worst reading) and sampleCount.
truncated (boolean): Present and true when a per-server series had more rows than the plan allows; the newest are returned.

bash

curl -G https://api.apitraffic.io/v1/accounts/acc_2mXq7RbT4kPz9WvN3cHd8LsYfQa/hosts/timeseries \
  -H "Authorization: Bearer $APITRAFFIC_TOKEN" \
  --data-urlencode 'environmentSid=prd7k2' \
  --data-urlencode 'metric=eventLoopDelay' \
  --data-urlencode 'perInstance=true' \
  --data-urlencode 'startTime=2026-10-19T13:00:00.000Z' \
  --data-urlencode 'endTime=2026-10-19T16:00:00.000Z'

const accountSid = 'acc_2mXq7RbT4kPz9WvN3cHd8LsYfQa';
const params = new URLSearchParams({
  environmentSid: 'prd7k2',
  metric: 'eventLoopDelay',
  perInstance: 'true',
  startTime: '2026-10-19T13:00:00.000Z',
  endTime: '2026-10-19T16:00:00.000Z',
});
const response = await fetch(`https://api.apitraffic.io/v1/accounts/${accountSid}/hosts/timeseries?${params}`, {
  headers: { Authorization: `Bearer ${process.env.APITRAFFIC_TOKEN}` },
});
const { points } = await response.json();

json

{
  "points": [
    { "period": "2026-10-19T14:00:00.000Z", "instanceSid": "ins_k8f2a1", "value": 14.2, "peak": 61.0, "sampleCount": 5 },
    { "period": "2026-10-19T14:00:00.000Z", "instanceSid": "ins_p3d9q7", "value": 12.8, "peak": 40.5, "sampleCount": 5 }
  ]
}

Get per-server traffic

GET https://api.apitraffic.io/v1/accounts/{accountSid}/hosts/traffic

Returns traffic, errors and latency per server, and flags servers that are much slower than their peers. Each server is compared with the median, so a slow server cannot drag its own baseline.

Path parameters

accountSid (path, string, required): The account identifier.

Query parameters

The common filters, plus limit (1 to 500).

Response

instances (object[]): One entry per server.

instance

instanceSid (string): The process, with machineId.
requestCount (number): Requests, split into inboundCount and outboundCount.
serverErrorCount (number): 5xx responses, and clientErrorCount 4xx.
errorRate (number): Server errors as a percentage of this server’s requests.
averageDurationMs (number): Average duration, with p50Ms, p95Ms, p99Ms and maxDurationMs.
endpointCount (number): Distinct endpoints served.
averageInFlight (number): Average concurrent requests, and peakInFlight the most.
fleetP95Ms (number): The median p95 across servers with meaningful traffic.
latencyOutlier (boolean): true when this server is much slower than its peers.
firstSeen (string): First request, and lastSeen the latest.
displayName (string | null): With host telemetry on: displayName, hostname, serviceName, serviceVersion, sdkVersion, region, gitSha, cpuTotalPct, heapUsedPct and eventLoopDelayP99Ms.

bash

curl -G https://api.apitraffic.io/v1/accounts/acc_2mXq7RbT4kPz9WvN3cHd8LsYfQa/hosts/traffic \
  -H "Authorization: Bearer $APITRAFFIC_TOKEN" \
  --data-urlencode 'environmentSid=prd7k2' \
  --data-urlencode 'startTime=2026-10-19T14:00:00.000Z' \
  --data-urlencode 'endTime=2026-10-19T15:00:00.000Z'

const accountSid = 'acc_2mXq7RbT4kPz9WvN3cHd8LsYfQa';
const params = new URLSearchParams({
  environmentSid: 'prd7k2',
  startTime: '2026-10-19T14:00:00.000Z',
  endTime: '2026-10-19T15:00:00.000Z',
});
const response = await fetch(`https://api.apitraffic.io/v1/accounts/${accountSid}/hosts/traffic?${params}`, {
  headers: { Authorization: `Bearer ${process.env.APITRAFFIC_TOKEN}` },
});
const { instances } = await response.json();
const outliers = instances.filter((instance) => instance.latencyOutlier);

json

{
  "instances": [
    {
      "instanceSid": "ins_k8f2a1",
      "machineId": "m_7f3a91c2e4",
      "requestCount": 361,
      "inboundCount": 301,
      "outboundCount": 60,
      "serverErrorCount": 33,
      "clientErrorCount": 12,
      "errorRate": 9.14,
      "averageDurationMs": 402.6,
      "p50Ms": 88,
      "p95Ms": 3910,
      "p99Ms": 4080,
      "maxDurationMs": 4120,
      "endpointCount": 14,
      "averageInFlight": 2.1,
      "peakInFlight": 11,
      "firstSeen": "2026-10-19T14:00:01.000Z",
      "lastSeen": "2026-10-19T14:59:58.000Z",
      "fleetP95Ms": 3860,
      "latencyOutlier": false,
      "displayName": "acme-api-1",
      "hostname": "acme-api-1",
      "serviceName": "acme-store-api",
      "serviceVersion": "v2026.10.19",
      "sdkVersion": "2.4.0",
      "region": "us-east-1",
      "gitSha": "4e1b9c7a2d5f8e3b6a0c1d4f7e2a9b5c8d3e6f1a",
      "cpuTotalPct": 24.8,
      "heapUsedPct": 44.1,
      "eventLoopDelayP99Ms": 14.6
    }
  ]
}

Get saturation

GET https://api.apitraffic.io/v1/accounts/{accountSid}/hosts/saturation

Shows latency against how many requests were already running when each request arrived. The point where latency starts climbing (the knee) is the concurrency at which to add capacity.

Path parameters

accountSid (path, string, required): The account identifier.

Query parameters

The common filters.

Response

points (object[]): One entry per concurrency band: concurrency (the band’s upper bound), requestCount (a percentile over few requests is noise), averageDurationMs, p50Ms, p95Ms, p99Ms and serverErrorCount.

bash

curl -G https://api.apitraffic.io/v1/accounts/acc_2mXq7RbT4kPz9WvN3cHd8LsYfQa/hosts/saturation \
  -H "Authorization: Bearer $APITRAFFIC_TOKEN" \
  --data-urlencode 'environmentSid=prd7k2' \
  --data-urlencode 'startTime=2026-10-19T00:00:00.000Z' \
  --data-urlencode 'endTime=2026-10-20T00:00:00.000Z'

const accountSid = 'acc_2mXq7RbT4kPz9WvN3cHd8LsYfQa';
const params = new URLSearchParams({
  environmentSid: 'prd7k2',
  startTime: '2026-10-19T00:00:00.000Z',
  endTime: '2026-10-20T00:00:00.000Z',
});
const response = await fetch(`https://api.apitraffic.io/v1/accounts/${accountSid}/hosts/saturation?${params}`, {
  headers: { Authorization: `Bearer ${process.env.APITRAFFIC_TOKEN}` },
});
const { points } = await response.json();

json

{
  "points": [
    { "concurrency": 1, "requestCount": 6120, "averageDurationMs": 71.4, "p50Ms": 44, "p95Ms": 210, "p99Ms": 620, "serverErrorCount": 41 },
    { "concurrency": 4, "requestCount": 3480, "averageDurationMs": 118.0, "p50Ms": 61, "p95Ms": 390, "p99Ms": 1150, "serverErrorCount": 58 },
    { "concurrency": 8, "requestCount": 790, "averageDurationMs": 402.5, "p50Ms": 140, "p95Ms": 2810, "p99Ms": 3990, "serverErrorCount": 39 }
  ]
}

Get server endpoints

GET https://api.apitraffic.io/v1/accounts/{accountSid}/hosts/endpoints

Returns the endpoints a server handled, busiest first. A fleet normally serves the same mix everywhere, so a server with a different mix points to a routing or deployment problem. Pass instanceSid or machineId to look at one server.

Path parameters

accountSid (path, string, required): The account identifier.

Query parameters

The common filters, plus limit (1 to 500).

Response

endpoints (object[]): One entry per endpoint: endpoint, method, requestCount, averageDurationMs, p95Ms and serverErrorCount.

bash

curl -G https://api.apitraffic.io/v1/accounts/acc_2mXq7RbT4kPz9WvN3cHd8LsYfQa/hosts/endpoints \
  -H "Authorization: Bearer $APITRAFFIC_TOKEN" \
  --data-urlencode 'instanceSid=ins_k8f2a1' \
  --data-urlencode 'startTime=2026-10-19T00:00:00.000Z' \
  --data-urlencode 'endTime=2026-10-20T00:00:00.000Z'

const accountSid = 'acc_2mXq7RbT4kPz9WvN3cHd8LsYfQa';
const params = new URLSearchParams({
  instanceSid: 'ins_k8f2a1',
  startTime: '2026-10-19T00:00:00.000Z',
  endTime: '2026-10-20T00:00:00.000Z',
});
const response = await fetch(`https://api.apitraffic.io/v1/accounts/${accountSid}/hosts/endpoints?${params}`, {
  headers: { Authorization: `Bearer ${process.env.APITRAFFIC_TOKEN}` },
});
const { endpoints } = await response.json();

json

{
  "endpoints": [
    { "endpoint": "/v1/products/{product_id}", "method": "GET", "requestCount": 1544, "averageDurationMs": 47.9, "p95Ms": 140, "serverErrorCount": 0 },
    { "endpoint": "/v1/orders/{order_id}", "method": "GET", "requestCount": 902, "averageDurationMs": 171.3, "p95Ms": 512, "serverErrorCount": 9 }
  ]
}

Get stability

GET https://api.apitraffic.io/v1/accounts/{accountSid}/hosts/stability

Counts restarts per machine. A process gets a new instance id each time it starts while the machine id stays the same, so several instances on one machine in a short time is a crash loop, even if each one looked healthy on its own.

Path parameters

accountSid (path, string, required): The account identifier.

Query parameters

The common filters, plus limit (1 to 500).

Response

machines (object[]): One entry per machine: machineId, instanceCount (processes seen), restartCount (instances beyond the first), requestCount, firstSeen and lastSeen.

bash

curl -G https://api.apitraffic.io/v1/accounts/acc_2mXq7RbT4kPz9WvN3cHd8LsYfQa/hosts/stability \
  -H "Authorization: Bearer $APITRAFFIC_TOKEN" \
  --data-urlencode 'environmentSid=prd7k2' \
  --data-urlencode 'startTime=2026-10-19T00:00:00.000Z' \
  --data-urlencode 'endTime=2026-10-20T00:00:00.000Z'

const accountSid = 'acc_2mXq7RbT4kPz9WvN3cHd8LsYfQa';
const params = new URLSearchParams({
  environmentSid: 'prd7k2',
  startTime: '2026-10-19T00:00:00.000Z',
  endTime: '2026-10-20T00:00:00.000Z',
});
const response = await fetch(`https://api.apitraffic.io/v1/accounts/${accountSid}/hosts/stability?${params}`, {
  headers: { Authorization: `Bearer ${process.env.APITRAFFIC_TOKEN}` },
});
const { machines } = await response.json();

json

{
  "machines": [
    { "machineId": "m_7f3a91c2e4", "instanceCount": 2, "restartCount": 1, "requestCount": 5210, "firstSeen": "2026-10-19T00:00:02.000Z", "lastSeen": "2026-10-19T23:59:58.000Z" },
    { "machineId": "m_2b8d40f6a1", "instanceCount": 2, "restartCount": 1, "requestCount": 5202, "firstSeen": "2026-10-19T00:00:01.000Z", "lastSeen": "2026-10-19T23:59:59.000Z" }
  ]
}

Correlate latency with server health

GET https://api.apitraffic.io/v1/accounts/{accountSid}/hosts/correlate

Puts request latency and server health in the same time periods, to answer “did requests slow down because the servers were in trouble?”.

Path parameters

accountSid (path, string, required): The account identifier.

Query parameters

The common filters, plus bucket (period width, as in Get host metric series) and limit (1 to 500).

Response

points (object[]): One entry per period: period, cpuTotalPct, eventLoopDelayP99Ms, heapUsedPct, requestCount, p95DurationMs and errorCount. A value is null when there was no data for it.

bash

curl -G https://api.apitraffic.io/v1/accounts/acc_2mXq7RbT4kPz9WvN3cHd8LsYfQa/hosts/correlate \
  -H "Authorization: Bearer $APITRAFFIC_TOKEN" \
  --data-urlencode 'environmentSid=prd7k2' \
  --data-urlencode 'startTime=2026-10-19T13:00:00.000Z' \
  --data-urlencode 'endTime=2026-10-19T16:00:00.000Z'

const accountSid = 'acc_2mXq7RbT4kPz9WvN3cHd8LsYfQa';
const params = new URLSearchParams({
  environmentSid: 'prd7k2',
  startTime: '2026-10-19T13:00:00.000Z',
  endTime: '2026-10-19T16:00:00.000Z',
});
const response = await fetch(`https://api.apitraffic.io/v1/accounts/${accountSid}/hosts/correlate?${params}`, {
  headers: { Authorization: `Bearer ${process.env.APITRAFFIC_TOKEN}` },
});
const { points } = await response.json();

json

{
  "points": [
    { "period": "2026-10-19T14:10:00.000Z", "cpuTotalPct": 22.1, "eventLoopDelayP99Ms": 13.0, "heapUsedPct": 43.9, "requestCount": 118, "p95DurationMs": 3950, "errorCount": 12 }
  ]
}

In this example latency rose while CPU and the event loop stayed healthy, which points away from the servers and toward a slow dependency.

Errors

Status	Code	Meaning
`400`	`1000`	A parameter is missing or invalid, for example no `environmentSid` and no `instanceSid`, or an unknown `metric`.
`502`	`5105`	The query failed. Retry.
`503`	`5102`, `5103`, `5104`	Telemetry is temporarily unavailable. Retry after `Retry-After` seconds.
`504`	`5101`	The query took too long. Narrow the range and retry.

Servers: Host telemetry in the app.
Requests API: See which requests a server was running with Get concurrent requests.

Hosts API

Common query parameters #

List servers #

Path parameters #

Query parameters #

Response #

Get fleet summary #

Path parameters #

Query parameters #

Response #

Get host metric series #

Path parameters #

Query parameters #

Response #

Get per-server traffic #

Path parameters #

Query parameters #

Response #

Get saturation #

Path parameters #

Query parameters #

Response #

Get server endpoints #

Path parameters #

Query parameters #

Response #

Get stability #

Path parameters #

Query parameters #

Response #

Correlate latency with server health #

Path parameters #

Query parameters #

Response #

Errors #

Related #

Common query parameters

List servers

Path parameters

Query parameters

Response

Get fleet summary

Path parameters

Query parameters

Response

Get host metric series

Path parameters

Query parameters

Response

Get per-server traffic

Path parameters

Query parameters

Response

Get saturation

Path parameters

Query parameters

Response

Get server endpoints

Path parameters

Query parameters

Response

Get stability

Path parameters

Query parameters

Response

Correlate latency with server health

Path parameters

Query parameters

Response

Errors

Related