List recent automatic halt and warn rows for a deployment

GET

/v1/apps/{appName}/deployments/{deploymentName}/halt-history

const url = 'https://api.aetherpush.com/v1/apps/example/deployments/example/halt-history?limit=50&kind=halt';
const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};

try {
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error(error);
}

curl --request GET \
  --url 'https://api.aetherpush.com/v1/apps/example/deployments/example/halt-history?limit=50&kind=halt' \
  --header 'Authorization: Bearer <token>'

Returns recent automatic halt events and warn claims for a deployment the caller can already read (app.read). Halt rows come from deployment_release_halt_events, plus unadopted legacy rows in deployment_release_halts that have no event yet. Warn rows come from deployment_release_warns. Newest first.

Device and threshold fields are the snapshot the auto-halt job stored when it claimed the row. All five are present together, or all five are null. Null means the row predates the audit trail and the gate cannot be recomputed from the response. Do not treat null as zero.

overriddenAt is the first time an operator re-enabled the package after an automatic halt, or null. It is not per-event.

An empty list is 200 { items: [] }. Unknown app, a caller who is not a member, and unknown deployment are 404 with the same bodies as other management GETs. A server that does not mount this path answers { error: "Route not found" }.

Requires the app.read app permission.

Authorizations

accessKeyAuth
apiKeyAuth
read

Parameters

Path Parameters

appName

required

string

deploymentName

required

string

Query Parameters

limit

integer

default: 50 >= 1 <= 100

kind

string

Allowed values: halt warn

label

string

/^v[1-9][0-9]{0,8}$/

Responses

200

Recent halt and warn rows, possibly empty.

application/json

object

items

required

Array<object>

object

kind

required

string

Allowed values: halt warn

label

required

string

>= 1 characters <= 50 characters

occurredAt

required

string format: date-time

servedDevices

required

integer | null

failedDevices

required

integer | null

thresholdFailureRate

required

number | null

> 0 <= 1

thresholdMinFailures

required

integer | null

>= 1

thresholdMinReports

required

integer | null

>= 1

failedCount

required

integer

succeededCount

required

integer

ordinal

required

Halt event ordinal on the package, 1-based. Null on warn rows. Unadopted legacy claim rows are ordinal 1.

integer | null

>= 1

generation

required

packages.auto_halt_generation at claim time, on halt and warn rows alike. Unadopted legacy claim rows are generation 0.

integer | null

overriddenAt

required

First package-level override stamp from deployment_release_halts.overridden_at, or null if the package was never re-enabled after an automatic halt. Not per-event: a later halt on the same package still carries this first stamp.

string | null format: date-time

Example

{
  "items": [
    {
      "kind": "halt",
      "label": "v3",
      "occurredAt": "2026-09-16T12:00:00.000Z",
      "servedDevices": 600,
      "failedDevices": 400,
      "thresholdFailureRate": 0.5,
      "thresholdMinFailures": 100,
      "thresholdMinReports": 500,
      "failedCount": 410,
      "succeededCount": 190,
      "ordinal": 1,
      "generation": 0,
      "overriddenAt": null
    }
  ]
}

400

Malformed limit, kind, or label.

application/json

Error

Standard error envelope. code is the stable machine identifier for client branching and i18n. The wording of error is a human-readable fallback and is not part of the contract. Specialized responses keep narrower code enums where clients already branch on them.

object

error

required

Human-readable error message.

string

code

required

Stable machine code. Prefer this over matching on error. The values this API can answer with are listed in the ApiErrorCode schema of the raw document at https://api.aetherpush.com/openapi.yaml. The field stays an open string here so that a release adding a value does not invalidate this response.

string

requestId

Unique identifier for the request, also exposed as the X-Request-Id response header.

string

Example

{
  "error": "The requested resource was not found.",
  "code": "not_found",
  "requestId": "req_abc123"
}

401

Unauthenticated.

application/json

Error

object

error

required

Human-readable error message.

string

code

required

string

requestId

Unique identifier for the request, also exposed as the X-Request-Id response header.

string

Example

{
  "error": "The requested resource was not found.",
  "code": "not_found",
  "requestId": "req_abc123"
}

403

The API key’s scopes do not grant read, which answers required_scopes. A refusal raised before the route is reached, such as a request that did not arrive through the trusted edge, answers a plain error instead.

application/json

One of:

Error
InsufficientScopesError

Error

object

error

required

Human-readable error message.

string

code

required

string

requestId

Unique identifier for the request, also exposed as the X-Request-Id response header.

string

InsufficientScopesError

Returned when an API key’s scopes do not grant the scope a management route requires. required_scopes lists what the route asked for, not what the key holds. Access keys and login sessions carry wildcard scope and pass the check without reaching this response, so only apiKeyAuth callers receive it. A key whose only scope is keys gets this on every management route, because that scope grants nothing, which is also why keys never appears in required_scopes.

object

error

required

string

code

required

string

Allowed values: insufficient_scopes

required_scopes

required

The scopes the route requires. Only these three appear: no management route requires keys.

Array<string>

Allowed values: read deploy apps

requestId

string

Examples

The API key's scopes do not grant read

{
  "error": "Insufficient permissions",
  "code": "insufficient_scopes",
  "required_scopes": [
    "read"
  ],
  "requestId": "req_abc123"
}

Refused before the route, here by the trusted edge

{
  "error": "Forbidden",
  "code": "forbidden",
  "requestId": "req_abc123"
}

404

App or deployment not found. The same body is used when the caller is not a member. An empty history is 200, not 404.

application/json

Error

object

error

required

Human-readable error message.

string

code

required

string

requestId

Unique identifier for the request, also exposed as the X-Request-Id response header.

string

Example

{
  "error": "The requested resource was not found.",
  "code": "not_found",
  "requestId": "req_abc123"
}

429

The tenant’s per-minute management API budget is spent. Retry-After and X-RateLimit-* say when to retry. This is not a plan quota: quota 429s use the Error envelope and do not set Retry-After.

application/json

RateLimitError

Returned with HTTP 429 when an endpoint-specific rate limit is hit, including the per-tenant management API budget. Not the process-wide address limiter (see GlobalAddressRateLimitErrorResponse). retryAfterSeconds indicates how long the client should wait before retrying, and matches the Retry-After header when that header is set. code names the limit that fired so clients can translate without matching on error.

object

error

required

string

code

required

string

retryAfterSeconds

required

integer

>= 1

requestId

string

Example

{
  "error": "Rate limit exceeded",
  "code": "tenant_rate_limit_exceeded",
  "retryAfterSeconds": 60
}

Headers

Retry-After

integer

>= 1

Seconds until the tenant window resets.