> For the complete documentation index, see [llms.txt](https://docs.rootcause.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.rootcause.ai/api-and-integrations/rest-api-reference/jobs.md).

# Jobs

## List pipeline jobs

> Lists pipeline runs for the workspace. Proxies to data-service GET /api/internal/pipeline-runs/workspace/{wsId}. Results are paginated in-app (limit, cursor). Jobs include connector imports, digital-twin train/run-pipeline/discover, report generate, etc. Use the returned job ids to poll GET /jobs/{id} or cancel via POST /jobs/{id}/cancel.

```json
{"openapi":"3.1.0","info":{"title":"RootCause Public API","version":"1.0.0"},"tags":[{"name":"Jobs"}],"servers":[{"url":"https://sandbox.rootcause.ai","description":"Sandbox"},{"url":"https://platform.rootcause.ai","description":"Production"},{"url":"http://localhost:3000","description":"Local development"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"API Key","description":"An API key (pk_...) created on the Organisation API page, or an OAuth access token. Every operation requires one."}},"schemas":{"PaginatedEnvelope":{"type":"object","properties":{"data":{"type":"array","items":{},"description":"Payload not declared in this repo"},"pagination":{"type":"object","properties":{"cursor":{"type":"string","description":"Pass back as ?cursor= to fetch the next page"},"hasMore":{"type":"boolean","description":"Whether a further page exists"},"total":{"type":"number","description":"Total matching rows, when the query can count them"}},"required":["hasMore"]}},"required":["data","pagination"]}},"responses":{"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"type":"object","properties":{"type":{"type":"string"},"title":{"type":"string"},"status":{"type":"integer"},"detail":{"type":"string"},"instance":{"type":"string"}},"required":["type","title","status","detail"]}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"type":"object","properties":{"type":{"type":"string"},"title":{"type":"string"},"status":{"type":"integer"},"detail":{"type":"string"},"instance":{"type":"string"}},"required":["type","title","status","detail"]}}}},"429":{"description":"Too Many Requests; the response carries Retry-After","content":{"application/json":{"schema":{"type":"object","properties":{"type":{"type":"string"},"title":{"type":"string"},"status":{"type":"integer"},"detail":{"type":"string"},"instance":{"type":"string"}},"required":["type","title","status","detail"]}}}},"500":{"description":"Internal Server Error","content":{"application/json":{"schema":{"type":"object","properties":{"type":{"type":"string"},"title":{"type":"string"},"status":{"type":"integer"},"detail":{"type":"string"},"instance":{"type":"string"}},"required":["type","title","status","detail"]}}}}}},"paths":{"/api/v1/workspaces/{wsId}/jobs":{"get":{"operationId":"get-api-v1-workspaces-{wsId}-jobs","summary":"List pipeline jobs","description":"Lists pipeline runs for the workspace. Proxies to data-service GET /api/internal/pipeline-runs/workspace/{wsId}. Results are paginated in-app (limit, cursor). Jobs include connector imports, digital-twin train/run-pipeline/discover, report generate, etc. Use the returned job ids to poll GET /jobs/{id} or cancel via POST /jobs/{id}/cancel.","tags":["Jobs"],"parameters":[{"in":"query","name":"limit","required":false,"schema":{"description":"Page size (1-1000, default 50).","type":"number","minimum":1,"maximum":1000},"description":"Page size (1-1000, default 50)."},{"in":"query","name":"cursor","required":false,"schema":{"type":"string","description":"Opaque cursor from a previous response's `pagination.cursor`."},"description":"Opaque cursor from a previous response's `pagination.cursor`."},{"name":"wsId","in":"path","required":true,"schema":{"type":"string"},"description":"Path parameter: wsId"}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PaginatedEnvelope"}}}},"401":{"$ref":"#/components/responses/401"},"403":{"$ref":"#/components/responses/403"},"429":{"$ref":"#/components/responses/429"},"500":{"$ref":"#/components/responses/500"}}}}}}
```

## Get job status

> Returns the pipeline run by id. Proxies to data-service GET /api/internal/pipeline-runs/by-id/{id}. Use to poll status after a 202 from import, train, run-pipeline, discover, or report generate. Response shape is defined by the data-service (e.g. status, progress, result). 404 if the run does not exist in this workspace. A job whose worker died is reported as failed rather than left active.

```json
{"openapi":"3.1.0","info":{"title":"RootCause Public API","version":"1.0.0"},"tags":[{"name":"Jobs"}],"servers":[{"url":"https://sandbox.rootcause.ai","description":"Sandbox"},{"url":"https://platform.rootcause.ai","description":"Production"},{"url":"http://localhost:3000","description":"Local development"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"API Key","description":"An API key (pk_...) created on the Organisation API page, or an OAuth access token. Every operation requires one."}},"schemas":{"UnspecifiedEnvelope":{"type":"object","properties":{"data":{"anyOf":[{"type":"string"},{"type":"number"},{"type":"boolean"},{"type":"null"},{"type":"object","additionalProperties":{}},{"type":"array","items":{}}],"description":"Payload not declared in this repo"}},"required":["data"]}},"responses":{"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"type":"object","properties":{"type":{"type":"string"},"title":{"type":"string"},"status":{"type":"integer"},"detail":{"type":"string"},"instance":{"type":"string"}},"required":["type","title","status","detail"]}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"type":"object","properties":{"type":{"type":"string"},"title":{"type":"string"},"status":{"type":"integer"},"detail":{"type":"string"},"instance":{"type":"string"}},"required":["type","title","status","detail"]}}}},"404":{"description":"Not Found","content":{"application/json":{"schema":{"type":"object","properties":{"type":{"type":"string"},"title":{"type":"string"},"status":{"type":"integer"},"detail":{"type":"string"},"instance":{"type":"string"}},"required":["type","title","status","detail"]}}}},"429":{"description":"Too Many Requests; the response carries Retry-After","content":{"application/json":{"schema":{"type":"object","properties":{"type":{"type":"string"},"title":{"type":"string"},"status":{"type":"integer"},"detail":{"type":"string"},"instance":{"type":"string"}},"required":["type","title","status","detail"]}}}},"500":{"description":"Internal Server Error","content":{"application/json":{"schema":{"type":"object","properties":{"type":{"type":"string"},"title":{"type":"string"},"status":{"type":"integer"},"detail":{"type":"string"},"instance":{"type":"string"}},"required":["type","title","status","detail"]}}}}}},"paths":{"/api/v1/workspaces/{wsId}/jobs/{id}":{"get":{"operationId":"get-api-v1-workspaces-{wsId}-jobs-{id}","summary":"Get job status","description":"Returns the pipeline run by id. Proxies to data-service GET /api/internal/pipeline-runs/by-id/{id}. Use to poll status after a 202 from import, train, run-pipeline, discover, or report generate. Response shape is defined by the data-service (e.g. status, progress, result). 404 if the run does not exist in this workspace. A job whose worker died is reported as failed rather than left active.","tags":["Jobs"],"parameters":[{"name":"wsId","in":"path","required":true,"schema":{"type":"string"},"description":"Path parameter: wsId"},{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"Path parameter: id"}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/UnspecifiedEnvelope"}}}},"401":{"$ref":"#/components/responses/401"},"403":{"$ref":"#/components/responses/403"},"404":{"$ref":"#/components/responses/404"},"429":{"$ref":"#/components/responses/429"},"500":{"$ref":"#/components/responses/500"}}}}}}
```

## Cancel a running job

> Cancels a running pipeline job. Requires the jobs:cancel scope — jobs:read alone no longer authorizes a cancel. Proxies to data-service POST /api/pipeline-runs/{id}/cancel. Returns jobId, status cancelled, and sourceQueryCancelled — true when the cancel reached the source database and stopped the query itself, false when the connector has no source-side cancellation and the query ends when the connection drops, and null when the job is owned by a workflow that stops the source asynchronously, so the outcome is not known at the time of the reply. A job the data-service refuses to cancel answers with that refusal and its status, and with a readable reason rather than a generic one: 409 when the job already finished, 400 when it is not a cancellable kind of job (connector imports, syncs, replaces and extends are; document extractions are not), 400 when it has no running work associated with it. 404 if the run does not exist in this workspace.

```json
{"openapi":"3.1.0","info":{"title":"RootCause Public API","version":"1.0.0"},"tags":[{"name":"Jobs"}],"servers":[{"url":"https://sandbox.rootcause.ai","description":"Sandbox"},{"url":"https://platform.rootcause.ai","description":"Production"},{"url":"http://localhost:3000","description":"Local development"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"API Key","description":"An API key (pk_...) created on the Organisation API page, or an OAuth access token. Every operation requires one."}},"schemas":{"UnspecifiedEnvelope":{"type":"object","properties":{"data":{"anyOf":[{"type":"string"},{"type":"number"},{"type":"boolean"},{"type":"null"},{"type":"object","additionalProperties":{}},{"type":"array","items":{}}],"description":"Payload not declared in this repo"}},"required":["data"]}},"responses":{"400":{"description":"Bad Request","content":{"application/json":{"schema":{"type":"object","properties":{"type":{"type":"string"},"title":{"type":"string"},"status":{"type":"integer"},"detail":{"type":"string"},"instance":{"type":"string"}},"required":["type","title","status","detail"]}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"type":"object","properties":{"type":{"type":"string"},"title":{"type":"string"},"status":{"type":"integer"},"detail":{"type":"string"},"instance":{"type":"string"}},"required":["type","title","status","detail"]}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"type":"object","properties":{"type":{"type":"string"},"title":{"type":"string"},"status":{"type":"integer"},"detail":{"type":"string"},"instance":{"type":"string"}},"required":["type","title","status","detail"]}}}},"404":{"description":"Not Found","content":{"application/json":{"schema":{"type":"object","properties":{"type":{"type":"string"},"title":{"type":"string"},"status":{"type":"integer"},"detail":{"type":"string"},"instance":{"type":"string"}},"required":["type","title","status","detail"]}}}},"409":{"description":"Conflict","content":{"application/json":{"schema":{"type":"object","properties":{"type":{"type":"string"},"title":{"type":"string"},"status":{"type":"integer"},"detail":{"type":"string"},"instance":{"type":"string"}},"required":["type","title","status","detail"]}}}},"429":{"description":"Too Many Requests; the response carries Retry-After","content":{"application/json":{"schema":{"type":"object","properties":{"type":{"type":"string"},"title":{"type":"string"},"status":{"type":"integer"},"detail":{"type":"string"},"instance":{"type":"string"}},"required":["type","title","status","detail"]}}}},"500":{"description":"Internal Server Error","content":{"application/json":{"schema":{"type":"object","properties":{"type":{"type":"string"},"title":{"type":"string"},"status":{"type":"integer"},"detail":{"type":"string"},"instance":{"type":"string"}},"required":["type","title","status","detail"]}}}}}},"paths":{"/api/v1/workspaces/{wsId}/jobs/{id}/cancel":{"post":{"operationId":"post-api-v1-workspaces-{wsId}-jobs-{id}-cancel","summary":"Cancel a running job","description":"Cancels a running pipeline job. Requires the jobs:cancel scope — jobs:read alone no longer authorizes a cancel. Proxies to data-service POST /api/pipeline-runs/{id}/cancel. Returns jobId, status cancelled, and sourceQueryCancelled — true when the cancel reached the source database and stopped the query itself, false when the connector has no source-side cancellation and the query ends when the connection drops, and null when the job is owned by a workflow that stops the source asynchronously, so the outcome is not known at the time of the reply. A job the data-service refuses to cancel answers with that refusal and its status, and with a readable reason rather than a generic one: 409 when the job already finished, 400 when it is not a cancellable kind of job (connector imports, syncs, replaces and extends are; document extractions are not), 400 when it has no running work associated with it. 404 if the run does not exist in this workspace.","tags":["Jobs"],"parameters":[{"name":"wsId","in":"path","required":true,"schema":{"type":"string"},"description":"Path parameter: wsId"},{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"Path parameter: id"}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/UnspecifiedEnvelope"}}}},"400":{"$ref":"#/components/responses/400"},"401":{"$ref":"#/components/responses/401"},"403":{"$ref":"#/components/responses/403"},"404":{"$ref":"#/components/responses/404"},"409":{"$ref":"#/components/responses/409"},"429":{"$ref":"#/components/responses/429"},"500":{"$ref":"#/components/responses/500"}}}}}}
```