---
title: "List Apps"
method: GET
path: "/app"
tags: ["apps"]
---

# List Apps

`GET /app`

## Request

- Base URL: `https://api.faable.com`
- URL: `https://api.faable.com/app`
- 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 Apps

## Query parameters

- `pageSize` number
- `cursor` string
- `next` string
- `count` boolean
- `query` string
- `expand` string[]

## Response `200`

Default Response

- object
  - `next` string, required
  - `results` App[], required
    - `id` string, required: App ID
    - `team` string, required
    - `name` string, required
    - `description` string, required
    - `slug` string, required
    - `url` string, required
    - `active` boolean, required
    - `disabled_reason` string: Reason the app was administratively disabled. Null when the app is active.
    - `runtime` 'node' | 'php' | 'python', required
    - `runtime_strategy` string, required
    - `detected` object
      - `buildpack` string, required
      - `framework` string
      - `runtime` object, required
        - `name` string, required
        - `version` string
        - `source` string
      - `dockerfile_ignored` boolean
      - `process_type` 'worker'
    - `runtime_pin` object
      - `name` string, required
      - `version` string, required
      - `pinned_at` string, date-time, required
      - `source` union, required
        - 'first_build'
        - 'backfill'
        - 'user_upgrade'
        - 'retirement'
    - `mode` 'standard' | 'coexistence', required
    - `build_mode` 'local' | 'remote'
    - `deploy_output` 'image' | 'artifact'
    - `root_dir` string
    - `gitlab_ci_project_id` string
    - `git_provider` union
      - 'github'
      - 'gitlab'
    - `gitlab_project_id` string
    - `gitlab_project_path` string
    - `gitlab_branch` string
    - `coexistence_routing` 'cookie' | 'path'
    - `coexistence_keep_versions` number: K: how many versions stay live under mode=coexistence (active + K-1 draining)
    - `coexistence_drain_hours` number: Max hours a demoted version keeps serving pinned sessions before GC
    - `instance` string: Compute catalogue row the app runs on (computeinstance id). Replaces instance_type.
    - `instance_type` string, required: Faable instance types comprise varying combinations of CPU, memory, storage, and networking capacity. Name of `instance`; kept for existing clients.
    - `instance_resources` object: The most CPU and memory the app can use on its instance (the limits). Read-only, derived from `instance`.
      - `cpu` string, required: Kubernetes quantity, e.g. '600m'
      - `memory` string, required: Kubernetes quantity, e.g. '512Mi'
    - `instance_upgrades` object[]: Each plan's default instance that gives more than this app's, smallest first. Read-only.
      - `plan` string, required: free | hobby | pro
      - `instance` string, required
      - `cpu` string, required
      - `memory` string, required
    - `region` 'gui1' | 'poz1' | 'ams1', required: High-level summary of where the Database is in its lifecycle
    - `notify_deploy_success` boolean: Success deploy emails (first deploy + every promote). Absent/null = enabled; false = muted. Failure emails are never gated by this.
    - `http3` boolean: Whether HTTP/3 is advertised for this app. Absent/null = advertised; false = not advertised. Note it controls the advertisement, not the listener: clients that already discovered HTTP/3 may keep using it until the advertisement expires, and the server does not refuse it.
    - `status` AppStatus, required
      - `phase` 'UNKNOWN' | 'QUEUED' | 'BUILDING' | 'ERROR' | 'INITIALIZING' | 'READY' | 'CANCELED' | 'TERMINATING', required: High-level summary of where the Database is in its lifecycle
      - `deployment` union, required
        - string: Deployment id for this app
        - object: Full Deployment object, present only when expanded via `?expand=status.deployment`
      - `deployment_previous` union, required
        - string: Previous deployment id for this app
        - object: Full Deployment object, present only when expanded via `?expand=status.deployment`
      - `last_commited_purge` string, nullable, required: Last commited cache Purge
      - `last_commited_purge_key` string, nullable, required: Last commited cache Purge key
      - `last_commited_purge_service` string, nullable, required: Last commited cache Purge key
      - `versions` object[], required: Live versions of the app: the promoted one plus any draining (coexistence) versions
        - `deployment` string, required: Deployment id of this version
        - `role` union, required: promoted = current production; coexisting = draining
          - 'promoted'
          - 'coexisting'
        - `promoted_at` string, required: ISO date this version was promoted
        - `drain_until` string, required: GC-eligibility deadline for a coexisting version (demotion + drain window). Null on the promoted entry.
      - `cold_state` union: Scale-to-zero sub-state of the promoted deployment (admin-only)
        - 'asleep'
        - 'waking'
      - `secrets_revision` string, nullable, required: Opaque revision token; changes whenever the app secrets change
      - `resource_health` object: Resource-limit breach observed at runtime
        - `state` union, required: Which limit was hit
          - 'memory_exceeded': The runtime exceeded its memory limit (OOMKilled)
          - 'disk_exceeded': The pod was evicted for exceeding its disk (ephemeral-storage) limit
        - `deployment` string, required: Deployment whose pod tripped the limit
        - `at` string, required: ISO time the limit was last observed being hit
        - `container` string, nullable: Container that was OOMKilled
      - `runtime_health` object: Runtime crash loop observed on the live version
        - `state` 'crash_loop', required: The container keeps exiting and being restarted (CrashLoopBackOff)
        - `deployment` string, required: Deployment whose pod is crash-looping
        - `at` string, required: ISO time the crash loop was last observed
        - `container` string, nullable: Container that is crash-looping
        - `restarts` integer, nullable: Restart count when observed
        - `exit_code` integer, nullable: Last exit code, when reported
        - `reason` string, nullable: K8s waiting/terminated reason
    - `repository` string
    - `github_branch` string
    - `github_installation_id` string
    - `github_installation_state` string: Platform GitHub access health, maintained by installation lifecycle webhooks. Absent/null = ok; 'deleted' | 'suspended' | 'repo_removed' = access broken until re-linked.
    - `github_repo_hidden` string: The linked repository stopped being readable after the app was created, per the GitHub `repository` webhook. Absent/null = visible; 'deleted' | 'privatized' | 'archived' = the source was pulled after deploying (the analyzer re-scores the promoted deployment against our own build artifact).
    - `github_disconnect_reason` string: Why the platform cleared the repository link automatically. Absent/null = never auto-disconnected (or re-linked since); 'push_flood' = the repo exceeded the hourly push limit and must be re-linked by the user.
    - `deploy_trigger` string: Push-to-deploy trigger. Absent/null = 'workflow' (committed GitHub Action); 'webhook' = the push webhook creates deployments server-side (deploy v4).
    - `deploy_gate` string: Wait-for-CI gate for webhook triggers. Absent/null = deploy on push; 'ci' = deploy only after the commit's check suites complete green.
    - `metadata` object, required
    - `createdAt` string, required: App creation date
    - `updatedAt` string: App 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)