Servers

Server Model

Fields

Field

Type

Description
object
"server"
id
string
project_id
string
project_name
string Display name of that project.
team_id
string
name
string | null Generated friendly name, for example swift-hawk.
sku
string The server's size, as a named bundle of CPU and memory, for example v1-1cpu-2gb.
status
Lifecycle state: provisioning until the server first comes up, then active. A paused free-trial server is draining while it finishes the data it accepted, then idle. A server removed by scaling down is terminating until it has finished that data and been deleted.
provisioning_phase
| null Why provisioning is still in flight (e.g. "awaiting_capacity"); null once active.
ordinal
number The server's stable position in the project's fleet, starting at 0.
created_at
updated_at
heartbeat_at
| null When the server last reported its vitals. Servers report every 30 seconds; null means it has never reported.
cpu_percent
number CPU usage the server last reported, from 0 to 100. Zero until the first report.
memory_percent
number Memory usage the server last reported, from 0 to 100. Zero until the first report.
spool_percent
number | null Actual PVC fullness 0-100, derived as max(bytes, inodes), or null before the first heartbeat.
spool_bytes_percent
number | null Actual PVC byte fullness 0-100, or null before the first heartbeat.
spool_inodes_percent
number | null Actual PVC inode (file-count) fullness 0-100, or null before the first heartbeat.

Server Event Model

Fields

Field

Type

Description
object
"server_rollout_event"
id
string
project_id
string
started_at
When the deploy of the project's servers began.
completed_at
| null When the deploy finished; null while it is still in progress.
image_tag
string | null Version tag the deploy moves the project's servers to.
phase
string | null The most recent step the deploy reached; null before the first step is recorded.

List Servers

Endpoint

Retrieve a list of servers in a project.

servers:read
GET
/v1/projects/:project_id/servers

Path Parameters

Field

Type

Description
project_id
string Unique identifier of the project.

Query Parameters

Field

Type

Description
order_by
string Field used to order the servers. Defaults to "created_at". Accepted values: "created_at","status".
status
Filter by server status.
limit
number Maximum number of items to return. Defaults to 25. Minimum: 1. Maximum: 200.
after
string Cursor from pagination.next_cursor of a previous response. Returns the resources after that page.
before
string Cursor from pagination.prev_cursor of a previous response. Returns the resources before that page.
sort
string Sort direction for the result set. Defaults to "desc". Accepted values: "asc","desc".

Comments

  • A server is a dedicated machine that receives and processes the project's data. Every project runs its own fleet.
  • A server that is still coming up is returned with a status of provisioning, and a server on its way out with a status of terminating.
  • after and before are mutually exclusive.

Response

200 
{
  message: string;
  data: Server[];
  status: 200;
  error: null;
  pagination: Pagination;
  endpoint: string;
}

Retrieve Server

Endpoint

Retrieve a single server.

servers:read
GET
/v1/projects/:project_id/servers/:server_id

Path Parameters

Field

Type

Description
project_id
string Unique identifier of the project.
server_id
string Unique identifier of the server.

Response

200 
{
  message: string;
  data: Server;
  status: 200;
  error: null;
  pagination: null;
  endpoint: string;
}

Scale Servers

Endpoint

Scale a project's fleet to a desired total number of servers.

servers:write
POST
/v1/projects/:project_id/servers

Path Parameters

Field

Type

Description
project_id
string Unique identifier of the project.

Request Body

Field

Type

Requirement

Description
count
integer
Required
Total number of servers the project should run after this request. This is the desired total, not the number of servers to add or remove. The maximum is the team's per-project server limit, which is set by its plan. Minimum: 0.

Comments

  • count is the total number of servers the project should end up running, not the number to add. A project already running two servers reaches three by sending count: 3.
  • Scaling down is the same call with a lower count, and count: 0 takes the whole fleet down. Tailglow chooses which servers to retire and drains them first, so they stay in the response with a status of terminating until they finish.
  • There is no endpoint that deletes an individual server. Removing capacity is always a scale request with a lower count.
  • Scaling up requires the team to have a payment method, and count must stay within the team's per-project server limit.
  • The response is the project's whole fleet after the request, not only the servers that changed.
  • Requesting the count the project already runs, with nothing in flight, returns a 409.
  • During a platform update, a scale request is queued and answered with a 202; it is applied once the update finishes, and the project's queued_server_count shows it meanwhile. A project that has no servers yet still gets its first server immediately.
  • Adding servers to a project that has not finished moving to the current platform version is queued the same way, even with no update in progress. Removing servers is not held back by it.
  • Requesting the count the project currently runs while a change is queued cancels the queued change, or returns a 409 if that change has already started. A newer request replaces an older queued one.

Response 200

