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

# list\_applications

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_applications`, 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_applications`.

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

List your account's applications with each one's id, `size`, deployment history and feature flags\. The history includes successful deploys, promotes and rollbacks, and excludes restarts and failures\. Rows give the `label` and each environment's hostname and halted\_at, null while not halted\. The company's own applications have size null and unlimited true\. Application states are deployed, `failed` after a failed first production deploy or promote, and never\_deployed\. Environment states are deploying, deployed, `failed`, never\_deployed, halted or deleting, as read\_status returns them\. Each environment's grain is container for its own container app, or pod for a cluster shared with other applications\. With function, it is a serverless environment with no compute of its own\. Other tools take the id as application\.

## Access and action metadata

```json
{
  "name": "list_applications",
  "resource": "application",
  "tier": "observe",
  "surface": "tzcloud",
  "addresses": [
    "tzcloud"
  ],
  "product": "cloud",
  "clients": [
    "bearer",
    "browser_session"
  ],
  "summary": "The account's applications with deployment history, declared feature flags and environments. Each environment gives its state (deploying, deployed, `failed`, never_deployed, halted or deleting, as read_status returns), serving version, hostname, compute grain and halted_at, null while not halted. Deployment history includes successful deploys, promotes and rollbacks, and excludes restarts and failures.",
  "annotations": {
    "readOnlyHint": true,
    "destructiveHint": false,
    "openWorldHint": false,
    "idempotentHint": true
  }
}
```

## MCP catalog entry

```json
{
  "name": "list_applications",
  "title": "List applications",
  "tier": "observe",
  "scenario": "CHI-L0-09",
  "summary": "List your account's applications with each one's id, `size`, deployment history and feature flags. The history includes successful deploys, promotes and rollbacks, and excludes restarts and failures. Rows give the `label` and each environment's hostname and halted_at, null while not halted. The company's own applications have size null and unlimited true. Application states are deployed, `failed` after a failed first production deploy or promote, and never_deployed. Environment states are deploying, deployed, `failed`, never_deployed, halted or deleting, as read_status returns them. Each environment's grain is container for its own container app, or pod for a cluster shared with other applications. With function, it is a serverless environment with no compute of its own. Other tools take the id as application.",
  "owners": [
    "PLD-L0-127",
    "PLD-L0-40"
  ]
}
```

## request

| JSON pointer | Description and constraints |
|---|---|
| "" \(root\) | Type: object |

## response

