> For the complete documentation index, see [llms.txt](https://v2.dataos.info/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://v2.dataos.info/references/interfaces/apis/data-product-apis/api-reference/quality-and-activity.md).

# Quality & Activity

Technical contract for quality information and operational activity.

Quality APIs answer whether the data meets its declared expectations. Activity APIs explain what was deployed, what ran, and what SQL executed.

## Data Quality

Review quality status and inspect rules. Start with the summary; drill into rules when something looks wrong.

**Data quality concepts:**

* A **rule** defines an expectation for a model or column.
* A **rule run** records the outcome of evaluating that expectation.
* A **quality summary** uses the latest relevant outcome for each rule to show product-level health.

Quality dimensions include `accuracy`, `completeness`, `conformity`, `consistency`, `coverage`, `timeliness`, `validity`, and `uniqueness`.

***

### Quality summary

**API endpoint:** GET /api/v1/dq

**Description:** Retrieve a product-level summary of the latest quality outcomes, grouped by quality dimension. Use it for health cards, scorecards, and point-in-time reporting.

**Query parameters:**

| Parameter  | Default      | Description                                                                 |
| ---------- | ------------ | --------------------------------------------------------------------------- |
| `as_of_ts` | Current time | Use each rule's latest outcome at or before this Unix timestamp in seconds. |

**cURL:**

```bash
curl -s https://$BASE_URL/api/v1/dq \
  -H "Authorization: Bearer $TOKEN"

# Historical snapshot
curl -s "https://$BASE_URL/api/v1/dq?as_of_ts=1789401600" \
  -H "Authorization: Bearer $TOKEN"
```

**Returns:** `200 OK` with total check count, overall pass/fail/warn/error statistics, pass rate, and the same breakdown per dimension. Returns `404 Not Found` when no quality data exists for the environment.

***

### List all quality rules

**API endpoint:** GET /api/v1/dq/rules

**Description:** List known data-quality rules with recent execution history. Start here when the summary reports a problem and you need to identify the failing expectation.

**Query parameters:**

| Parameter       | Default | Description                                                              |
| --------------- | ------- | ------------------------------------------------------------------------ |
| `model`         | None    | Comma-separated model names. Omit for all models.                        |
| `column`        | None    | Filter by column. Omit for all columns.                                  |
| `dimension`     | None    | Filter by ODPS data-quality dimension, such as `validity`.               |
| `runs_per_rule` | `10`    | Recent executions included per rule; range `1`–`100`.                    |
| `limit`         | `100`   | Rules to return; range `1`–`1000`.                                       |
| `offset`        | `0`     | Rules to skip.                                                           |
| `start_ts`      | None    | Rule evaluation start time greater than or equal to this Unix timestamp. |
| `end_ts`        | None    | Rule evaluation start time less than or equal to this Unix timestamp.    |

**cURL:**

```bash
curl -s "https://$BASE_URL/api/v1/dq/rules?model=demo.retail.customer_orders_enriched&dimension=completeness&runs_per_rule=5" \
  -H "Authorization: Bearer $TOKEN"
```

**Returns:** `200 OK` with rule definitions, identities, model/column scope, and recent outcomes. Returns `422 Unprocessable Entity` for invalid filters or ranges.

***

### Look up a rule by name

**API endpoint:** GET /api/v1/dq/rules/by-name/{model}/{dimension}/{name}

**Description:** Retrieve one rule using its readable model, dimension, and check name. Use this form when an alert or dashboard provides the natural key instead of the identity hash.

**Path parameters:**

| Parameter   | Description                                                           |
| ----------- | --------------------------------------------------------------------- |
| `model`     | Fully qualified model name, such as `my_product.my_model`.            |
| `dimension` | Quality dimension, such as `completeness`, `accuracy`, or `validity`. |
| `name`      | Rule name. Names containing `/` are supported.                        |

**Query parameters:**

| Parameter  | Default | Description                                                              |
| ---------- | ------- | ------------------------------------------------------------------------ |
| `limit`    | `20`    | Maximum runs to return.                                                  |
| `offset`   | `0`     | Pagination offset.                                                       |
| `start_ts` | None    | Rule evaluation start time greater than or equal to this Unix timestamp. |
| `end_ts`   | None    | Rule evaluation start time less than or equal to this Unix timestamp.    |

**cURL:**

```bash
curl -s "https://$BASE_URL/api/v1/dq/rules/by-name/demo.retail.customer_orders_enriched/completeness/customer_email_not_null?limit=20" \
  -H "Authorization: Bearer $TOKEN"
```

**Returns:** `200 OK` with the rule definition and run history. Returns `404 Not Found` when the rule does not exist and `422 Unprocessable Entity` for invalid inputs.

***

### Fetch rule by identity hash

**API endpoint:** GET /api/v1/dq/rules/{identity}

**Description:** Retrieve one rule and its execution history using the stable identity returned by `/dq/rules`.

**Path parameters:**

| Parameter  | Description                                      |
| ---------- | ------------------------------------------------ |
| `identity` | Rule identity hash from the rules list response. |

**Query parameters:**

| Parameter  | Default | Description                                                              |
| ---------- | ------- | ------------------------------------------------------------------------ |
| `limit`    | `20`    | Maximum runs to return.                                                  |
| `offset`   | `0`     | Pagination offset.                                                       |
| `start_ts` | None    | Rule evaluation start time greater than or equal to this Unix timestamp. |
| `end_ts`   | None    | Rule evaluation start time less than or equal to this Unix timestamp.    |

**cURL:**

```bash
curl -s https://$BASE_URL/api/v1/dq/rules/dfabde6e \
  -H "Authorization: Bearer $TOKEN"
```

**Returns:** `200 OK` with the rule and recent runs ordered newest first. Returns `404 Not Found` when the identity is unknown and `422 Unprocessable Entity` for invalid query parameters.

***

## Plans

A **plan** is a deployment event that describes changes to the Data Product. A **run** is an execution event that evaluates one or more models, often after a plan or on a schedule.

```
Plan: what changed and was deployed
  └── Runs: what executed
       ├── Model execution details
       ├── Quality/profile results
       └── Warehouse SQL statements
```

***

### List deployment plans

**API endpoint:** GET /api/v1/activity/plans

**Description:** List deployment plans from newest to oldest. Use this for deployment history, change timelines, and success monitoring.

**Query parameters:**

| Parameter  | Default | Description                                                                                     |
| ---------- | ------- | ----------------------------------------------------------------------------------------------- |
| `models`   | None    | Comma-separated models a plan affected. Omit for all models.                                    |
| `limit`    | `20`    | Plans to return; range `1`–`100`.                                                               |
| `offset`   | `0`     | Plans to skip.                                                                                  |
| `start_ts` | None    | Include plans with a start time greater than or equal to this Unix timestamp.                   |
| `end_ts`   | None    | Include plans with a start time less than or equal to this Unix timestamp.                      |
| `success`  | None    | Filter by success. Omit for all plans.                                                          |
| `summary`  | `false` | Return compact rows with change counts only.                                                    |
| `impact`   | `all`   | When `models` is set, filter by direct, indirect, or metadata changes. `all` matches all three. |

**cURL:**

```bash
curl -s "https://$BASE_URL/api/v1/activity/plans?models=demo.retail.customer_orders_enriched&impact=all&limit=20" \
  -H "Authorization: Bearer $TOKEN"
```

**Returns:** `200 OK` with plans and pagination. Returns `404 Not Found` when a model filter is unknown.

***

### Plan detail

**API endpoint:** GET /api/v1/activity/plans/{plan\_id}

**Description:** Full detail on a specific deployment: which models were added, modified, or removed; downstream impact; backfill requirements; and links to adjacent plans.

**Path parameters:**

| Parameter | Description                     |
| --------- | ------------------------------- |
| `plan_id` | Plan ID from the list response. |

**cURL:**

```bash
curl -s https://$BASE_URL/api/v1/activity/plans/c8852cdc210e43e4bf261c9983c8f3d6 \
  -H "Authorization: Bearer $TOKEN"
```

**Returns:** `200 OK` with plan detail. Returns `404 Not Found` when the plan does not exist.

***

### Git diff between plans

**API endpoint:** GET /api/v1/activity/plans/{plan\_id}/git-diff

**Description:** Code diff between this plan and the previous one in the same environment. Diffs are isolated per environment. Large diffs are truncated at 512KB (`truncated: true`).

**Path parameters:**

| Parameter | Description                     |
| --------- | ------------------------------- |
| `plan_id` | Plan ID from the list response. |

**cURL:**

```bash
curl -s https://$BASE_URL/api/v1/activity/plans/c8852cdc210e43e4bf261c9983c8f3d6/git-diff \
  -H "Authorization: Bearer $TOKEN"
```

**Returns:** `200 OK` with `git_diff`, commit metadata, related links, and a `truncated` flag. Diffs larger than 512 KB are truncated. When no previous plan or commit SHA is available, `git_diff` can be null and `message` explains why. Returns `404 Not Found` when the plan does not exist.

***

## Runs

Run history and per-model execution details for each scheduled or triggered execution. A **run** is an execution event.

***

### List execution runs

**API endpoint:** GET /api/v1/activity/runs

**Description:** List execution runs from newest to oldest. Use it to monitor scheduled processing, investigate failures, and relate executions to deployment plans.

**Query parameters:**

| Parameter  | Default | Description                                                                  |
| ---------- | ------- | ---------------------------------------------------------------------------- |
| `models`   | None    | Comma-separated models executed in the run. Omit for all models.             |
| `success`  | None    | Filter by success. Omit for all runs.                                        |
| `start_ts` | None    | Include runs with a start time greater than or equal to this Unix timestamp. |
| `end_ts`   | None    | Include runs with a start time less than or equal to this Unix timestamp.    |
| `plan`     | None    | Plan sequence, using digits only, or plan ID.                                |
| `limit`    | `20`    | Runs to return; range `1`–`100`.                                             |
| `offset`   | `0`     | Runs to skip.                                                                |
| `summary`  | `false` | Return compact rows with model, error, and data-quality counts only.         |

**cURL:**

```bash
curl -s "https://$BASE_URL/api/v1/activity/runs?limit=20&offset=0" \
  -H "Authorization: Bearer $TOKEN"
```

**Returns:** `200 OK` with runs and pagination. Full rows can contain timing, affected models, errors, quality checks, and profiling information. Returns `404 Not Found` when a model filter is unknown.

***

### Run detail

**API endpoint:** GET /api/v1/activity/runs/{run\_id}

**Description:** Full run record: timing, rows affected, per-model quality checks, and profile stats. Quality and profile fields are `null` if those features weren't enabled for the run.

**Path parameters:**

| Parameter | Description                    |
| --------- | ------------------------------ |
| `run_id`  | Run ID from the list response. |

**cURL:**

```bash
curl -s https://$BASE_URL/api/v1/activity/runs/8b299d19d22342d4a9348140353475e4 \
  -H "Authorization: Bearer $TOKEN"
```

**Returns:** `200 OK` with run detail. Quality and profile fields can be absent when those features were not enabled. Returns `404 Not Found` when the run does not exist.

***

### List SQL statements for a run

**API endpoint:** GET /api/v1/activity/runs/{run\_id}/sql

**Description:** Returns the SQL statements executed as part of a run: useful for auditing exactly what ran against the warehouse. Filter by statement kind (e.g. `SELECT`, `MERGE`) or execution outcome.

**Path parameters:**

| Parameter | Description                    |
| --------- | ------------------------------ |
| `run_id`  | Run ID from the list response. |

**Query parameters:**

| Parameter | Default | Description                                            |
| --------- | ------- | ------------------------------------------------------ |
| `kind`    | None    | Filter by statement kind, such as `SELECT` or `MERGE`. |
| `status`  | None    | Filter by execution outcome.                           |
| `limit`   | `100`   | Statements to return; range `1`–`200`.                 |
| `offset`  | `0`     | Statements to skip.                                    |

**cURL:**

```bash
curl -s "https://$BASE_URL/api/v1/activity/runs/run_789/sql?kind=MERGE&limit=100" \
  -H "Authorization: Bearer $TOKEN"
```

**Returns:** `200 OK` with normalized/executed SQL, kind, status, timing, row counts, pagination, and a link to the parent run. Returns `404 Not Found` when the run does not exist.

***

### All models with latest run

**API endpoint:** GET /api/v1/activity/models

**Description:** Every model in the Data Product alongside its most recent run. If a model has never run, the `run` field is `null`. Use this for a model freshness dashboard.

**cURL:**

```bash
curl -s https://$BASE_URL/api/v1/activity/models \
  -H "Authorization: Bearer $TOKEN"
```

**Returns:** `200 OK` with the environment and `models`. Each item contains `model_name` and its latest run; `run` is null when the model has never executed.

***

### Runs for a specific model

**API endpoint:** GET /api/v1/activity/models/{model\_name}/runs

**Description:** Retrieve execution history scoped to one model. Use it for model-level freshness, reliability, and performance views.

**Path parameters:**

| Parameter    | Description                 |
| ------------ | --------------------------- |
| `model_name` | Fully qualified model name. |

**Query parameters:**

| Parameter  | Default | Description                                                                  |
| ---------- | ------- | ---------------------------------------------------------------------------- |
| `limit`    | `20`    | Maximum runs to return.                                                      |
| `offset`   | `0`     | Pagination offset.                                                           |
| `success`  | None    | Filter by success. Omit for all runs.                                        |
| `start_ts` | None    | Include runs with a start time greater than or equal to this Unix timestamp. |
| `end_ts`   | None    | Include runs with a start time less than or equal to this Unix timestamp.    |
| `plan`     | None    | Plan sequence, using digits only, or plan ID.                                |

**cURL:**

```bash
curl -s "https://$BASE_URL/api/v1/activity/models/demo.retail.customer_orders_enriched/runs?limit=10" \
  -H "Authorization: Bearer $TOKEN"
```

**Returns:** `200 OK` with the model name, environment, scoped run entries, total, and pagination. Run wall-clock times describe the full run; model timings describe only that model. Returns `404 Not Found` when the model does not exist and `400 Bad Request` for invalid filter combinations.


---

# 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://v2.dataos.info/references/interfaces/apis/data-product-apis/api-reference/quality-and-activity.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.
