> ## Documentation Index
> Fetch the complete documentation index at: https://docs.squarecloud.app/llms.txt
> Use this file to discover all available pages before exploring further.

# List deployments

> List the recent Git deploys of an application with GET /v2/apps/{app_id}/deployments, with each state from pending to success, or the error code.

<ParamField header="Authorization" type="string" placeholder="API Key" required>
  The API key for your account. You can find this in your [account settings](https://squarecloud.app/en/account/security).
</ParamField>

Requires an API key with the `apps:read` [scope](/en/api-reference/authentication#scopes).

Use this endpoint to inspect what happened during recent deploys: each inner array captures one deploy attempt's lifecycle, moving through the `pending`, `clone`, `commit`, `restarting` and `success` states. A deploy that fails ends in an `error` event that carries a `code` (for example `AUTHENTICATION_REQUIRED`, `INVALID_BRANCH` or `CLONE_FAILED`) and, sometimes, a `message` with details. There is no `failed` state.

Only Git deploys, from a [webhook](/en/api-reference/endpoint/apps/deploy/webhooks) or a [GitHub App](/en/api-reference/endpoint/apps/deploy/github-app-link) push, are recorded, so every event's `source` is `git`. Zip uploads and [Commit Application](/en/api-reference/endpoint/apps/commit) calls don't appear here.

The deploy log comes from a short-lived cluster cache, so it only reflects the application's most recent activity and returns an empty array once nothing remains recorded. To check the currently configured Git integration instead of past deploy attempts, see [Get Current Deployment](/en/api-reference/endpoint/apps/deploy/info).

## Parameters

<ParamField path="app_id" type="string" placeholder="Application ID" required>
  The ID of the application. You can find this in the URL of your application's dashboard.
</ParamField>

## Response

<ResponseField name="status" type="string">
  Indicates whether the call was successful: `success` if it was, `error` if not.
</ResponseField>

<ResponseField name="response" type="array">
  The contents of the response.

  <Expandable title="Toggle object">
    <ResponseField name="id" type="string">
      The ID of the deploy.
    </ResponseField>

    <ResponseField name="state" type="string">
      The state of the deploy: `pending`, `clone`, `commit`, `restarting`, `success` or `error`.
    </ResponseField>

    <ResponseField name="date" type="string">
      The date of the event.
    </ResponseField>

    <ResponseField name="source" type="string">
      Always `git`.
    </ResponseField>

    <ResponseField name="code" type="string">
      Only on `error` events: why the deploy failed, for example `AUTHENTICATION_REQUIRED`, `INVALID_BRANCH` or `CLONE_FAILED`.
    </ResponseField>

    <ResponseField name="message" type="string">
      Only on some `error` events: details about the failure.
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseExample>
  ```json theme={"system"}
  {
      "status": "success",
      "response": [
          [
              { "id": "96b1c6931c20b1555e612d3c8cd0a7b36f0fd5c7", "state": "pending", "date": "2026-05-28T21:47:33.608Z", "source": "git" },
              { "id": "96b1c6931c20b1555e612d3c8cd0a7b36f0fd5c7", "state": "clone", "date": "2026-05-28T21:47:34.019Z", "source": "git" },
              { "id": "96b1c6931c20b1555e612d3c8cd0a7b36f0fd5c7", "state": "commit", "date": "2026-05-28T21:47:36.240Z", "source": "git" },
              { "id": "96b1c6931c20b1555e612d3c8cd0a7b36f0fd5c7", "state": "restarting", "date": "2026-05-28T21:47:37.105Z", "source": "git" },
              { "id": "96b1c6931c20b1555e612d3c8cd0a7b36f0fd5c7", "state": "success", "date": "2026-05-28T21:47:41.872Z", "source": "git" }
          ]
      ]
  }
  ```
</ResponseExample>

## Related

* CLI: [`squarecloud app deploy list`](/en/cli-reference/github-deploys#squarecloud-app-deploy-list)
* SDKs: [`api.apps.deploys.list()`](/en/sdks/js/deploys) (JavaScript), [`client.apps.deploys.list()`](/en/sdks/py/deploys) (Python), [`c.Apps.Deploys.List()`](/en/sdks/go/deploys) (Go)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.