---
title: "List a vault's columns"
method: GET
path: "/vaults/{id}/columns"
tags: ["Contract Intelligence"]
---

# List a vault's columns

`GET /vaults/{id}/columns`

## Request

- Base URL: `https://app.gc.ai/api/external/v1`
- URL: `https://app.gc.ai/api/external/v1/vaults/{id}/columns`
- Auth: API key in header `Authorization`
- TypeScript: <https://skmtc.dev/gc-ai/apis/gc-ai-external-api/docs/vaults/:id/columns/get.ts> (a function with typed inputs; its response is checked against the schema)

List every column in a vault's table, in the order the table shows them.

The list covers both kinds of column. Built-in columns, such as Document Type and Effective Date, come from GC AI and appear in every vault; they report `id: null` and `kind: built_in`, and no endpoint changes them. The rest belong to this vault and carry an ID. Of those, `kind: custom` columns are yours to change, and `kind: system` columns (Document Name, Document Status, Document Title) are managed by GC AI and reject every change.

Columns a member has hidden in the app are listed too: hiding is a display preference, and a hidden column still holds its values and still counts toward the vault's 500 column limit.

Requires a user-scoped API key (`u:gcai_...`). A vault is shared with named people, so an organization-scoped key has no identity to resolve vault access with.

## Path parameters

- `id` string, uuid, required: The vault ID

## Response `200`

The vault's columns

- VaultColumnListResponse
  - `columns` VaultColumnResponse[], required
    - `id` string, uuid, nullable, required: Unique column identifier, or null for a built-in column. A built-in column has no row of its own in this vault, so it has no ID and cannot be changed or deleted.
    - `field_key` string, required: The stable key extracted values are stored under. It is set once, when the column is created, and never changes, so renaming the column keeps every value already extracted for it.
    - `label` string, required: The column heading shown in the vault table
    - `instructions` string, required: For an `ai` column, the prompt extraction reads each document with. For a `manual`, `import`, or `connector` column, a note to whoever reads the column.
    - `field_type` 'text' | 'date' | 'date_range' | 'enum' | 'multi_enum' | 'boolean' | 'number' | 'currency' | 'percentage' | 'duration' | 'email' | 'url' | 'list' | 'rich_text' | 'party_list' | 'related_agreement_list', required: The shape of the values in this column. Built-in columns can report `party_list` and `related_agreement_list`, which you cannot set yourself.
    - `field_meta` union, required: The option list for an `enum` or `multi_enum` column. Null for every other type.
      - object
        - `type` 'enum', required
        - `options` string[], required: The values extraction can assign to this column.
        - `legacy_options` string[]: Values that documents extracted under an older version of this option list still hold. They stay readable and filterable, and extraction never assigns them again.
      - object
        - `type` 'multi_enum', required
        - `options` string[], required: The values extraction can assign to this column.
      - unknown
    - `extraction_mode` 'ai' | 'manual' | 'import' | 'connector', required: How the column gets filled. `ai`: extraction reads it out of each document. `manual`: a person types it and no scan ever touches it. `import`: values come from a connected spreadsheet, which owns the column. `connector`: values come from a connected document source, which owns the column. You can create `ai` and `manual` columns. An `import` column is created by connecting a spreadsheet in the app. A `connector` column is created when a source such as Ironclad fills it.
    - `kind` 'built_in' | 'system' | 'custom', required: What this column is. `built_in`: merged into every vault by GC AI, with no ID and no way to change it. `system`: owned by this vault but managed by GC AI (Document Name, Document Status, Document Title), so it has an ID but rejects every change and every delete. `custom`: yours, and the only kind `PATCH` and `DELETE` accept.
    - `editable` boolean, required: True when this column can be changed with `PATCH /vaults/{id}/columns/{columnId}`. Built-in and system columns report `false`: GC AI owns their name, type, options, and prompt. One exception, on both surfaces: `sort_order` is list position rather than identity, so it can be set on any column that has an ID.
    - `sort_order` number, nullable, required: Placement weight for this column, or null for a built-in one. The table orders columns by `sort_order` first and creation time second.
    - `created_at` string, nullable, required: ISO 8601 creation timestamp, or null for a built-in column
    - `updated_at` string, nullable, required: ISO 8601 last-update timestamp, or null for a built-in column

## Other responses

- `401`: Missing or malformed API key
- `403`: Contract Intelligence is not enabled for this account. Contact support to request access.
- `404`: Vault not found, archived, or access denied
- `422`: Vault access is per-user and requires a user-scoped API key (u:gcai_...).
- `429`: Rate limit exceeded. See [Rate Limits](https://docs.gc.ai/api-reference/concepts/rate-limits) for the tiers, limits, and how to back off.
- `500`: Internal server error
- `503`: Service temporarily unavailable

---

[API](https://skmtc.dev/gc-ai/apis/gc-ai-external-api.md) - [All operations](https://skmtc.dev/gc-ai/apis/gc-ai-external-api/llms.txt) - [OpenAPI document](https://skmtc.dev/gc-ai/apis/gc-ai-external-api/revisions/2bbdfddf7107?raw)