# Scan Runs

These endpoints allow you to trigger on-demand scans and track scan execution progress.

***

## Endpoints

| Method | Path                            | Permission     | Description                                         |
| ------ | ------------------------------- | -------------- | --------------------------------------------------- |
| `POST` | `/api/scan/run`                 | `scan:trigger` | Trigger an on-demand scan for the current workspace |
| `GET`  | `/api/scan/status/:executionId` | `scan:trigger` | Check the progress of a triggered scan              |

> **Note:** The Admin and Member workspace roles have `scan:trigger` permission. Viewers cannot trigger scans.

***

## POST /api/scan/run

Trigger an on-demand DQ scan for all enabled monitors in the current workspace. The scan starts immediately without waiting for the next scheduled run.

**Permission:** Admin or Member role

**Request:** Empty body.

**Response (202):**

```json
{
  "data": {
    "executionId": "aca-execution-id",
    "status": "running"
  }
}
```

Use the `executionId` to poll for completion.

***

## GET /api/scan/status/:executionId

Check the status of a scan triggered via `POST /api/scan/run`.

**Response (200):**

```json
{
  "data": {
    "executionId": "aca-execution-id",
    "status": "running",
    "startedAt": "2026-03-24T09:00:00Z",
    "finishedAt": null
  }
}
```

**Status values:** `running` | `finished` | `failed`

***

## GET /api/assets/scan-status

Returns the current and last completed scan run for every asset. Useful for polling the Monitor Dashboard to show live progress.

**Permission:** `assets:read`

**Response (200):**

```json
{
  "data": [
    {
      "assetId": "uuid",
      "assetName": "orders",
      "status": "running",
      "lastCompletedAt": "2026-03-24T08:30:00Z",
      "currentRun": {
        "jobId": "batch-uuid",
        "status": "running",
        "startedAt": "2026-03-24T09:00:00Z",
        "finishedAt": null,
        "progress": {
          "total": 4,
          "completed": 1,
          "running": 2,
          "failed": 0,
          "pending": 1
        },
        "monitors": [
          {
            "monitorId": "uuid",
            "monitorName": "Record Count",
            "stage": "completed",
            "durationMs": 1200,
            "error": null
          }
        ]
      },
      "lastRun": {
        "jobId": "batch-uuid-prev",
        "status": "completed",
        "startedAt": "2026-03-24T08:00:00Z",
        "finishedAt": "2026-03-24T08:30:00Z",
        "progress": { "total": 4, "completed": 4, "running": 0, "failed": 0, "pending": 0 }
      }
    }
  ]
}
```

**Asset status values:** `idle` | `running` | `completed` | `failed` | `partial_failure`


---

# Agent Instructions: Querying This Documentation

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

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://fabric-docs.telm.ai/api-reference/scan-runs.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
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.