# (NEW!) List Metadata Cascades (Paginated)

Retrieve a paginated, searchable list of metadata cascades for UI consumption. Response fields are lightweight by default (counts only); full level/value detail is available via GET /metadata/cascades/{id} or via the include query parameter.

Defaults:
- sortField defaults to name.
- order defaults to asc.
- from defaults to 0.
- limit defaults to 100 — or 20 if include contains values, regardless of the value requested.

Business Rules:
- searchTerm is a case-insensitive partial match on cascade name.
- inUse accepts a boolean (true/false — aggregate: used anywhere at all) or one of metadataTables, metadataGroups, metadataTemplates, filtering to cascades referenced in that specific usage category. Omitted applies no filter. inUse is also a valid sortField value.
- includeSystem defaults to false. When true, also returns read-only, platform-owned cascades used internally by various platform functionalities, alongside user-created ones. System cascades cannot be edited or deleted by users.
- include is a comma-separated list of levels, values. Omitted returns summary fields only (levelCount/valueCount); include=levels adds levels[] per row; include=values adds values[] per row and clamps limit to 20; include=levels,values returns both.
- usedIn is shaped { metadataTables: [], metadataGroups: [], metadataTemplates: [] } — metadataGroups is a derived, transitive rollup through Table → group, and metadataTemplates a further rollup through group → template; neither is a direct reference.

The user submitting the request must have the Metadata Template Management admin privilege.

Endpoint: GET /metadata/cascades
Version: 1.5
Security: ApiKeyAuth, BasicAuth

## Header parameters:

  - `Authorization` (string, required)
    Provided by Authentication Token creation operation.

## Query parameters:

  - `searchTerm` (string)
    Case-insensitive partial match on cascade name.

  - `inUse` (string)
    Filters by usage status. true/false filters on aggregate usage (referenced anywhere at all). One of metadataTables, metadataGroups, metadataTemplates filters to cascades referenced in that specific usage category. Omitted applies no filter.
    Enum: "true", "false", "metadataTables", "metadataGroups", "metadataTemplates"

  - `includeSystem` (boolean)
    When true, also returns read-only, platform-owned cascades used internally by various platform functionalities, in addition to user-created ones. System cascades cannot be edited or deleted by users. Defaults to false.

  - `from` (integer)
    Result offset from which to start. Defaults to 0.

  - `limit` (integer)
    Number of results to return per page. Defaults to 100, maximum 100 — clamped to 20 when include contains values.
    Example: 100

  - `sortField` (string)
    Field to sort results by. Defaults to name.
    Enum: "name", "createdEpoch", "lastUpdatedEpoch", "inUse"

  - `order` (string)
    Sort direction. Defaults to asc.
    Enum: "asc", "desc"

  - `include` (string)
    Comma-separated additional data to return per row. levels, values, or both. Omitted returns summary fields only.
    Example: "levels,values"

## Response 200 fields (application/json):

  - `hitCount` (integer)
    Total number of cascades matching the search criteria.
    Example: 9

  - `results` (array)
    Array of cascade summary objects.

  - `results.id` (string)
    Unique ID of the cascade.
    Example: "b7e41f2a-6c9d-4a17-8f3b-2d5c8a0e3f61"

  - `results.name` (string)
    Display name of the cascade.
    Example: "Region Cascade"

  - `results.searchField` (string)
    System-generated slug. Permanent once created.
    Example: "region_cascade"

  - `results.nameVisible` (boolean)
    Whether the cascade name is visible when rendered on an asset.
    Example: true

  - `results.featured` (boolean,null)
    System-assigned. null if never set. Blocks deletion when true.

  - `results.levelCount` (integer)
    Number of levels defined on the cascade (maximum 4). Always present.
    Example: 2

  - `results.levels` (array)
    Ordered levels. Only present when the include query parameter contains levels; same shape as GET /metadata/cascades/{id}'s levels.

  - `results.levels.attributeId` (string)
    Id of the controlled-vocabulary attribute backing this level's dropdown values.
    Example: "a29f3e1c-7b4d-4f8a-9c2e-5d1b8f6a3c70"

  - `results.levels.attributeName` (string)
    Denormalized display name of the backing attribute.
    Example: "Continent"

  - `results.levels.order` (integer)
    Zero-based level position.

  - `results.valueCount` (integer)
    Total value nodes across the whole tree, all levels combined. Always present.
    Example: 12

  - `results.values` (array)
    Full nested value tree. Only present when the include query parameter contains values; same shape as GET /metadata/cascades/{id}'s values.

  - `results.values.id` (string)
    Value node id.
    Example: "f3a8c1e5-9d24-4b7a-8e6f-1c3a9d5e2b74"

  - `results.values.name` (string)
    Display value.
    Example: "North America"

  - `results.values.source` (string,null)
    Present only when this level's attribute is a Dynamic Controlled Vocabulary (a CV composed from other CVs) — holds the search field of the underlying source CV this value was copied from. null for a value sourced from an ordinary controlled vocabulary. System-computed only; never client-supplied.

  - `results.values.children` (array)
    Nested child values at the next level. Empty array for a leaf node.

  - `results.createdBy` (string)
    User-profile id of the cascade's creator.
    Example: "8f2a5c91-4e6d-4b83-9a17-6c0d3e8b2f45"

  - `results.createdEpoch` (integer)
    Unix timestamp (ms) of creation.
    Example: 1770714900000

  - `results.createdDate` (string)
    ISO 8601 creation date.
    Example: "2026-02-10T09:15:00Z"

  - `results.lastUpdatedBy` (string)
    User-profile id of the last user to update the cascade.
    Example: "8f2a5c91-4e6d-4b83-9a17-6c0d3e8b2f45"

  - `results.lastUpdatedEpoch` (integer)
    Unix timestamp (ms) of the last update.
    Example: 1771432800000

  - `results.lastUpdatedDate` (string)
    ISO 8601 last-updated date.
    Example: "2026-02-18T16:40:00Z"

  - `results.inUse` (boolean)
    Derived from usedIn — true when any of usedIn.metadataTables, usedIn.metadataGroups, or usedIn.metadataTemplates is non-empty.
    Example: true

  - `results.usedIn` (object)
    Where the cascade is currently referenced. A cascade's only direct relationship is being used as a column inside a Table. metadataGroups is a derived, transitive rollup of every group reached through that table's own group membership (Table → group). metadataTemplates is a further derived, transitive rollup of every template reached through that group's own template membership (group → template).

  - `results.usedIn.metadataTables` (array)
    Tables that directly use this cascade as a column.

  - `results.usedIn.metadataTables.id` (string)
    Example: "e91a4c7d-3f8b-4e26-9a1d-7c5b0e9f2a83"

  - `results.usedIn.metadataTables.name` (string)
    Example: "Store Locations Table"

  - `results.usedIn.metadataGroups` (array)
    Groups that transitively reach this cascade through a table that uses it.

  - `results.usedIn.metadataTemplates` (array)
    Templates that transitively reach this cascade through a table that uses it.

## Response 400 fields (application/json):

  - `status` (string)
    Example: "error"

  - `message` (string)

## Response 401 fields (application/json):

  - `status` (string)
    Example: "error"

  - `message` (string)

## Response 403 fields (application/json):

  - `status` (string)
    Example: "error"

  - `message` (string)