> For the complete documentation index, see [llms.txt](https://developer.collibra.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://developer.collibra.com/api/references/control-execution/controls.md).

# Controls

Manage and monitor control executions. Use these endpoints to retrieve execution statuses, trigger on-demand control runs, and track failed controls. Supports filtering by asset to identify which controls have failed for specific resources.

## List failed controls

> Returns a list of controls that have failed.\
> \
> It is possible to pass an asset ID to filter the controls and only return the controls that have failed for that\
> specific asset.\
> \
> Returns only the controls on which the authenticated user has view permissions.<br>

```json
{"openapi":"3.1.0","info":{"title":"Collibra Control Execution API","version":"1.0.0"},"tags":[{"name":"Controls","description":"Manage and monitor control executions. Use these endpoints to retrieve execution statuses,\ntrigger on-demand control runs, and track failed controls. Supports filtering by asset to\nidentify which controls have failed for specific resources.\n"}],"servers":[{"url":"/rest/controlExecution/v1"}],"security":[{"basicAuth":[]}],"components":{"securitySchemes":{"basicAuth":{"description":"This API requires Basic HTTP authentication.","type":"http","scheme":"basic"}},"parameters":{"assetId":{"name":"assetId","in":"query","required":false,"description":"The unique identifier of the asset.\n","schema":{"type":"string","format":"uuid"}},"cursor":{"name":"cursor","in":"query","required":false,"description":"The cursor pointing to the first resource to be included in the response. This cursor cannot be created and must\nhave been extracted from a response returned by a previous API call.\n\nIf not set, the response starts from the first available resource.\n","schema":{"type":"string"}},"limit":{"name":"limit","in":"query","required":false,"description":"The maximum number of resources to retrieve.\n\nIf not set, the default value is 100. The maximum value is 500.\n","schema":{"type":"integer","default":100,"maximum":500,"minimum":1}},"controlSortField":{"name":"sortField","in":"query","required":false,"description":"The field on which the controls are sorted. The default value is `NAME`.\n","schema":{"type":"string","default":"NAME","enum":["NAME","SEVERITY","TYPE","FAILED_SINCE"]}},"sortOrder":{"name":"sortOrder","in":"query","required":false,"description":"The sorting order. The default value is `ASC`.\n","schema":{"type":"string","default":"ASC","enum":["ASC","DESC"]}},"includeTotal":{"name":"includeTotal","in":"query","required":false,"description":"Whether to include the total number of resources in the response.\n\nIf `true`, the response will include the total number of resources (`total`), as well as a boolean indicating if\nthe total is approximate (`isTotalApproximate`).\n\nIf `false`, the response will not include the total number of resources (`total` and `isTotalApproximate`).\n","schema":{"type":"boolean","default":true}}},"responses":{"FailedControlsResponse":{"description":"Response containing the failed controls for a specific asset with pagination support.\n","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PaginatedFailedControls"}}}},"BadRequest":{"description":"The request contains invalid parameters or is missing required data. Details about the validation errors are\nprovided in the response.\n","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StandardErrorResponse"}}}},"InternalServerError":{"description":"The server encountered an unexpected condition that prevented it from fulfilling the request. The error details\nprovide information for troubleshooting.\n","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StandardErrorResponse"}}}}},"schemas":{"PaginatedFailedControls":{"type":"object","description":"A paginated response containing controls that have failed for an asset.\n","required":["results"],"properties":{"nextCursor":{"$ref":"#/components/schemas/NextCursor"},"total":{"$ref":"#/components/schemas/Total"},"isTotalApproximate":{"$ref":"#/components/schemas/TotalApproximate"},"results":{"description":"Array of failed controls for the current page.","type":"array","items":{"$ref":"#/components/schemas/FailedControl"}}}},"NextCursor":{"description":"Cursor pointing to the next page. If missing, this means that there are no additional pages of resources\navailable after the current one.\n","type":"string"},"Total":{"type":"integer","description":"The total number of resources matching the request."},"TotalApproximate":{"type":"boolean","description":"Indicates if the total is approximate. Failed asset counts stop at 1000: beyond that the API reports `1000`\nwith this flag set to `true`. Failed control counts are always exact, so this is always `false` for them.\n"},"FailedControl":{"type":"object","description":"A control that has failed for an asset.\n","properties":{"id":{"$ref":"#/components/schemas/ControlId"},"name":{"$ref":"#/components/schemas/ControlName"},"description":{"$ref":"#/components/schemas/ControlDescription"},"severity":{"$ref":"#/components/schemas/ControlSeverity"},"controlType":{"$ref":"#/components/schemas/ControlType"},"failedSince":{"$ref":"#/components/schemas/FailureTimestamp"}}},"ControlId":{"type":"string","format":"uuid","description":"The unique identifier of the control."},"ControlName":{"type":"string","description":"The name of the control."},"ControlDescription":{"type":"string","description":"The description of the control."},"ControlSeverity":{"type":"string","description":"The severity of the control.\n\nThe possible values are:\n- Low\n- Medium\n- High\n"},"ControlType":{"type":"string","description":"The type of the control."},"FailureTimestamp":{"type":"string","format":"date-time","description":"The timestamp when the control first failed for this asset."},"StandardErrorResponse":{"description":"A standard error response object.\n\n`titleMessage`, `helpMessage` and `userMessage` all carry the same text: the reason phrase of the status code\nfor `5xx` responses, and the error detail for `4xx` responses. Do not rely on them differing.\n","type":"object","properties":{"statusCode":{"description":"HTTP response code.","type":"integer"},"titleMessage":{"description":"The error message. Same text as `helpMessage` and `userMessage`.\n","type":"string"},"helpMessage":{"description":"The error message. Same text as `titleMessage` and `userMessage`.\n","type":"string"},"userMessage":{"description":"The error message. Same text as `titleMessage` and `helpMessage`.\n","type":"string"},"errorCode":{"description":"An error code identifier. Unless the individual response documents otherwise, this is the name of the\nHTTP status, such as `BAD_REQUEST` or `INTERNAL_SERVER_ERROR`.\n","type":"string"}},"required":["statusCode","errorCode","userMessage"]}}},"paths":{"/controls/failed":{"get":{"tags":["Controls"],"summary":"List failed controls","description":"Returns a list of controls that have failed.\n\nIt is possible to pass an asset ID to filter the controls and only return the controls that have failed for that\nspecific asset.\n\nReturns only the controls on which the authenticated user has view permissions.\n","operationId":"findFailedControlsByAssetId","parameters":[{"$ref":"#/components/parameters/assetId"},{"$ref":"#/components/parameters/cursor"},{"$ref":"#/components/parameters/limit"},{"$ref":"#/components/parameters/controlSortField"},{"$ref":"#/components/parameters/sortOrder"},{"$ref":"#/components/parameters/includeTotal"}],"responses":{"200":{"$ref":"#/components/responses/FailedControlsResponse"},"400":{"$ref":"#/components/responses/BadRequest"},"500":{"$ref":"#/components/responses/InternalServerError"}}}}}}
```

## Retrieve the latest control execution status

> Retrieves the last control execution status for a specific control by its ID.\
> \
> A control that has never completed an execution answers \`Unknown\`, with no \`lastExecutedOn\` and no\
> \`failedAssetCount\`.\
> \
> A \`404\` means the control does not exist, has been deleted, or has not been picked up yet. A control\
> created moments ago is not immediately known here: it becomes available once it has been synchronized,\
> which normally takes a few minutes and no more than 30. For a newly created control, treat a \`404\` as\
> transient and retry.<br>

```json
{"openapi":"3.1.0","info":{"title":"Collibra Control Execution API","version":"1.0.0"},"tags":[{"name":"Controls","description":"Manage and monitor control executions. Use these endpoints to retrieve execution statuses,\ntrigger on-demand control runs, and track failed controls. Supports filtering by asset to\nidentify which controls have failed for specific resources.\n"}],"servers":[{"url":"/rest/controlExecution/v1"}],"security":[{"basicAuth":[]}],"components":{"securitySchemes":{"basicAuth":{"description":"This API requires Basic HTTP authentication.","type":"http","scheme":"basic"}},"parameters":{"controlId":{"name":"controlId","in":"path","required":true,"description":"The unique identifier of the control.\n","schema":{"type":"string","format":"uuid"}}},"responses":{"ExecutionStatusResponse":{"description":"Response containing the execution status details of a specific control, including last known status and\nlast execution timestamp.\n","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ControlExecutionStatus"}}}},"BadRequest":{"description":"The request contains invalid parameters or is missing required data. Details about the validation errors are\nprovided in the response.\n","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StandardErrorResponse"}}}},"NotFoundResponse":{"description":"The request references a resource that is not available.\n","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StandardErrorResponse"}}}},"InternalServerError":{"description":"The server encountered an unexpected condition that prevented it from fulfilling the request. The error details\nprovide information for troubleshooting.\n","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StandardErrorResponse"}}}}},"schemas":{"ControlExecutionStatus":{"description":"Schema for a control status execution.","type":"object","properties":{"controlStatus":{"$ref":"#/components/schemas/ControlExecutionOutcome"},"failedAssetCount":{"$ref":"#/components/schemas/FailedAssetCount"},"lastExecutedOn":{"description":"The timestamp when the control execution was last executed. Absent when the control has never completed an execution.","type":"string","format":"date-time"}},"required":["controlStatus"]},"ControlExecutionOutcome":{"description":"Represents the outcome of a control execution. The currently defined outcomes are `Pass`, `Fail`, and `Unknown`.\n","type":"string"},"FailedAssetCount":{"type":"integer","description":"The number of assets that have failed the control."},"StandardErrorResponse":{"description":"A standard error response object.\n\n`titleMessage`, `helpMessage` and `userMessage` all carry the same text: the reason phrase of the status code\nfor `5xx` responses, and the error detail for `4xx` responses. Do not rely on them differing.\n","type":"object","properties":{"statusCode":{"description":"HTTP response code.","type":"integer"},"titleMessage":{"description":"The error message. Same text as `helpMessage` and `userMessage`.\n","type":"string"},"helpMessage":{"description":"The error message. Same text as `titleMessage` and `userMessage`.\n","type":"string"},"userMessage":{"description":"The error message. Same text as `titleMessage` and `helpMessage`.\n","type":"string"},"errorCode":{"description":"An error code identifier. Unless the individual response documents otherwise, this is the name of the\nHTTP status, such as `BAD_REQUEST` or `INTERNAL_SERVER_ERROR`.\n","type":"string"}},"required":["statusCode","errorCode","userMessage"]}}},"paths":{"/controls/{controlId}/executionStatus":{"get":{"tags":["Controls"],"summary":"Retrieve the latest control execution status","description":"Retrieves the last control execution status for a specific control by its ID.\n\nA control that has never completed an execution answers `Unknown`, with no `lastExecutedOn` and no\n`failedAssetCount`.\n\nA `404` means the control does not exist, has been deleted, or has not been picked up yet. A control\ncreated moments ago is not immediately known here: it becomes available once it has been synchronized,\nwhich normally takes a few minutes and no more than 30. For a newly created control, treat a `404` as\ntransient and retry.\n","operationId":"getControlExecutionStatusByControlId","parameters":[{"$ref":"#/components/parameters/controlId"}],"responses":{"200":{"$ref":"#/components/responses/ExecutionStatusResponse"},"400":{"$ref":"#/components/responses/BadRequest"},"404":{"$ref":"#/components/responses/NotFoundResponse"},"500":{"$ref":"#/components/responses/InternalServerError"}}}}}}
```

## Execute a control

> Triggers the execution of a given control.\
> \
> The control execution is \*\*asynchronous\*\*, meaning that the endpoint returns a pointer to an execution job that\
> &#x20;provides the ability to monitor the status of the execution.\
> \
> This endpoint has side-effects, meaning that the execution of the control can:\
> \- Send notifications\
> \- Update the Managed Control asset with information about the number of failed assets, ...\
> \- Update historical data\
> \
> Note: This execution does not modify the \*\*schedule\*\* of the control, meaning the control will still be executed as\
> defined in the schedule.\
> \
> The caller needs the Activate and Run permission on the control.<br>

```json
{"openapi":"3.1.0","info":{"title":"Collibra Control Execution API","version":"1.0.0"},"tags":[{"name":"Controls","description":"Manage and monitor control executions. Use these endpoints to retrieve execution statuses,\ntrigger on-demand control runs, and track failed controls. Supports filtering by asset to\nidentify which controls have failed for specific resources.\n"}],"servers":[{"url":"/rest/controlExecution/v1"}],"security":[{"basicAuth":[]}],"components":{"securitySchemes":{"basicAuth":{"description":"This API requires Basic HTTP authentication.","type":"http","scheme":"basic"}},"parameters":{"controlId":{"name":"controlId","in":"path","required":true,"description":"The unique identifier of the control.\n","schema":{"type":"string","format":"uuid"}}},"responses":{"JobCreatedResponse":{"description":"A new job was created to execute the control in the background. Poll `GET /jobs/{jobId}` to follow it.\n","headers":{"Location":{"description":"The URL of the newly created job details resource.","schema":{"type":"string","format":"uri-reference"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Job"}}}},"BadRequest":{"description":"The request contains invalid parameters or is missing required data. Details about the validation errors are\nprovided in the response.\n","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StandardErrorResponse"}}}},"ActivateAndRunForbiddenResponse":{"description":"The calling user does not have the Activate and Run permission on the control. Shared by every operation\nthat requires it.\n","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StandardErrorResponse"}}}},"NotFoundResponse":{"description":"The request references a resource that is not available.\n","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StandardErrorResponse"}}}},"ExecuteControlConflictResponse":{"description":"Control executions are blocked because the credit balance of the tenant environment is exhausted. The\n`errorCode` is `creditStateBlocked`.\n","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StandardErrorResponse"}}}},"UnprocessableEntityResponse":{"description":"The request is well-formed but the referenced resource is in a state that prevents the operation.\n","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StandardErrorResponse"}}}},"InternalServerError":{"description":"The server encountered an unexpected condition that prevented it from fulfilling the request. The error details\nprovide information for troubleshooting.\n","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StandardErrorResponse"}}}}},"schemas":{"Job":{"type":"object","description":"A `Job` represents the execution chain for a single on-demand control run, consisting of three background\nsteps: fetching failed assets, sending notifications, and updating the execution status in the knowledge\ngraph.\n","required":["id","type","state","details"],"properties":{"id":{"$ref":"#/components/schemas/JobId"},"type":{"$ref":"#/components/schemas/JobType"},"state":{"$ref":"#/components/schemas/JobState"},"details":{"$ref":"#/components/schemas/JobDetails"},"endDate":{"$ref":"#/components/schemas/JobEndDate"},"failureMessage":{"$ref":"#/components/schemas/JobFailureMessage"}}},"JobId":{"description":"The ID of the job.\n","type":"string","format":"uuid"},"JobType":{"description":"The type of the job.\n\nThe only supported value is `ControlExecutionJob`.\n","type":"string"},"JobState":{"description":"State of the execution chain.\n\nThe current values are:\n - waiting: the first step has been accepted and is waiting to be picked up\n - running: at least one step is running or waiting to run\n - completed: all three steps finished successfully\n - failed: at least one step failed permanently\n","type":"string"},"JobDetails":{"type":"object","description":"Per-step completion flags for the execution chain.","required":["failedAssetsFetched","statusUpdatedInKnowledgeGraph","notificationTriggered"],"properties":{"failedAssetsFetched":{"type":"boolean","description":"True once the first step (fetching failed assets) has completed successfully."},"statusUpdatedInKnowledgeGraph":{"type":"boolean","description":"True once the execution status has been updated in the knowledge graph."},"notificationTriggered":{"type":"boolean","description":"True once the notification step has completed successfully."},"failedStep":{"type":"string","description":"Present only when state is `failed`. Identifies the step that failed permanently.\n\nThe current values are:\n - process-control-query\n - send-control-notifications\n - update-control-execution-status\n"}}},"JobEndDate":{"description":"The completion date and time of the execution job. Indicates when the job transitioned to either `complete` or\n`failed`\n","type":"string","format":"date-time"},"JobFailureMessage":{"description":"A user-facing message indicating that the job has failed. Only present when the job state is `failed`.\n","type":"string"},"StandardErrorResponse":{"description":"A standard error response object.\n\n`titleMessage`, `helpMessage` and `userMessage` all carry the same text: the reason phrase of the status code\nfor `5xx` responses, and the error detail for `4xx` responses. Do not rely on them differing.\n","type":"object","properties":{"statusCode":{"description":"HTTP response code.","type":"integer"},"titleMessage":{"description":"The error message. Same text as `helpMessage` and `userMessage`.\n","type":"string"},"helpMessage":{"description":"The error message. Same text as `titleMessage` and `userMessage`.\n","type":"string"},"userMessage":{"description":"The error message. Same text as `titleMessage` and `helpMessage`.\n","type":"string"},"errorCode":{"description":"An error code identifier. Unless the individual response documents otherwise, this is the name of the\nHTTP status, such as `BAD_REQUEST` or `INTERNAL_SERVER_ERROR`.\n","type":"string"}},"required":["statusCode","errorCode","userMessage"]}}},"paths":{"/controls/{controlId}/execute":{"post":{"tags":["Controls"],"summary":"Execute a control","description":"Triggers the execution of a given control.\n\nThe control execution is **asynchronous**, meaning that the endpoint returns a pointer to an execution job that\n provides the ability to monitor the status of the execution.\n\nThis endpoint has side-effects, meaning that the execution of the control can:\n- Send notifications\n- Update the Managed Control asset with information about the number of failed assets, ...\n- Update historical data\n\nNote: This execution does not modify the **schedule** of the control, meaning the control will still be executed as\ndefined in the schedule.\n\nThe caller needs the Activate and Run permission on the control.\n","operationId":"executeControl","parameters":[{"$ref":"#/components/parameters/controlId"}],"responses":{"202":{"$ref":"#/components/responses/JobCreatedResponse"},"400":{"$ref":"#/components/responses/BadRequest"},"403":{"$ref":"#/components/responses/ActivateAndRunForbiddenResponse"},"404":{"$ref":"#/components/responses/NotFoundResponse"},"409":{"$ref":"#/components/responses/ExecuteControlConflictResponse"},"422":{"$ref":"#/components/responses/UnprocessableEntityResponse"},"500":{"$ref":"#/components/responses/InternalServerError"}}}}}}
```


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://developer.collibra.com/api/references/control-execution/controls.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