| JSON pointer | Description and constraints |
|---|---|
| "" \(root\) | Type: object<br>Required fields: \["contract\_version","applications"\] |
| /<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>applications | Type: array |
| /<wbr>properties/<wbr>applications/<wbr>items | Type: object<br>Required fields: \["id","name","label","created\_at","kind","environments","state","version","first\_live\_at","last\_deployed\_at","deploy\_count","production\_deploy\_count","features"\] |
| /<wbr>properties/<wbr>applications/<wbr>items/<wbr>properties/<wbr>id | Type: string |
| /<wbr>properties/<wbr>applications/<wbr>items/<wbr>properties/<wbr>name | Type: string |
| /<wbr>properties/<wbr>applications/<wbr>items/<wbr>properties/<wbr>label | Type: string |
| /<wbr>properties/<wbr>applications/<wbr>items/<wbr>properties/<wbr>created\_at | Type: string |
| /<wbr>properties/<wbr>applications/<wbr>items/<wbr>properties/<wbr>size |  |
| /<wbr>properties/<wbr>applications/<wbr>items/<wbr>properties/<wbr>size/<wbr>anyOf/<wbr>0 | $ref: \#/shapes/app\_size |
| /<wbr>properties/<wbr>applications/<wbr>items/<wbr>properties/<wbr>size/<wbr>anyOf/<wbr>1 | Type: null |
| /<wbr>properties/<wbr>applications/<wbr>items/<wbr>properties/<wbr>unlimited | True on the company's own applications, where `size` is null\. Absent on every other application\.<br><br>Type: boolean |
| /<wbr>properties/<wbr>applications/<wbr>items/<wbr>properties/<wbr>kind | The application’s recorded kind, server or serverless\. Earlier applications and creation with no kind use server\. Serverless is not yet available\.<br><br>Type: string<br>Allowed values: \["server","serverless"\] |
| /<wbr>properties/<wbr>applications/<wbr>items/<wbr>properties/<wbr>environments | One object per environment, development then production: its name, state, serving version, hostname, compute grain and halted\_at, the halt instant or null\.<br><br>Type: array |
| /<wbr>properties/<wbr>applications/<wbr>items/<wbr>properties/<wbr>environments/<wbr>items | Type: object<br>Required fields: \["name","state","version","hostname","halted\_at"\] |
| /<wbr>properties/<wbr>applications/<wbr>items/<wbr>properties/<wbr>environments/<wbr>items/<wbr>properties/<wbr>name | Type: string<br>Allowed values: \["development","production"\] |
| /<wbr>properties/<wbr>applications/<wbr>items/<wbr>properties/<wbr>environments/<wbr>items/<wbr>properties/<wbr>state | The first of these that holds: `deleting` while a deletion of the application or of the environment is in flight, `halted` where you or the platform halted the environment\. Then `deploying` while a deploy, promote, or restart of the environment is in flight, `deployed` where a serving version exists, and `failed` where none serves and the environment's latest version row not retired by a deletion failed\. It is `never_deployed` otherwise\. These are the words `read_status` returns as the environment's `state`, read through one function; the compute provider's own word is `read_status`'s `compute_state`\.<br><br>Type: string<br>Allowed values: \["deploying","deployed","failed","never\_deployed","halted","deleting"\] |
| /<wbr>properties/<wbr>applications/<wbr>items/<wbr>properties/<wbr>environments/<wbr>items/<wbr>properties/<wbr>version | The environment's serving version, or null\.<br><br>Type: \["integer","null"\] |
| /<wbr>properties/<wbr>applications/<wbr>items/<wbr>properties/<wbr>environments/<wbr>items/<wbr>properties/<wbr>hostname | The environment's hostname as `read_status` returns it: the label under the serving suffix for production, the label with `-dev` appended for development\.<br><br>Type: string |
| /<wbr>properties/<wbr>applications/<wbr>items/<wbr>properties/<wbr>environments/<wbr>items/<wbr>properties/<wbr>grain | The environment's placement grain is `container`, `pod` or `function`\. A `container` is its own container app\. A `pod` is one pod on the hosting cell's cluster, in a group of the environment's kind\. A `shared-1gb` or unlimited production environment is `container`\. A development environment of either size, and a `shared-0.5gb` production environment, is `pod` where its cell registers an admitting group of its kind\. It is `container` where the cell registers none\. A full group refuses the act `group_full`\. A serverless application, not yet available to customers, has `function` grain with no compute before or after a version serves\.<br><br>Type: string<br>Allowed values: \["container","pod","function"\] |
| /<wbr>properties/<wbr>applications/<wbr>items/<wbr>properties/<wbr>environments/<wbr>items/<wbr>properties/<wbr>halted\_at | The instant this environment was halted, in ISO 8601 form\. Null while it is not halted\.<br><br>Type: \["string","null"\] |
| /<wbr>properties/<wbr>applications/<wbr>items/<wbr>properties/<wbr>state | The application's own state: `failed` where production's environment reads `failed`, a first production deploy or promote having failed with nothing serving; otherwise `deployed` once production's compute exists and `never_deployed` before\.<br><br>Type: string<br>Pattern: ^\(deployed\|failed\|never\_deployed\)$ |
| /<wbr>properties/<wbr>applications/<wbr>items/<wbr>properties/<wbr>version | Type: \["integer","null"\] |
| /<wbr>properties/<wbr>applications/<wbr>items/<wbr>properties/<wbr>first\_live\_at | The earliest non\-null `ended_at` of a deploy or promote row that ended `deployed`, across both environments\. Rollbacks count\. Restarts and failures do not\. Null before one\.<br><br>Type: \["string","null"\] |
| /<wbr>properties/<wbr>applications/<wbr>items/<wbr>properties/<wbr>last\_deployed\_at | The latest non\-null `ended_at` of a deploy or promote row that ended `deployed`, across both environments\. Rollbacks count\. Restarts and failures do not\. Null before one\.<br><br>Type: \["string","null"\] |
| /<wbr>properties/<wbr>applications/<wbr>items/<wbr>properties/<wbr>deploy\_count | The number of deploy or promote rows that ended `deployed` with a non\-null `ended_at`, across both environments\. Rollbacks count\. Restarts and failures do not\. Zero before one\.<br><br>Type: integer<br>Minimum: 0 |
| /<wbr>properties/<wbr>applications/<wbr>items/<wbr>properties/<wbr>production\_deploy\_count | The number of production deploy or promote rows that ended `deployed` with a non\-null `ended_at`\. Rollbacks count\. Restarts and failures do not\. Zero before one\.<br><br>Type: integer<br>Minimum: 0 |
| /<wbr>properties/<wbr>applications/<wbr>items/<wbr>properties/<wbr>features | Feature flags from the current recorded manifest, the application's own resource rows and its environment count\.<br><br>Type: object<br>Required fields: \["database","schedules","end\_user\_sign\_in","storage","custom\_domain","development\_environment"\]<br>Additional properties: false |
| /<wbr>properties/<wbr>applications/<wbr>items/<wbr>properties/<wbr>features/<wbr>properties/<wbr>database | True when the current recorded manifest declares a database\.<br><br>Type: boolean |
| /<wbr>properties/<wbr>applications/<wbr>items/<wbr>properties/<wbr>features/<wbr>properties/<wbr>schedules | True when the current recorded manifest declares schedules\.<br><br>Type: boolean |
| /<wbr>properties/<wbr>applications/<wbr>items/<wbr>properties/<wbr>features/<wbr>properties/<wbr>end\_user\_sign\_in | True when the current recorded manifest declares the accounts service or has a non\-public audience\.<br><br>Type: boolean |
| /<wbr>properties/<wbr>applications/<wbr>items/<wbr>properties/<wbr>features/<wbr>properties/<wbr>storage | True when the application has a storage area of its own\. Platform\-held areas do not count\.<br><br>Type: boolean |
| /<wbr>properties/<wbr>applications/<wbr>items/<wbr>properties/<wbr>features/<wbr>properties/<wbr>custom\_domain | True when the application has a custom domain that is not being detached\.<br><br>Type: boolean |
| /<wbr>properties/<wbr>applications/<wbr>items/<wbr>properties/<wbr>features/<wbr>properties/<wbr>development\_environment | True when the application has two environments\.<br><br>Type: boolean |
| /<wbr>properties/<wbr>detail | Type: string |

