---
title: "Read an install"
method: GET
path: "/v1/installs/{installId}"
tags: ["Installs"]
---

# Read an install

`GET /v1/installs/{installId}`

## Request

- Base URL: `https://api.banksync.io`
- URL: `https://api.banksync.io/v1/installs/{installId}`
- Auth: one of:
  - API key in header `X-API-Key`
  - HTTP bearer

One install and every resource it made, adopted or linked, with each one’s status and workspace id. A step skipped because the plan did not include it says “Included on <Plan>: …”; `planIncludedNow` lists those the plan includes now (`PATCH` with `action: "addPlanIncluded"` makes them).

## Path parameters

- `installId` string, required: Install id, from the list

## Response `200`

The install and its resources

- object
  - `success` true, required
  - `data` object, required
    - `install` object, required
      - `id` string, required: Install id — the `installId` other operations take
      - `name` string, required
      - `source` 'listing' | 'app' | 'workspace' | 'preset' | 'inline', required
      - `listingId` string, nullable, required
      - `releaseId` string, nullable, required
      - `blueprintId` string, nullable, required
      - `blueprintKey` string, nullable, required
      - `status` 'installing' | 'installed' | 'partial' | 'removing' | 'removed', required
      - `generation` integer, required
      - `error` string, nullable, required
      - `createdAt` string, nullable, required
      - `updatedAt` string, nullable, required
      - `removedAt` string, nullable, required
      - `removeMode` 'keep' | 'trash' | 'null', nullable, required
      - `planIncludesMore` boolean
      - `bindings` object, required
    - `resources` object[], required
      - `key` string, required
      - `kind` string, required
      - `resourceId` string, nullable, required
      - `mode` 'created' | 'adopted' | 'linked', required
      - `status` 'pending' | 'created' | 'skipped' | 'failed' | 'removed', required
      - `userModified` boolean, required
      - `error` string, nullable, required
      - `appliedAt` string, nullable, required
      - `keptFor` object: A removed row whose resource stays because another install still uses it (a shared table, feed or enrichment)
        - `installId` string, required
        - `installName` string, required
      - `sharedWith` object[]: installs_get: the other live installs that also use this shared table, feed or enrichment. Removing this install (either mode) keeps it for them — it is never trashed while one of them uses it
        - `installId` string, required
        - `installName` string, required
    - `planIncludedNow` object[]
      - `resourceKey` string, required
      - `kind` string, required
      - `name` string, required
      - `plan` string, required: The lowest plan that includes it (`professional`)
      - `planLabel` string, required
      - `adds` string, required: What it adds, in words ("AI categorising")
      - `reason` string, required: "Included on Professional: AI categorising"
      - `requirement` 'count': `count`: what the template makes needs more of a capped thing (tables, a bank connection) than lower plans allow, so it needs this plan to install. Absent: a plan-gated step, skipped below its plan.

## Other responses

- `400`: Invalid input — `code` names it: `VALIDATION_FAILED`, `INVALID`, `INVALID_BLUEPRINT` (not a blueprint this workspace can read), `PORTABILITY_VIOLATION` (it still carries workspace ids), `UNSAFE_BLUEPRINT`, `INVALID_BINDINGS` (an input is missing or does not fit), `RESTORE_WINDOW_PASSED`; `details[]` names each field
- `401`: Unauthorized
- `403`: Forbidden — a missing `marketplace:read` / `marketplace:write` scope, a role below editor for a change, an installed app outside the public marketplace, an unverified listing already installed in ten workspaces (`INSTALL_CAP_REACHED`), or a template that needs more tables, feeds or enrichments than the workspace plan has left (`PLAN_LIMIT_REACHED`)
- `404`: Not found — something this workspace may not see answers exactly as something that does not exist; or the marketplace is not enabled for this workspace
- `409`: Conflict — it changed since you read it (`STALE`), it is busy or in the wrong state (`INVALID_STATE`), the listing cannot be installed (`NOT_INSTALLABLE`), a key is taken (`KEY_TAKEN`), or an existing container does not fit (`ADOPTION_CONFLICT`)
- `429`: Too many — the key’s rate limit, or a marketplace quota (`QUOTA_EXCEEDED`: 200 saved templates per workspace, 50 installs per hour). `Retry-After` says when to come back.
- `503`: The marketplace is temporarily unavailable; retry shortly

---

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