---
title: "List Deployments"
method: GET
path: "/deployment"
tags: ["deployments"]
---

# List Deployments

`GET /deployment`

## Request

- Base URL: `https://api.faable.com`
- URL: `https://api.faable.com/deployment`
- Auth: one of:
  - OAuth 2 (authorization code, authorization URL `https://faable.auth.faable.link/authorize`, token URL `https://faable.auth.faable.link/oauth/token`)
  - HTTP bearer
  - OAuth 2 (client credentials, token URL `https://faable.auth.faable.link/oauth/token`)
  - HTTP bearer
  - HTTP basic
  - API key in query parameter `apikey`

List Deployments

## Query parameters

- `pageSize` number
- `cursor` string
- `next` string
- `count` boolean
- `query` string

## Response `200`

Default Response

- object
  - `next` string, required
  - `results` Deployment[], required
    - `id` string, required: Deployment ID
    - `team` string, required
    - `app_id` string, required
    - `image` string
    - `release` string
    - `github_commit` string
    - `github_ref` string
    - `github_actor` string
    - `github_commit_message` string
    - `artifact_id` string
    - `artifact_ready_at` string, date-time
    - `build_started_at` string, date-time
    - `build_ms` integer
    - `redeploy_of` string
    - `rebuild_of` string
    - `runtime_fallback` object
      - `name` string, required
      - `from` string, required
      - `to` string, required
      - `of` string, required
    - `runtime_fallback_retry` object
      - `to` string, required
      - `at` string, date-time, required
      - `deployment_id` string
    - `runtime_upgrade` object
      - `name` string, required
      - `to` string, required
      - `previous` object, required
        - `name` string, required
        - `version` string, required
        - `pinned_at` string, date-time, required
        - `source` string, required
    - `quota_released_at` string, date-time
    - `trigger` string
    - `detected` DeploymentDetected
      - `buildpack` string, required
      - `framework` string
      - `runtime` object, required
        - `name` string, required
        - `version` string
        - `source` string
      - `dockerfile_ignored` boolean
      - `process_type` 'worker'
    - `status` DeploymentStatus, required
      - `phase` 'UNKNOWN' | 'QUEUED' | 'BUILDING' | 'ERROR' | 'BUILD_ERROR' | 'INITIALIZING' | 'READY' | 'CANCELED' | 'TERMINATING' | 'SUPERSEDED' | 'QUOTA_HOLD', required: High-level summary of where the Deployment is in its lifecycle
      - `controlled_at` string, date-time: When a controller took control of this deployment
      - `controlled_by` string: INSTANCE_NAME of the controller that claimed it
      - `reason` string: Why the deployment failed (shown to the user on ERROR)
      - `failure_code` string: Producer's own name for what failed (e.g. detect_no_buildpack). Not the fault taxonomy.
      - `failure_detail` object: Structured context the producer had before writing `reason` (found_files, subdir_hits, workdir, root_dir…). Never free build output: it must carry no repository paths beyond the entry names detection already lists.
      - `cold_state` union: Scale-to-zero sub-state (admin-only): asleep, waking or null
        - 'asleep'
        - 'waking'
      - `resource_limit` object: Last hard resource limit (memory or disk) this deployment hit
        - `state` union, required: Which limit was hit
          - 'memory_exceeded'
          - 'disk_exceeded'
        - `at` string, required: ISO time the limit was last hit
        - `count` integer, required: How many times this deployment hit it
      - `runtime_image` string: Runtime image (immutable version tag) this artifact deployment runs
      - `fetcher_image` string: Fetcher image (immutable version tag) of the artifact-prepare initContainer
      - `builder_image` string: Builder image (immutable version tag) that built this deployment
    - `metadata` object, required
    - `createdAt` string, required: Deployment creation date
    - `updatedAt` string: Deployment updated date
  - `total` integer: Rows matching the whole filter, across every page. Only with `?count=true`.

## Other responses

- `400`: `invalid_query` — The `?query=` FaableQL expression could not be parsed. `invalid_expand` — An `?expand=` path is not allowed on this resource. `search_not_supported` — This resource does not support `?q=`. `validation_error` — The body, query or path failed schema validation. `details.issues` lists each failing field.
- `401`: `team_or_scope_required` — Listing needs either a project in the `x-faable-project` header or a global scope on the token. `unauthorized` — The request carries no valid credentials. `invalid_token` — The bearer token is missing, malformed or expired.
- `403`: `forbidden` — The credentials are valid but do not allow this operation. `user_suspended` — The account is suspended. Contact support@faable.com.
- `429`: `too_many_requests` — Rate limit exceeded. Honour the `Retry-After` header.
- `500`: `internal_error` — Unexpected server error. Retry later; the request id is logged.
- `503`: `database_unavailable` — Faable cannot reach its database right now. Transient: retry after the `Retry-After` header.

---

[API](https://skmtc.dev/faable/apis/faablecloud-api.md) · [All operations](https://skmtc.dev/faable/apis/faablecloud-api/llms.txt) · [OpenAPI document](https://skmtc.dev/faable/apis/faablecloud-api/revisions/e2fc93da3c49?raw)