---
title: "list_versions"
description: "Generated reference for the management action list_versions: its description, access metadata, payload contract, and registration status."
slug: /reference/actions/list-versions
order: 39
visibility: public
redirects_from: []
---

# list\_versions

Generated automatically from the [published contract sources](/cloud/reference/about/#contract-sources).

A script calls this action over HTTPS at `POST https://tzcloud.turnzero.ai/v1/list_versions`, with a bearer credential and the action's payload as the JSON body. It also accepts `GET`. An MCP connection lists this action as the tool `tzcloud_list_versions`.

OAuth access tokens and minted tokens, including the turnzero command's computer token, are bearer credentials. The action determines which kinds, scopes and grants it accepts ([Sign-in, sessions, and tokens](/cloud/concepts/sign-in-sessions-and-tokens/)).

**Build metadata:** Registered in this build. Registration describes the default dispatcher in this build. It does not guarantee that a caller has the required credential or grant, that a tool is listed for that connection, or that the required service is configured.

## Contract description

This call lists your app's version history, newest first\. These are the version numbers `promote` and `roll_back` take\. Kinds are deploy, promote, or restart\. A restart re\-creates the serving version under current settings, made by `restart_application`, a rename, or the platform\. Each row says whether it serves and is promotable\. `promotable` marks a kept image, without advice to promote\. Once retention deletes its image, promotable is false\. Each environment's serving row gives `kept`, recorded `{ path, sha256 }` pairs or null, for reuse in `deploy_files`\. Version numbers form one sequence per application, shared by development and production\. Each deploy takes the next number\. A promote, rollback, or restart row has the number of the version it applies\.

## More about this action

Each row also gives `harness_hash`, the hash of the runtime harness its image contains, and `harness_current`, whether that harness is the platform's current one\. A promote keeps the harness of the version it promotes, and a new deploy takes the current harness\. Each row also records its step `timings`\. A failed build's outcome includes the last lines of the build's own output\. The serving row also gives `fixes`: `critical` or `high`, the highest severity fixed by the platform's base image updates since its version's base, or null\. It is the same value as `read_status`'s `base.fixes`\.

Each environment's serving row also gives `kept`: its recorded files as `{ path, sha256 }` pairs sorted by path, or null where none were recorded\. Each listed hash can replace `content` for that file in `deploy_files` while the version serves\. Null covers versions deployed before the platform recorded these entries, those deployed through the command, upload or artifact route, and promotes, rollbacks or restarts carrying their null\. Where `kept` is null, a later chat sends every file with `content` or `stored`\. Other rows carry no `kept`\.

Each row gives its environment, number, kind, state, artifact hash, times, and outcome\. An ended row's `result` in `outcome` says how it ended\. Read a failed row's `outcome` for its error and detail and, where the health check failed, its gate evidence\.

## Access and action metadata

```json
{
  "name": "list_versions",
  "resource": "version",
  "tier": "observe",
  "surface": "tzcloud",
  "addresses": [
    "tzcloud"
  ],
  "product": "cloud",
  "clients": [
    "bearer",
    "browser_session"
  ],
  "summary": "An application's version history, newest first: each row's environment, number, kind (deploy, promote, or restart, the last the re-creation of a serving revision under current settings by `restart_application`, a rename, or the platform), state, artifact hash, instants, and outcome. The outcome carries `result`, and the `gate` evidence of a failed health gate or a failed build's last lines. Each row says whether it is serving and whether it is promotable, false once the platform's retention has deleted its image. It carries its step `timings`, and its harness hash with whether that harness is the platform's current one, which a promote keeps and a new deploy takes; the rows are those promotion and rollback name.\n\nEach environment's serving row alone also gives `kept`: its recorded file paths and SHA-256 hashes sorted by path, or null where none were recorded. Each listed hash can replace `content` for that file in `deploy_files` while the version serves.",
  "annotations": {
    "readOnlyHint": true,
    "destructiveHint": false,
    "openWorldHint": false,
    "idempotentHint": true
  }
}
```

## MCP catalog entry

```json
{
  "name": "list_versions",
  "title": "List deployed versions",
  "tier": "observe",
  "scenario": "CHI-L0-09",
  "summary": "This call lists your app's version history, newest first. These are the version numbers `promote` and `roll_back` take. Kinds are deploy, promote, or restart. A restart re-creates the serving version under current settings, made by `restart_application`, a rename, or the platform. Each row says whether it serves and is promotable. `promotable` marks a kept image, without advice to promote. Once retention deletes its image, promotable is false. Each environment's serving row gives `kept`, recorded `{ path, sha256 }` pairs or null, for reuse in `deploy_files`. Version numbers form one sequence per application, shared by development and production. Each deploy takes the next number. A promote, rollback, or restart row has the number of the version it applies.",
  "owners": [
    "PLD-L0-84",
    "PLD-L0-63",
    "PLD-L0-89",
    "PLD-L0-90",
    "PLD-L0-82"
  ]
}
```

## request

| JSON pointer | Description and constraints |
|---|---|
| "" \(root\) | Type: object<br>Required fields: \["application"\] |
| /<wbr>properties/<wbr>application | Your account's application `id` from `list_applications`, not its name or label\.<br><br>Type: string |
| /<wbr>properties/<wbr>environment | Optional\. Narrows the answer to one environment's rows, `development` or `production`; leave it out and you get both environments' rows\.<br><br>Type: string<br>Pattern: ^\(development\|production\)$ |
| /<wbr>properties/<wbr>limit | Optional\. The most rows you get, 1 to 200; 50 by default\.<br><br>Type: integer<br>Minimum: 1<br>Maximum: 200 |
| /<wbr>properties/<wbr>cursor | Optional\. The `next_cursor` of a previous answer\.<br><br>Type: string |

## response

| JSON pointer | Description and constraints |
|---|---|
| "" \(root\) | The application's version history, newest first by start instant\. The `serving` member is true on each environment's serving row, the deployed row that is not retired and has the latest end instant\. The `promotable` member is true on a deployed row whose image the platform's retention has kept\. A row retired by its environment's deletion is not returned\. The `harness_hash` and `harness_current` members state the harness the row's image carries and whether it is the platform's current one — a promote keeps the deploy's harness, a new deploy takes the current one\.<br><br>Each environment's serving row alone also carries `kept`: its recorded file paths and SHA\-256 hashes sorted by path, or null where none were recorded\.<br><br>Type: object<br>Required fields: \["contract\_version","application","versions","next\_cursor"\] |
| /<wbr>properties/<wbr>contract\_version | Required value: 1 |
| /<wbr>properties/<wbr>reference | The short reference the platform recorded your call under: ten lowercase hexadecimal characters, the value in the call’s record row\. Quote it when you report the call\.<br><br>Type: string<br>Pattern: ^\[0\-9a\-f\]\{10\}$ |
| /<wbr>properties/<wbr>application | Type: string |
| /<wbr>properties/<wbr>versions | Type: array |
| /<wbr>properties/<wbr>versions/<wbr>items | Type: object<br>Required fields: \["id","environment","version","kind","state","artifact\_hash","started\_at","ended\_at","outcome","serving","promotable","harness\_hash","harness\_current","rolled\_back\_from"\] |
| /<wbr>properties/<wbr>versions/<wbr>items/<wbr>properties/<wbr>id | Type: string |
| /<wbr>properties/<wbr>versions/<wbr>items/<wbr>properties/<wbr>environment | Type: string<br>Allowed values: \["development","production"\] |
| /<wbr>properties/<wbr>versions/<wbr>items/<wbr>properties/<wbr>version | Type: integer |
| /<wbr>properties/<wbr>versions/<wbr>items/<wbr>properties/<wbr>kind | A deploy writes a row of kind deploy\. A promote or rollback writes a row of kind promote\. A restart writes a row of kind restart, carrying the serving row's number\. A restart is the re\-creation of the environment's serving compute under current settings by `restart_application`, a rename, or the platform\.<br><br>Type: string<br>Allowed values: \["deploy","promote","restart"\] |
| /<wbr>properties/<wbr>versions/<wbr>items/<wbr>properties/<wbr>state | Type: string<br>Allowed values: \["deploying","deployed","failed"\] |
| /<wbr>properties/<wbr>versions/<wbr>items/<wbr>properties/<wbr>artifact\_hash | Type: \["string","null"\] |
| /<wbr>properties/<wbr>versions/<wbr>items/<wbr>properties/<wbr>started\_at | Type: string |
| /<wbr>properties/<wbr>versions/<wbr>items/<wbr>properties/<wbr>ended\_at | Type: \["string","null"\] |
| /<wbr>properties/<wbr>versions/<wbr>items/<wbr>properties/<wbr>outcome | Null while the row is deploying\. On a failed row an object of error, the refusal's name, and detail, its sentence — or the outcome interrupted or superseded — with step, the step the run had reached where the process that ran it ended the row\. On a row failed at the health gate \(health\_gate\_failed\) it also carries gate: probed \(private\_ingress or group\_route, never the address\), timeout\_ms, polls, and probe\_sequence\. The probe\_sequence is a run\-length ledger of at most sixteen \{answer, count\} runs, answer an HTTP status or one of the transport words connection\_refused, name\_not\_resolved, connection\_reset, timed\_out, tls\_failed, and transport\_error\. The gate also carries last \(the last non\-200 answer's status and content\_type, and its body's first 512 bytes with body\_truncated only where answered\_by is application\), null where no HTTP answer was read\. The gate also carries answered\_by \(application, intermediary, nothing, or unknown, the reading at the deadline or at an early end\) and control\_probe \(its outcome and status, refusal, or cause\)\. The gate also carries ended\_early: true for an early end on an own\-process client error or stopping instance\. It is false at the bound and absent on rows written before the member\. The gate's polls\_200 counts the probes whose response was 200; an older row lacks it\. The gate also carries compute: state, and with detail revision \{provisioning, running, health\}, instance \{phase, state, restarts, exit\_code, last\_state\}, and ready, a member \{unavailable: cause\} where its read failed\. The cause is an HTTP status word, a platform error code, or error\. The whole member is \{outcome: unavailable, cause\} where its read failed or overran and \{state: unavailable, reason\} where the seam caught the failure\. The gate also carries console \(outcome as lines, empty, or unavailable; lines, at most forty of at most 512 bytes and 4,096 in all; truncated; since; and cause\)\. read\_status returns the same outcome whole\. No member includes an address, a header value, or the provider\. On a row failed `smoke_path_failed` it carries `smoke` in place of `gate`: path, answer, last, compute, and console\.<br><br>Type: \["object","null"\] |
| /<wbr>properties/<wbr>versions/<wbr>items/<wbr>properties/<wbr>outcome/<wbr>properties/<wbr>result | How the row ended, on every ended row: `succeeded` on a deployed row, `interrupted` where the platform's process stopped or lost the run, `superseded` where a deletion ended it, and `failed` otherwise\.<br><br>On a `succeeded` server run, the declared health path returned 200 three times in a row within the check's bound\. Where it replaced a serving version, the routers' short resolve interval after the switch has passed\. On a server deploy or a promote that is not a rollback and passes a version production does not serve, the check also requested the manifest's smoke paths after the gate passed\. No other path is probed: a failing route shows in `read_status`' `server_errors` once a request reaches it\.<br><br>A serverless run made no health check or smoke check\.<br><br>Type: string<br>Allowed values: \["succeeded","failed","interrupted","superseded"\] |
| /<wbr>properties/<wbr>versions/<wbr>items/<wbr>properties/<wbr>outcome/<wbr>properties/<wbr>step | On a failed row, the step the run had reached when the process that ran it failed or stopped it, a platform word\. The word `switching` is a live step alone, the one a replacing act is at between its switch and its mark: a row that reached it ends `deployed`, so no failed row carries it\. The step is absent on a row the stale sweep ended, a superseded row, and a row written before the member\.<br><br>Type: string<br>Allowed values: \["pending\_candidates","image\_build","slot\_guard","database\_pair","issue\_space","platform\_credential","database\_credential","declarations","realm\_keys","pull\_identity","compute\_apply","shell\_assets","migrations","health\_gate","smoke\_check","function\_settings","finish","switching","after\_finish"\] |
| /<wbr>properties/<wbr>versions/<wbr>items/<wbr>properties/<wbr>outcome/<wbr>properties/<wbr>build | On a row failed `image_build_failed` or failed by the function build's tree check with `function_tree_link`, `function_native_module`, `function_tree_too_large` or `function_count_exceeded`\. The build steps' own last lines, at most forty of at most 512 bytes and 4,096 in all, `truncated` where a bound cut them\. Framing lines, registry addresses, header values, and the provider's name are left out; another address reads `[address]` and a token `[token]`\. `cause` says why the log was not read\.<br><br>Type: object<br>Required fields: \["outcome","output\_tail","truncated"\]<br>Additional properties: false |
| /<wbr>properties/<wbr>versions/<wbr>items/<wbr>properties/<wbr>outcome/<wbr>properties/<wbr>build/<wbr>properties/<wbr>outcome | Type: string<br>Allowed values: \["lines","empty","unavailable"\] |
| /<wbr>properties/<wbr>versions/<wbr>items/<wbr>properties/<wbr>outcome/<wbr>properties/<wbr>build/<wbr>properties/<wbr>output\_tail | Type: array |
| /<wbr>properties/<wbr>versions/<wbr>items/<wbr>properties/<wbr>outcome/<wbr>properties/<wbr>build/<wbr>properties/<wbr>output\_tail/<wbr>items | Type: string |
| /<wbr>properties/<wbr>versions/<wbr>items/<wbr>properties/<wbr>outcome/<wbr>properties/<wbr>build/<wbr>properties/<wbr>truncated | Type: boolean |
| /<wbr>properties/<wbr>versions/<wbr>items/<wbr>properties/<wbr>outcome/<wbr>properties/<wbr>build/<wbr>properties/<wbr>cause | Type: string<br>Allowed values: \["log\_unavailable","log\_timeout"\] |
| /<wbr>properties/<wbr>versions/<wbr>items/<wbr>properties/<wbr>outcome/<wbr>properties/<wbr>credentials\_missing | On a row that ended deployed, present where the environment reads no stored key for an upstream of the application: each such upstream and its key's stored name\. The act served, and the gateway refuses that upstream's calls `credential_not_in_custody` until `store_secret` stores the key at that environment's scope of the application or at the account scope\.<br><br>Type: array |
| /<wbr>properties/<wbr>versions/<wbr>items/<wbr>properties/<wbr>outcome/<wbr>properties/<wbr>credentials\_missing/<wbr>items | Type: object<br>Required fields: \["upstream","credential\_name"\] |
| /<wbr>properties/<wbr>versions/<wbr>items/<wbr>properties/<wbr>outcome/<wbr>properties/<wbr>credentials\_missing/<wbr>items/<wbr>properties/<wbr>upstream | The upstream's name\.<br><br>Type: string |
| /<wbr>properties/<wbr>versions/<wbr>items/<wbr>properties/<wbr>outcome/<wbr>properties/<wbr>credentials\_missing/<wbr>items/<wbr>properties/<wbr>credential\_name | The stored name of the upstream's key\.<br><br>Type: string |
| /<wbr>properties/<wbr>versions/<wbr>items/<wbr>properties/<wbr>outcome/<wbr>properties/<wbr>provider\_credentials\_missing | On a row that ended deployed, present where a credential the manifest's `realm` member or push entry refers to is one the environment's provider cannot read: each such credential and its provider\. The act served\. Until `store_secret` stores the credential at that environment's scope of the application, the sign\-in method's sign\-ins fail and the push provider's deliveries end `credential_unreadable`\. A sign\-in credential then moves into place at the manifest's next submission\.<br><br>Type: array |
| /<wbr>properties/<wbr>versions/<wbr>items/<wbr>properties/<wbr>outcome/<wbr>properties/<wbr>provider\_credentials\_missing/<wbr>items | Type: object<br>Required fields: \["provider","credential\_name"\] |
| /<wbr>properties/<wbr>versions/<wbr>items/<wbr>properties/<wbr>outcome/<wbr>properties/<wbr>provider\_credentials\_missing/<wbr>items/<wbr>properties/<wbr>provider | The provider the credential serves: a sign\-in method, `entra` or `apple`, or a push provider, `apns` or `fcm`\.<br><br>Type: string<br>Allowed values: \["entra","apple","apns","fcm"\] |
| /<wbr>properties/<wbr>versions/<wbr>items/<wbr>properties/<wbr>outcome/<wbr>properties/<wbr>provider\_credentials\_missing/<wbr>items/<wbr>properties/<wbr>credential\_name | The credential's stored name\.<br><br>Type: string |
| /<wbr>properties/<wbr>versions/<wbr>items/<wbr>properties/<wbr>outcome/<wbr>properties/<wbr>error | Type: string |
| /<wbr>properties/<wbr>versions/<wbr>items/<wbr>properties/<wbr>outcome/<wbr>properties/<wbr>detail | Type: string |
| /<wbr>properties/<wbr>versions/<wbr>items/<wbr>properties/<wbr>outcome/<wbr>properties/<wbr>gate | Type: object |
| /<wbr>properties/<wbr>versions/<wbr>items/<wbr>properties/<wbr>outcome/<wbr>properties/<wbr>smoke | Type: object |
| /<wbr>properties/<wbr>versions/<wbr>items/<wbr>properties/<wbr>serving | Type: boolean |
| /<wbr>properties/<wbr>versions/<wbr>items/<wbr>properties/<wbr>fixes | On a serving row alone: the highest severity, `critical` or `high`, fixed by the platform's moves of its running\-stage base image since this version's base\. It is null where none, where the version runs on the current base, or where its base is not recorded\. It is read\_status's `base.fixes` for that environment, whose `base_apply` says which acts take the current base\.<br><br>Type: \["string","null"\]<br>Allowed values: \["critical","high",null\] |
| /<wbr>properties/<wbr>versions/<wbr>items/<wbr>properties/<wbr>kept | On each environment's serving row alone: the recorded files as `{ path, sha256 }` pairs sorted by path, or null where none were recorded\. These are the files the `deploy_files` list carried, excluding left\-out entries and library copies the platform filled\. Each hash can replace `content` for that file in `deploy_files` while the version serves\. Null covers versions deployed before the platform recorded these entries, those deployed through the command, upload or artifact route, and promotes, rollbacks or restarts carrying their null\. Other rows carry no `kept`\.<br><br>Type: \["array","null"\]<br>Maximum items: 200 |
| /<wbr>properties/<wbr>versions/<wbr>items/<wbr>properties/<wbr>kept/<wbr>items | Type: object<br>Required fields: \["path","sha256"\]<br>Additional properties: false |
| /<wbr>properties/<wbr>versions/<wbr>items/<wbr>properties/<wbr>kept/<wbr>items/<wbr>properties/<wbr>path | Type: string |
| /<wbr>properties/<wbr>versions/<wbr>items/<wbr>properties/<wbr>kept/<wbr>items/<wbr>properties/<wbr>sha256 | Type: string<br>Pattern: ^\[0\-9a\-f\]\{64\}$ |
| /<wbr>properties/<wbr>versions/<wbr>items/<wbr>properties/<wbr>promotable | True where the row is `deployed` and its image still exists in the cell registry, so `promote` and `roll_back` can take its version\. It says the image exists, not that promoting it is advised; `serving` marks the version the environment runs\. It is false on a `deploying` or `failed` row and on a deployed row whose image the platform's retention deleted, when a promote of that version is refused 409 `version_image_pruned`\. The retention keeps the images of each environment's serving version and its twenty most recent deployed versions\.<br><br>Type: boolean |
| /<wbr>properties/<wbr>versions/<wbr>items/<wbr>properties/<wbr>harness\_hash | The SHA\-256 of the runtime harness bundle the row's image carries, read by the platform from its own bundle at the deploy's first write and copied from the source row by a promote or rollback\. It is null where the platform did not record the harness: every row written before the platform kept it, and a promote or rollback of such a row\.<br><br>Type: \["string","null"\] |
| /<wbr>properties/<wbr>versions/<wbr>items/<wbr>properties/<wbr>harness\_current | True where `harness_hash` is non\-null and equals the harness the platform you called bakes into new images; false where it differs or is null\. A promote carries the deploy's image and its harness, so a version whose harness is not current stays so in production; a new deploy takes the current harness\.<br><br>Type: boolean |
| /<wbr>properties/<wbr>versions/<wbr>items/<wbr>properties/<wbr>timings | The steps the row entered, in order, each with its start and end instants, a step a word of `outcome.step`'s list\. The last step's `ended_at` is null while the row is deploying and where the platform's sweep or a deletion ended the row\. Null on a row written before the platform kept it\.<br><br>Type: \["array","null"\] |
| /<wbr>properties/<wbr>versions/<wbr>items/<wbr>properties/<wbr>timings/<wbr>items | Type: object<br>Required fields: \["step","started\_at","ended\_at"\]<br>Additional properties: false |
| /<wbr>properties/<wbr>versions/<wbr>items/<wbr>properties/<wbr>timings/<wbr>items/<wbr>properties/<wbr>step | Type: string |
| /<wbr>properties/<wbr>versions/<wbr>items/<wbr>properties/<wbr>timings/<wbr>items/<wbr>properties/<wbr>started\_at | Type: string |
| /<wbr>properties/<wbr>versions/<wbr>items/<wbr>properties/<wbr>timings/<wbr>items/<wbr>properties/<wbr>ended\_at | Type: \["string","null"\] |
| /<wbr>properties/<wbr>versions/<wbr>items/<wbr>properties/<wbr>rolled\_back\_from | The version production served when this rollback was accepted\. Null on other rows, when production served none, and on rows written before this member\. A rollback's `kind` remains `promote`\.<br><br>Type: \["integer","null"\] |
| /<wbr>properties/<wbr>next\_cursor | The cursor of the next page, or null on the last page\.<br><br>Type: \["string","null"\] |
| /<wbr>properties/<wbr>serving | Each environment the application has, mapped to the number of the version it serves, or null where it serves none\. It is read from the whole version history, whatever page you request\.<br><br>Type: object<br>Additional properties: false |
| /<wbr>properties/<wbr>serving/<wbr>properties/<wbr>development | Type: \["integer","null"\] |
| /<wbr>properties/<wbr>serving/<wbr>properties/<wbr>production | Type: \["integer","null"\] |
| /<wbr>properties/<wbr>page | $ref: \#/shapes/page |
| /<wbr>properties/<wbr>detail | Type: string |

## Complete payload contract

```json
{
  "request": {
    "type": "object",
    "required": [
      "application"
    ],
    "properties": {
      "application": {
        "type": "string",
        "description": "Your account's application `id` from `list_applications`, not its name or label."
      },
      "environment": {
        "type": "string",
        "pattern": "^(development|production)$",
        "description": "Optional. Narrows the answer to one environment's rows, `development` or `production`; leave it out and you get both environments' rows."
      },
      "limit": {
        "type": "integer",
        "minimum": 1,
        "maximum": 200,
        "description": "Optional. The most rows you get, 1 to 200; 50 by default."
      },
      "cursor": {
        "type": "string",
        "description": "Optional. The `next_cursor` of a previous answer."
      }
    }
  },
  "response": {
    "type": "object",
    "required": [
      "contract_version",
      "application",
      "versions",
      "next_cursor"
    ],
    "properties": {
      "contract_version": {
        "const": 1
      },
      "reference": {
        "type": "string",
        "pattern": "^[0-9a-f]{10}$",
        "description": "The short reference the platform recorded your call under: ten lowercase hexadecimal characters, the value in the call’s record row. Quote it when you report the call."
      },
      "application": {
        "type": "string"
      },
      "versions": {
        "type": "array",
        "items": {
          "type": "object",
          "required": [
            "id",
            "environment",
            "version",
            "kind",
            "state",
            "artifact_hash",
            "started_at",
            "ended_at",
            "outcome",
            "serving",
            "promotable",
            "harness_hash",
            "harness_current",
            "rolled_back_from"
          ],
          "properties": {
            "id": {
              "type": "string"
            },
            "environment": {
              "type": "string",
              "enum": [
                "development",
                "production"
              ]
            },
            "version": {
              "type": "integer"
            },
            "kind": {
              "type": "string",
              "enum": [
                "deploy",
                "promote",
                "restart"
              ],
              "description": "A deploy writes a row of kind deploy. A promote or rollback writes a row of kind promote. A restart writes a row of kind restart, carrying the serving row's number (PLD-L0-63). A restart is the re-creation of the environment's serving compute under current settings by `restart_application`, a rename, or the platform (PLD-L0-84)."
            },
            "state": {
              "type": "string",
              "enum": [
                "deploying",
                "deployed",
                "failed"
              ]
            },
            "artifact_hash": {
              "type": [
                "string",
                "null"
              ]
            },
            "started_at": {
              "type": "string"
            },
            "ended_at": {
              "type": [
                "string",
                "null"
              ]
            },
            "outcome": {
              "type": [
                "object",
                "null"
              ],
              "description": "Null while the row is deploying. On a failed row an object of error, the refusal's name, and detail, its sentence — or the outcome interrupted or superseded — with step, the step the run had reached where the process that ran it ended the row (PLD-L0-63). On a row failed at the health gate (health_gate_failed) it also carries gate: probed (private_ingress or group_route, never the address), timeout_ms, polls, and probe_sequence. The probe_sequence is a run-length ledger of at most sixteen {answer, count} runs, answer an HTTP status or one of the transport words connection_refused, name_not_resolved, connection_reset, timed_out, tls_failed, and transport_error. The gate also carries last (the last non-200 answer's status and content_type, and its body's first 512 bytes with body_truncated only where answered_by is application), null where no HTTP answer was read. The gate also carries answered_by (application, intermediary, nothing, or unknown, the reading at the deadline or at an early end) and control_probe (its outcome and status, refusal, or cause). The gate also carries ended_early: true for an early end on an own-process client error or stopping instance. It is false at the bound and absent on rows written before the member. The gate's polls_200 counts the probes whose response was 200; an older row lacks it. The gate also carries compute: state, and with detail revision {provisioning, running, health}, instance {phase, state, restarts, exit_code, last_state}, and ready, a member {unavailable: cause} where its read failed. The cause is an HTTP status word, a platform error code, or error. The whole member is {outcome: unavailable, cause} where its read failed or overran and {state: unavailable, reason} where the seam caught the failure. The gate also carries console (outcome as lines, empty, or unavailable; lines, at most forty of at most 512 bytes and 4,096 in all; truncated; since; and cause). read_status returns the same outcome whole. No member includes an address, a header value, or the provider (PLD-L0-59; PLD-L0-63). On a row failed `smoke_path_failed` it carries `smoke` in place of `gate`: path, answer, last, compute, and console (PLD-L0-59).",
              "properties": {
                "result": {
                  "type": "string",
                  "enum": [
                    "succeeded",
                    "failed",
                    "interrupted",
                    "superseded"
                  ],
                  "description": "How the row ended, on every ended row: `succeeded` on a deployed row, `interrupted` where the platform's process stopped or lost the run, `superseded` where a deletion ended it, and `failed` otherwise (PLD-L0-63).\n\nOn a `succeeded` server run, the declared health path returned 200 three times in a row within the check's bound. Where it replaced a serving version, the routers' short resolve interval after the switch has passed. On a server deploy or a promote that is not a rollback and passes a version production does not serve, the check also requested the manifest's smoke paths after the gate passed (MAN-18). No other path is probed: a failing route shows in `read_status`' `server_errors` once a request reaches it.\n\nA serverless run made no health check or smoke check."
                },
                "step": {
                  "type": "string",
                  "enum": [
                    "pending_candidates",
                    "image_build",
                    "slot_guard",
                    "database_pair",
                    "issue_space",
                    "platform_credential",
                    "database_credential",
                    "declarations",
                    "realm_keys",
                    "pull_identity",
                    "compute_apply",
                    "shell_assets",
                    "migrations",
                    "health_gate",
                    "smoke_check",
                    "function_settings",
                    "finish",
                    "switching",
                    "after_finish"
                  ],
                  "description": "On a failed row, the step the run had reached when the process that ran it failed or stopped it, a platform word. The word `switching` is a live step alone, the one a replacing act is at between its switch and its mark: a row that reached it ends `deployed`, so no failed row carries it. The step is absent on a row the stale sweep ended, a superseded row, and a row written before the member (PLD-L0-63)."
                },
                "build": {
                  "type": "object",
                  "required": [
                    "outcome",
                    "output_tail",
                    "truncated"
                  ],
                  "properties": {
                    "outcome": {
                      "type": "string",
                      "enum": [
                        "lines",
                        "empty",
                        "unavailable"
                      ]
                    },
                    "output_tail": {
                      "type": "array",
                      "items": {
                        "type": "string"
                      }
                    },
                    "truncated": {
                      "type": "boolean"
                    },
                    "cause": {
                      "type": "string",
                      "enum": [
                        "log_unavailable",
                        "log_timeout"
                      ]
                    }
                  },
                  "additionalProperties": false,
                  "description": "On a row failed `image_build_failed` or failed by the function build's tree check with `function_tree_link`, `function_native_module`, `function_tree_too_large` or `function_count_exceeded`. The build steps' own last lines, at most forty of at most 512 bytes and 4,096 in all, `truncated` where a bound cut them. Framing lines, registry addresses, header values, and the provider's name are left out; another address reads `[address]` and a token `[token]`. `cause` says why the log was not read (PLD-L0-90; PLD-L0-59)."
                },
                "credentials_missing": {
                  "type": "array",
                  "description": "On a row that ended deployed, present where the environment reads no stored key for an upstream of the application: each such upstream and its key's stored name (EGW-L0-02). The act served, and the gateway refuses that upstream's calls `credential_not_in_custody` until `store_secret` stores the key at that environment's scope of the application or at the account scope.",
                  "items": {
                    "type": "object",
                    "required": [
                      "upstream",
                      "credential_name"
                    ],
                    "properties": {
                      "upstream": {
                        "type": "string",
                        "description": "The upstream's name."
                      },
                      "credential_name": {
                        "type": "string",
                        "description": "The stored name of the upstream's key."
                      }
                    }
                  }
                },
                "provider_credentials_missing": {
                  "type": "array",
                  "description": "On a row that ended deployed, present where a credential the manifest's `realm` member or push entry refers to is one the environment's provider cannot read: each such credential and its provider (ACS-L0-09; PSH-L0-01). The act served. Until `store_secret` stores the credential at that environment's scope of the application, the sign-in method's sign-ins fail and the push provider's deliveries end `credential_unreadable`. A sign-in credential then moves into place at the manifest's next submission.",
                  "items": {
                    "type": "object",
                    "required": [
                      "provider",
                      "credential_name"
                    ],
                    "properties": {
                      "provider": {
                        "type": "string",
                        "enum": [
                          "entra",
                          "apple",
                          "apns",
                          "fcm"
                        ],
                        "description": "The provider the credential serves: a sign-in method, `entra` or `apple`, or a push provider, `apns` or `fcm`."
                      },
                      "credential_name": {
                        "type": "string",
                        "description": "The credential's stored name."
                      }
                    }
                  }
                },
                "error": {
                  "type": "string"
                },
                "detail": {
                  "type": "string"
                },
                "gate": {
                  "type": "object"
                },
                "smoke": {
                  "type": "object"
                }
              }
            },
            "serving": {
              "type": "boolean"
            },
            "fixes": {
              "type": [
                "string",
                "null"
              ],
              "enum": [
                "critical",
                "high",
                null
              ],
              "description": "On a serving row alone: the highest severity, `critical` or `high`, fixed by the platform's moves of its running-stage base image since this version's base. It is null where none, where the version runs on the current base, or where its base is not recorded. It is read_status's `base.fixes` for that environment, whose `base_apply` says which acts take the current base (PLD-L0-82)."
            },
            "kept": {
              "type": [
                "array",
                "null"
              ],
              "maxItems": 200,
              "items": {
                "type": "object",
                "required": [
                  "path",
                  "sha256"
                ],
                "properties": {
                  "path": {
                    "type": "string"
                  },
                  "sha256": {
                    "type": "string",
                    "pattern": "^[0-9a-f]{64}$"
                  }
                },
                "additionalProperties": false
              },
              "description": "On each environment's serving row alone: the recorded files as `{ path, sha256 }` pairs sorted by path, or null where none were recorded. These are the files the `deploy_files` list carried, excluding left-out entries and library copies the platform filled. Each hash can replace `content` for that file in `deploy_files` while the version serves. Null covers versions deployed before the platform recorded these entries, those deployed through the command, upload or artifact route, and promotes, rollbacks or restarts carrying their null. Other rows carry no `kept` (PLD-L0-63)."
            },
            "promotable": {
              "type": "boolean",
              "description": "True where the row is `deployed` and its image still exists in the cell registry, so `promote` and `roll_back` can take its version. It says the image exists, not that promoting it is advised; `serving` marks the version the environment runs. It is false on a `deploying` or `failed` row and on a deployed row whose image the platform's retention deleted, when a promote of that version is refused 409 `version_image_pruned`. The retention keeps the images of each environment's serving version and its twenty most recent deployed versions (PLD-L0-63)."
            },
            "harness_hash": {
              "type": [
                "string",
                "null"
              ],
              "description": "The SHA-256 of the runtime harness bundle the row's image carries, read by the platform from its own bundle at the deploy's first write and copied from the source row by a promote or rollback. It is null where the platform did not record the harness: every row written before the platform kept it, and a promote or rollback of such a row (PLD-L0-63)."
            },
            "harness_current": {
              "type": "boolean",
              "description": "True where `harness_hash` is non-null and equals the harness the platform you called bakes into new images; false where it differs or is null. A promote carries the deploy's image and its harness, so a version whose harness is not current stays so in production; a new deploy takes the current harness (PLD-L0-63)."
            },
            "timings": {
              "type": [
                "array",
                "null"
              ],
              "items": {
                "type": "object",
                "required": [
                  "step",
                  "started_at",
                  "ended_at"
                ],
                "properties": {
                  "step": {
                    "type": "string"
                  },
                  "started_at": {
                    "type": "string"
                  },
                  "ended_at": {
                    "type": [
                      "string",
                      "null"
                    ]
                  }
                },
                "additionalProperties": false
              },
              "description": "The steps the row entered, in order, each with its start and end instants, a step a word of `outcome.step`'s list. The last step's `ended_at` is null while the row is deploying and where the platform's sweep or a deletion ended the row. Null on a row written before the platform kept it (PLD-L0-89)."
            },
            "rolled_back_from": {
              "type": [
                "integer",
                "null"
              ],
              "description": "The version production served when this rollback was accepted. Null on other rows, when production served none, and on rows written before this member. A rollback's `kind` remains `promote`."
            }
          }
        }
      },
      "next_cursor": {
        "type": [
          "string",
          "null"
        ],
        "description": "The cursor of the next page, or null on the last page."
      },
      "serving": {
        "type": "object",
        "properties": {
          "development": {
            "type": [
              "integer",
              "null"
            ]
          },
          "production": {
            "type": [
              "integer",
              "null"
            ]
          }
        },
        "additionalProperties": false,
        "description": "Each environment the application has, mapped to the number of the version it serves, or null where it serves none. It is read from the whole version history, whatever page you request (PLD-L0-63)."
      },
      "page": {
        "$ref": "#/shapes/page"
      },
      "detail": {
        "type": "string"
      }
    },
    "description": "The application's version history, newest first by start instant. The `serving` member is true on each environment's serving row, the deployed row that is not retired and has the latest end instant. The `promotable` member is true on a deployed row whose image the platform's retention has kept. A row retired by its environment's deletion is not returned. The `harness_hash` and `harness_current` members state the harness the row's image carries and whether it is the platform's current one — a promote keeps the deploy's harness, a new deploy takes the current one (PLD-L0-63).\n\nEach environment's serving row alone also carries `kept`: its recorded file paths and SHA-256 hashes sorted by path, or null where none were recorded (PLD-L0-63)."
  }
}
```

## Shared contracts

- [Refusals](/cloud/reference/refusals/): every refusal, by surface, with its cause and its remedy
- [schemas/wire\_error\.schema\.json](/cloud/reference/sources/schemas/wire-error-schema/)
- [schemas/wire\_errors\.json](/cloud/reference/sources/schemas/wire-errors/)
- [schemas/action\_payloads\.json](/cloud/reference/sources/schemas/action-payloads/) (includes shared shapes)
- [management\_api\_contract\.md](/cloud/reference/sources/management-api-contract/)