## Complete payload contract

```json
{
  "request": {
    "type": "object",
    "properties": {}
  },
  "response": {
    "type": "object",
    "required": [
      "contract_version",
      "applications"
    ],
    "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."
      },
      "applications": {
        "type": "array",
        "items": {
          "type": "object",
          "required": [
            "id",
            "name",
            "label",
            "created_at",
            "kind",
            "environments",
            "state",
            "version",
            "first_live_at",
            "last_deployed_at",
            "deploy_count",
            "production_deploy_count",
            "features"
          ],
          "properties": {
            "id": {
              "type": "string"
            },
            "name": {
              "type": "string"
            },
            "label": {
              "type": "string"
            },
            "created_at": {
              "type": "string"
            },
            "size": {
              "anyOf": [
                {
                  "$ref": "#/shapes/app_size"
                },
                {
                  "type": "null"
                }
              ]
            },
            "unlimited": {
              "type": "boolean",
              "description": "True on the company's own applications, where `size` is null. Absent on every other application."
            },
            "kind": {
              "type": "string",
              "enum": [
                "server",
                "serverless"
              ],
              "description": "The application’s recorded kind, server or serverless. Earlier applications and creation with no kind use server. Serverless is not yet available."
            },
            "environments": {
              "type": "array",
              "description": "One object per environment, development then production: its name, state, serving version, hostname, compute grain and halted_at, the halt instant or null (PLD-L0-40).",
              "items": {
                "type": "object",
                "required": [
                  "name",
                  "state",
                  "version",
                  "hostname",
                  "halted_at"
                ],
                "properties": {
                  "name": {
                    "type": "string",
                    "enum": [
                      "development",
                      "production"
                    ]
                  },
                  "state": {
                    "type": "string",
                    "enum": [
                      "deploying",
                      "deployed",
                      "failed",
                      "never_deployed",
                      "halted",
                      "deleting"
                    ],
                    "description": "The first of these that holds: `deleting` while a deletion of the application or of the environment is in flight, `halted` where you or the platform halted the environment (PLD-L0-66; PLD-L0-41). Then `deploying` while a deploy, promote, or restart of the environment is in flight, `deployed` where a serving version exists, and `failed` where none serves and the environment's latest version row not retired by a deletion failed. It is `never_deployed` otherwise. These are the words `read_status` returns as the environment's `state`, read through one function; the compute provider's own word is `read_status`'s `compute_state` (PLD-L0-40; PLD-L0-63)."
                  },
                  "version": {
                    "type": [
                      "integer",
                      "null"
                    ],
                    "description": "The environment's serving version, or null."
                  },
                  "hostname": {
                    "type": "string",
                    "description": "The environment's hostname as `read_status` returns it: the label under the serving suffix for production, the label with `-dev` appended for development (SVC-L0-07)."
                  },
                  "grain": {
                    "type": "string",
                    "enum": [
                      "container",
                      "pod",
                      "function"
                    ],
                    "description": "The environment's placement grain is `container`, `pod` or `function` (PLD-L0-127; PLD-L0-130). A `container` is its own container app. A `pod` is one pod on the hosting cell's cluster, in a group of the environment's kind. A `shared-1gb` or unlimited production environment is `container`. A development environment of either size, and a `shared-0.5gb` production environment, is `pod` where its cell registers an admitting group of its kind. It is `container` where the cell registers none. A full group refuses the act `group_full`. A serverless application, not yet available to customers, has `function` grain with no compute before or after a version serves."
                  },
                  "halted_at": {
                    "type": [
                      "string",
                      "null"
                    ],
                    "description": "The instant this environment was halted, in ISO 8601 form. Null while it is not halted."
                  }
                }
              }
            },
            "state": {
              "type": "string",
              "pattern": "^(deployed|failed|never_deployed)$",
              "description": "The application's own state: `failed` where production's environment reads `failed`, a first production deploy or promote having failed with nothing serving; otherwise `deployed` once production's compute exists and `never_deployed` before (WEB-L0-17)."
            },
            "version": {
              "type": [
                "integer",
                "null"
              ]
            },
            "first_live_at": {
              "type": [
                "string",
                "null"
              ],
              "description": "The earliest non-null `ended_at` of a deploy or promote row that ended `deployed`, across both environments. Rollbacks count. Restarts and failures do not. Null before one."
            },
            "last_deployed_at": {
              "type": [
                "string",
                "null"
              ],
              "description": "The latest non-null `ended_at` of a deploy or promote row that ended `deployed`, across both environments. Rollbacks count. Restarts and failures do not. Null before one."
            },
            "deploy_count": {
              "type": "integer",
              "minimum": 0,
              "description": "The number of deploy or promote rows that ended `deployed` with a non-null `ended_at`, across both environments. Rollbacks count. Restarts and failures do not. Zero before one."
            },
            "production_deploy_count": {
              "type": "integer",
              "minimum": 0,
              "description": "The number of production deploy or promote rows that ended `deployed` with a non-null `ended_at`. Rollbacks count. Restarts and failures do not. Zero before one."
            },
            "features": {
              "type": "object",
              "description": "Feature flags from the current recorded manifest, the application's own resource rows and its environment count.",
              "required": [
                "database",
                "schedules",
                "end_user_sign_in",
                "storage",
                "custom_domain",
                "development_environment"
              ],
              "additionalProperties": false,
              "properties": {
                "database": {
                  "type": "boolean",
                  "description": "True when the current recorded manifest declares a database."
                },
                "schedules": {
                  "type": "boolean",
                  "description": "True when the current recorded manifest declares schedules."
                },
                "end_user_sign_in": {
                  "type": "boolean",
                  "description": "True when the current recorded manifest declares the accounts service or has a non-public audience."
                },
                "storage": {
                  "type": "boolean",
                  "description": "True when the application has a storage area of its own. Platform-held areas do not count."
                },
                "custom_domain": {
                  "type": "boolean",
                  "description": "True when the application has a custom domain that is not being detached."
                },
                "development_environment": {
                  "type": "boolean",
                  "description": "True when the application has two environments."
                }
              }
            }
          }
        }
      },
      "detail": {
        "type": "string"
      }
    }
  }
}
```

## 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/)
