--- title: "Check" canonical_url: "https://docs.getdx.com/webapi/types/check/" md_url: "https://docs.getdx.com/webapi/types/check.md" last_updated: "2026-05-19" --- # Check The definition for a single check contained in a Scorecard. ## Example ```json { "id": "y3ynphtim18c", "ordering": 5, "name": "Has Dockerfile", "description": "Service has a valid Dockerfile for containerization", "sql": "select 'PASS' as status", "filter_sql": "select ce.identifier\nfrom dx_catalog_entities ce\njoin dx_catalog_entity_types cet on cet.id = ce.entity_type_id\njoin dx_catalog_properties cp on cp.entity_type_id = cet.id and cp.identifier = 'cluster'\njoin dx_catalog_entity_properties cep on cep.entity_id = ce.id\nwhere cet.identifier = 'service';", "filter_message": "This check only applies to services with a `cluster` property defined", "output_enabled": true, "output_type": "custom", "output_custom_options": { "unit": "container", "decimals": 0 }, "output_aggregation": "mean", "estimated_dev_days": 1.5, "external_url": "https://docs.company.com/docker-guide", "published": true, "level": { "id": "vic57y3o11r4", "name": "Bronze" } } ``` ## Properties | Key | Type | Description | | ----------------------- | ----------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `id` | string | The check's unique ID. | | `ordering` | number | The ordering of this check within its container Level or Check Group. | | `name` | string | The check's name. | | `description` | string | The check's plain text description. | | `sql` | string | The query to execute in order to determine whether an entity is passing or failing. For more information, see [Writing Scorecard Checks](https://docs.getdx.com/scorecards/writing-checks/). | | `filter_sql` | string \| null | Optional SQL query that filters the relevant entities that this check will apply to. Must return an `identifier` column. | | `filter_message` | string \| null | If `filter_sql` is being applied, this message will show when viewing details for a check result. | | `output_enabled` | boolean | Whether to display a formatted value on a check result instead of a simple pass/warn/fail icon. | | `output_type` | string | The output formatting to apply. See [available output types](https://docs.getdx.com/webapi/types/check-output/#output-types). | | `output_custom_options` | `Output Custom Options` | Additional formatting configuration for the `custom` output type. See below for details. | | `output_aggregation` | string | When viewing the Checks Report grouped by team, this defines how to combine the output values of each check result. Available values are `mean`, `sum`, `count`, `min`, `max`, and `median`. | | `estimated_dev_days` | number \| null | Provides an estimate to entity owners about how long it will take to get a check passing for a single entity. Every check in an initiative must specify this. | | `external_url` | string \| null | The check's external URL, used for documentation or other instructions for passing the check. | | `published` | boolean | Whether this check is published or is still a draft. Draft checks do not impact an entity's level or points. | | `level` | object | For level-based scorecards, this lists the `id` and `name` of the [`Level`](https://docs.getdx.com/webapi/types/level/) under which this check is nested. | | `check_group` | object | For points-based scorecards, this lists the `id` and `name` of the [`Check Group`](https://docs.getdx.com/webapi/types/check-group/) under which this check is nested. | ## Additional properties required in a request body These properties define the [`Level`](https://docs.getdx.com/webapi/types/level/) or [`Check Group`](https://docs.getdx.com/webapi/types/check-group/) under which a check should be nested. | Key | Type | Description | | --------------------------- | ------ | ---------------------------------------------------------------------------------------------------------------------- | | `scorecard_level_key` | string | Required for level-based scorecards. The user-defined key of the level under which this check should be nested. | | `scorecard_check_group_key` | string | Required for points-based scorecards. The user-defined key of the check group under which this check should be nested. | ## Output Custom Options | Key | Type | Description | | ---------- | ---------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `unit` | string | The unit to show to the right of the value. Will be pluralized when shown in the UI. For example, a unit of widget will display as 1 widget or 2 widgets. | | `decimals` | "auto" \| number | Decimal precision for the value. A string value of "auto" will show the default amount of precision for a number provided by the check's SQL result set, whether an integer (e.g. 123) or a floating point number (e.g. 0.333333). A numeric value will set fixed precision at that many digits. For example, decimals: 2 will result in formatted values like 1.21 Jigawatts or 2.00 widgets. | --- ## Sitemap [Overview of all docs pages](/llms.txt)