> 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/jobs.md).

# Jobs

Monitor background job execution status. Use these endpoints to track the progress of asynchronous operations such as on-demand control executions. Poll job status to determine when operations complete and retrieve execution results.

## Retrieve the job status

> Returns the description of a given job.\
> \
> You can use this endpoint for polling to track the progress of a given job.<br>

```json
{"openapi":"3.1.0","info":{"title":"Collibra Control Execution API","version":"1.0.0"},"tags":[{"name":"Jobs","description":"Monitor background job execution status. Use these endpoints to track the progress of\nasynchronous operations such as on-demand control executions. Poll job status to determine\nwhen operations complete and retrieve execution results.\n"}],"servers":[{"url":"/rest/controlExecution/v1"}],"security":[{"basicAuth":[]}],"components":{"securitySchemes":{"basicAuth":{"description":"This API requires Basic HTTP authentication.","type":"http","scheme":"basic"}},"parameters":{"jobId":{"name":"jobId","in":"path","required":true,"description":"The ID of an execution job.\n","schema":{"type":"string","format":"uuid"}}},"responses":{"JobResponse":{"description":"Response containing information about a given execution job.\n","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"}}}},"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":{"/jobs/{jobId}":{"get":{"tags":["Jobs"],"summary":"Retrieve the job status","description":"Returns the description of a given job.\n\nYou can use this endpoint for polling to track the progress of a given job.\n","operationId":"getJob","parameters":[{"$ref":"#/components/parameters/jobId"}],"responses":{"200":{"$ref":"#/components/responses/JobResponse"},"400":{"$ref":"#/components/responses/BadRequest"},"403":{"$ref":"#/components/responses/ActivateAndRunForbiddenResponse"},"404":{"$ref":"#/components/responses/NotFoundResponse"},"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/jobs.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.