200 
{
  message: string;
  data: Server[];
  status: 200;
  error: null;
  pagination: Pagination;
  endpoint: string;
}

Response 202

202 
{
  message: string;
  data: Server[];
  status: 202;
  error: null;
  pagination: Pagination;
  endpoint: string;
}

Update Server

Endpoint

Rename a server.

servers:write
POST
/v1/projects/:project_id/servers/:server_id

Path Parameters

Field

Type

Description
project_id
string Unique identifier of the project.
server_id
string Unique identifier of the server.

Request Body

Field

Type

Requirement

Description
name
string
Required
Display name for the server. Minimum length: 1. Maximum length: 64.

Comments

  • name is the only editable field on a server. It is a display label and does not change how data is routed or how much capacity the server has.
  • Renaming never adds or removes servers. Use POST /v1/projects/:project_id/servers to change how many servers the project runs.

Response

200 
{
  message: string;
  data: Server;
  status: 200;
  error: null;
  pagination: null;
  endpoint: string;
}

Retrieve Server Vitals

Endpoint

Retrieve CPU, memory, and buffer usage for a server over a time range.

servers:read
GET
/v1/projects/:project_id/servers/:server_id/vitals

Path Parameters

Field

Type

Description
project_id
string Unique identifier of the project.
server_id
string Unique identifier of the server.

Query Parameters

Field

Type

Description
start_at
Start time (ISO format, default: 12 hours ago).
end_at
End time (ISO format, default: now).
interval
string Aggregation interval. Defaults to "minute". Accepted values: "minute","hour".

Comments

  • The response carries Worker CPU, Worker Memory, Buffer, Bytes, and Inodes series, plus ingress CPU and memory when available, bucketed by interval.
  • Older points come from archived data and recent points come from the running server, stitched into one continuous timeline. A server replaced by a platform deploy does not break the series.
  • Without start_at and end_at the range is the last 12 hours.

Response

200 
{
  message: string;
  data: TimeseriesAggregation;
  status: 200;
  error: null;
  pagination: null;
  endpoint: string;
}

Retrieve Server Pipeline

Endpoint

Retrieve queue depth, throughput, and error counts for a server over a time range.

servers:read
GET
/v1/projects/:project_id/servers/:server_id/pipeline

Path Parameters

Field

Type

Description
project_id
string Unique identifier of the project.
server_id
string Unique identifier of the server.

Query Parameters

Field

Type

Description
start_at
Start time (ISO format, default: 12 hours ago).
end_at
End time (ISO format, default: now).
interval
string Aggregation interval. Defaults to "minute". Accepted values: "minute","hour".

Comments

  • Pending averages valid queued records, Throughput counts drained records, and Errors counts rejected requests and dropped frames. Older pending history without record counts is unknown.
  • Takes the same range and interval parameters as the vitals endpoint, so the two can be read over the same window.
  • Without start_at and end_at the range is the last 12 hours.

Response

200 
{
  message: string;
  data: TimeseriesAggregation;
  status: 200;
  error: null;
  pagination: null;
  endpoint: string;
}

List Server Events

Endpoint

Retrieve the platform events recorded for a server's project over a time range.

servers:read
GET
/v1/projects/:project_id/servers/:server_id/events

Path Parameters

Field

Type

Description
project_id
string Unique identifier of the project.
server_id
string Unique identifier of the server.

Query Parameters

Field

Type

Requirement

Description
start_at
Required
Earliest event date and time to return (ISO format).
end_at
Required
Latest event date and time to return (ISO format).
type
string
Optional
Filter by event type. Accepted values: "rollout".
limit
number
Optional
Maximum number of items to return. Defaults to 25. Minimum: 1. Maximum: 200.
after
string
Optional
Cursor from pagination.next_cursor of a previous response. Returns the resources after that page.
before
string
Optional
Cursor from pagination.prev_cursor of a previous response. Returns the resources before that page.
sort
string
Optional
Sort direction for the result set. Defaults to "desc". Accepted values: "asc","desc".

Comments

  • An event is a Tailglow deploy of the project's servers. Requesting events over the same window as the vitals and pipeline endpoints shows whether a change in those charts lines up with a deploy.
  • start_at and end_at are both required.
  • An event whose completed_at is null is still in progress.
  • Events belong to the project, so every server in the project returns the same list.
  • after and before are mutually exclusive.

Response

200 
{
  message: string;
  data: ServerRolloutEvent[];
  status: 200;
  error: null;
  pagination: Pagination;
  endpoint: string;
}

Referenced Types

ISODateString

An ISO 8601 date-time string returned at the JSON API boundary.

ServerStatus

provisioning
active
upgrading
draining
idle
terminating

ServerProvisioningPhase

allocating
awaiting_capacity
attaching_storage
pulling_image
starting