Unified Catalog Entity List¶

POST /api/v1/unified_catalog/entity/list

Overview¶

Retrieve the list of entities in the Unified Catalog under the current workspace. Entity data is queried by Studio via Kodo.

Body Request Parameters¶

Parameter	Type	Description
pageIndex	integer	Page number, default `1` Allow empty: False Example: `1` $minValue: 1 $maxValue: 10000
pageSize	integer	Items per page, default `20`, max `200` Allow empty: False Example: `20` $minValue: 1 $maxValue: 200
urn	string	Exact filter by entity URN Allow empty: False
entityType	string	Entity type code; required when filtering or sorting by health fields Allow empty: False
provider	string	Single source type. For multiple values, consider using `providers` instead Allow empty: False
providers	array	List of source types, e.g. `["discovery", "manual"]` Allow empty: False
search	string	Fuzzy search, matching `urn`, `name`, `display_name` Allow empty: False
filters	json	Filter on `attributes` fields; also supports top-level health fields. Health filtering requires `entityType` to be specified simultaneously Allow empty: False Example: `{'env': ['prod'], 'project': ['demo']}`
orderBy	string	Sort field, default `updatedAt`; sorting by health fields requires `entityType` to be specified simultaneously Allow empty: False
order	string	Sort direction, supports `asc` / `desc`, default `desc` Allow empty: False

Additional Parameter Notes¶

Request Parameter Explanation

Parameter	Type	Required	Description
pageIndex	integer	No	Page number, default `1`
pageSize	integer	No	Items per page, default `20`, max `200`
urn	string	No	Exact filter by entity URN
entityType	string	No	Entity type code; required when filtering or sorting by health fields
provider	string	No	Single source type
providers	array[string]	No	List of source types
search	string	No	Fuzzy search, matching `urn`, `name`, `display_name`
filters	json	No	Filter on `attributes` fields; also supports top-level health fields. Health filtering requires `entityType` to be specified simultaneously
orderBy	string	No	Sort field, default `updatedAt`; sorting by health fields requires `entityType` to be specified simultaneously
order	string	No	Sort direction, supports `asc` / `desc`, default `desc`

Usage Notes for filters

Regular keys match entity attributes; healthStatus/healthScore/healthUpdateAt/brokenComponents and their snake_case aliases match valid top-level health fields of the entity.
Example: {"env":["prod"],"project":["demo"]}; health filtering example: {"healthStatus":["warning"]}.
If an attribute needs to match multiple values, place them in an array.

Calling Notes

This is a paginated endpoint. It is recommended to always explicitly pass pageIndex and pageSize.
Use either provider or providers; for multiple source values, use providers.
pagination.totalCount in the response indicates the total number of entities matched by the current filter criteria.
Each entity always returns healthConfig/healthEnabled/healthScore/healthStatus/healthUpdateAt; all types return these fields based on the effective configuration, regardless of background readiness cleanup progress.

Request Example¶

curl 'https://openapi.guance.com/api/v1/unified_catalog/entity/list' \
-H 'DF-API-KEY: <DF-API-KEY>' \
-H 'Content-Type: application/json;charset=UTF-8' \
--data-raw '{"pageIndex":1,"pageSize":20,"entityType":"database","filters":{"env":["prod"]}}'

Response¶

{
    "code": 200,
    "content": {
        "items": [
            {
                "urn": "urn:mysql:default:demo",
                "entityType": "database",
                "name": "demo",
                "provider": "manual",
                "attributes": {
                    "project": "demo",
                    "env": "prod"
                },
                "healthConfig": {},
                "healthEnabled": false,
                "healthScore": null,
                "healthStatus": "unknown",
                "healthUpdateAt": null,
                "teamInfo": [],
                "tagsInfo": []
            }
        ],
        "pagination": {
            "pageIndex": 1,
            "pageSize": 20,
            "count": 1,
            "totalCount": 1
        }
    },
    "errorCode": "",
    "message": "",
    "success": true,
    "traceId": "TRACE-XXXX"
}