# Datastore Quality Score API

Source: https://userguide.qualytics.io/source-datastore/data-quality-score/api/

The Data Quality Score API allows you to retrieve and update quality score settings for a datastore or one of its containers, and to access the score history of datastores, containers, and fields.

> **Tip**
>
> For complete API documentation, including request/response schemas, visit the [API docs](https://userguide.qualytics.io/api/docs).

All endpoints use the base URL of your Qualytics deployment (e.g., `https://your-instance.qualytics.io/api`).

---

## Get Quality Score Settings

Retrieve the current quality score settings (decay period and dimension weights) for a datastore or a container.

**Tab: Datastore**

**Endpoint**: `GET /api/datastores/{datastore_id}/score-settings`

**Permission**: Member user role + Reporter team permission on the datastore

Returns the datastore's settings, or the defaults when the datastore has never been configured.

**Tab: Container**

**Endpoint**: `GET /api/containers/{container_id}/score-settings`

**Permission**: Member user role + Reporter team permission on the datastore

Returns the container's own settings when it has them. Otherwise it returns the settings the container inherits from its datastore, or the defaults when neither is configured. The response looks the same in each case, so it does not show whether the settings are the container's own or inherited.

> **Example: Example request and response**
>
> **Request**:
>
> ```bash
> curl -X GET "https://your-instance.qualytics.io/api/datastores/42/score-settings" \
>   -H "Authorization: Bearer YOUR_TOKEN"
> ```
>
> **Response**:
>
> ```json
> {
>   "decay_period_days": 180,
>   "completeness_weight": 1.0,
>   "coverage_weight": 1.0,
>   "conformity_weight": 1.0,
>   "consistency_weight": 1.0,
>   "precision_weight": 1.0,
>   "timeliness_weight": 1.0,
>   "volumetrics_weight": 1.0,
>   "accuracy_weight": 1.0
> }
> ```

> **Note: null vs 1.0**
>
> When a datastore has never had its settings explicitly configured, the GET endpoint returns `null` for all weight fields. A `null` weight means the system default (`1.0`) is used. Once you update any setting, subsequent GET calls return the explicitly set values.

---

## Update Quality Score Settings

Update the decay period and dimension weights for a datastore or a container. This endpoint **replaces the full settings object**: any field you omit is reset to its default (`decay_period_days` back to 180, weights back to the system default). Always send the complete configuration you want to keep.

**Tab: Datastore**

**Endpoint**: `PUT /api/datastores/{datastore_id}/score-settings`

**Permission**: Member user role + Editor team permission on the datastore

The settings apply to the datastore score and to every container that has no settings of its own.

**Tab: Container**

**Endpoint**: `PUT /api/containers/{container_id}/score-settings`

**Permission**: Member user role + Editor team permission on the datastore. On a computed table, computed file, or computed join, its owner with the Author team permission can also update them.

The settings override the datastore's settings for this container only. Fields use the settings of their container, so there is no field-level endpoint.

**Request Body**:

| Field | Type | Default | Range | Description |
| --- | --- | --- | --- | --- |
| `decay_period_days` | `integer` | `180` | 7-180 | The time frame in days over which historical data is evaluated for scoring. |
| `completeness_weight` | `float` | `null` (1.0) | 0.0-2.0 | Weight for the Completeness dimension. |
| `coverage_weight` | `float` | `null` (1.0) | 0.0-2.0 | Weight for the Coverage dimension. |
| `conformity_weight` | `float` | `null` (1.0) | 0.0-2.0 | Weight for the Conformity dimension. |
| `consistency_weight` | `float` | `null` (1.0) | 0.0-2.0 | Weight for the Consistency dimension. |
| `precision_weight` | `float` | `null` (1.0) | 0.0-2.0 | Weight for the Precision dimension. |
| `timeliness_weight` | `float` | `null` (1.0) | 0.0-2.0 | Weight for the Timeliness dimension. |
| `volumetrics_weight` | `float` | `null` (1.0) | 0.0-2.0 | Weight for the Volumetrics dimension. |
| `accuracy_weight` | `float` | `null` (1.0) | 0.0-2.0 | Weight for the Accuracy dimension. |

> **Note**
>
> A weight of `null` uses the system default (1.0). A weight of `0.0` effectively disables the dimension, so it cannot pull the score down.

The examples below use a datastore. For a container, send the same body to `PUT /api/containers/{container_id}/score-settings`.

> **Example: Change decay period**
>
> Shorten the decay period to 30 days for a more recent quality view. The weights are sent as `null` to keep the system default of 1.0:
>
> **Request**:
>
> ```bash
> curl -X PUT "https://your-instance.qualytics.io/api/datastores/42/score-settings" \
>   -H "Authorization: Bearer YOUR_TOKEN" \
>   -H "Content-Type: application/json" \
>   -d '{
>     "decay_period_days": 30,
>     "completeness_weight": null,
>     "coverage_weight": null,
>     "conformity_weight": null,
>     "consistency_weight": null,
>     "precision_weight": null,
>     "timeliness_weight": null,
>     "volumetrics_weight": null,
>     "accuracy_weight": null
>   }'
> ```
>
> **Response**:
>
> ```json
> {
>   "decay_period_days": 30,
>   "completeness_weight": null,
>   "coverage_weight": null,
>   "conformity_weight": null,
>   "consistency_weight": null,
>   "precision_weight": null,
>   "timeliness_weight": null,
>   "volumetrics_weight": null,
>   "accuracy_weight": null
> }
> ```

> **Example: Prioritize Accuracy and Completeness**
>
> Increase Accuracy and Completeness while reducing Volumetrics. Note that the full settings object is sent, including the fields that keep their current values; omitting them would reset them to defaults:
>
> **Request**:
>
> ```bash
> curl -X PUT "https://your-instance.qualytics.io/api/datastores/42/score-settings" \
>   -H "Authorization: Bearer YOUR_TOKEN" \
>   -H "Content-Type: application/json" \
>   -d '{
>     "decay_period_days": 30,
>     "completeness_weight": 1.5,
>     "coverage_weight": 1.0,
>     "conformity_weight": 1.0,
>     "consistency_weight": 1.0,
>     "precision_weight": 1.0,
>     "timeliness_weight": 1.0,
>     "volumetrics_weight": 0.3,
>     "accuracy_weight": 2.0
>   }'
> ```
>
> **Response**:
>
> ```json
> {
>   "decay_period_days": 30,
>   "completeness_weight": 1.5,
>   "coverage_weight": 1.0,
>   "conformity_weight": 1.0,
>   "consistency_weight": 1.0,
>   "precision_weight": 1.0,
>   "timeliness_weight": 1.0,
>   "volumetrics_weight": 0.3,
>   "accuracy_weight": 2.0
> }
> ```

> **Example: Disable Timeliness and Volumetrics**
>
> Set the two weights to `0.0` while restating the rest of the current configuration:
>
> **Request**:
>
> ```bash
> curl -X PUT "https://your-instance.qualytics.io/api/datastores/42/score-settings" \
>   -H "Authorization: Bearer YOUR_TOKEN" \
>   -H "Content-Type: application/json" \
>   -d '{
>     "decay_period_days": 30,
>     "completeness_weight": 1.5,
>     "coverage_weight": 1.0,
>     "conformity_weight": 1.0,
>     "consistency_weight": 1.0,
>     "precision_weight": 1.0,
>     "timeliness_weight": 0.0,
>     "volumetrics_weight": 0.0,
>     "accuracy_weight": 2.0
>   }'
> ```
>
> **Response**:
>
> ```json
> {
>   "decay_period_days": 30,
>   "completeness_weight": 1.5,
>   "coverage_weight": 1.0,
>   "conformity_weight": 1.0,
>   "consistency_weight": 1.0,
>   "precision_weight": 1.0,
>   "timeliness_weight": 0.0,
>   "volumetrics_weight": 0.0,
>   "accuracy_weight": 2.0
> }
> ```

> **Example: Reset all weights to default**
>
> Set all weights to `null` to restore system defaults:
>
> **Request**:
>
> ```bash
> curl -X PUT "https://your-instance.qualytics.io/api/datastores/42/score-settings" \
>   -H "Authorization: Bearer YOUR_TOKEN" \
>   -H "Content-Type: application/json" \
>   -d '{
>     "decay_period_days": 180,
>     "completeness_weight": null,
>     "coverage_weight": null,
>     "conformity_weight": null,
>     "consistency_weight": null,
>     "precision_weight": null,
>     "timeliness_weight": null,
>     "volumetrics_weight": null,
>     "accuracy_weight": null
>   }'
> ```
>
> **Response**:
>
> ```json
> {
>   "decay_period_days": 180,
>   "completeness_weight": null,
>   "coverage_weight": null,
>   "conformity_weight": null,
>   "consistency_weight": null,
>   "precision_weight": null,
>   "timeliness_weight": null,
>   "volumetrics_weight": null,
>   "accuracy_weight": null
> }
> ```

For the UI equivalent, see [Configure Quality Score Settings](https://userguide.qualytics.io/source-datastore/data-quality-score/how-tos/quality-score-settings/).

---

## Get Historical Quality Scores

Retrieve the last 10 quality scores of a datastore, a container, or a field, most recent first.

**Tab: Datastore**

**Endpoint**: `GET /api/datastores/{datastore_id}/quality-scores`

**Permission**: Member user role + Reporter team permission on the datastore

**Tab: Container**

**Endpoint**: `GET /api/containers/{container_id}/quality-scores`

**Permission**: Member user role + Reporter team permission on the datastore

**Tab: Field**

**Endpoint**: `GET /api/field-profiles/{field_id}/quality-scores`

**Permission**: Member user role + Reporter team permission on the datastore

The `field_id` is the ID that appears in the field's page URL in Qualytics.

**Query Parameters**:

| Parameter | Type | Default | Description |
| --- | --- | --- | --- |
| `granularity` | `string` | `day` | `day` returns one score per calendar day: the weighted average of the containers for a datastore, and the last measurement of the day for a container or field. `measure` returns every individual measurement with its exact `timestamp`, so a score that dipped and recovered within the same day is still visible. |

> **Note: Limitation**
>
> These endpoints return a **fixed maximum of 10 scores**. There is no pagination or date range parameter, so the response always contains the 10 most recent days or measurements.

> **Example: Example request and response**
>
> **Request**:
>
> ```bash
> curl -X GET "https://your-instance.qualytics.io/api/datastores/42/quality-scores" \
>   -H "Authorization: Bearer YOUR_TOKEN"
> ```
>
> **Response**:
>
> ```json
> [
>   {
>     "date": "2026-03-30",
>     "total": 87.4,
>     "completeness": 95.2,
>     "coverage": 72.0,
>     "conformity": 91.3,
>     "consistency": 88.7,
>     "precision": 94.1,
>     "timeliness": 82.5,
>     "volumetrics": 90.0,
>     "accuracy": 85.6
>   },
>   {
>     "date": "2026-03-29",
>     "total": 85.1,
>     "completeness": 94.8,
>     "coverage": 70.0,
>     "conformity": 89.2,
>     "consistency": 87.3,
>     "precision": 93.5,
>     "timeliness": 80.0,
>     "volumetrics": 88.5,
>     "accuracy": 84.2
>   }
> ]
> ```

### Response Schema

| Field | Type | Description |
| --- | --- | --- |
| `date` | `date` | The date of the quality score snapshot. |
| `timestamp` | `datetime` | The exact time of the measurement. Returned only with `granularity=measure`, and `null` otherwise. |
| `total` | `float` | The overall quality score (0-100). |
| `completeness` | `float` | Completeness dimension score (0-100). |
| `coverage` | `float` | Coverage dimension score (0-100). |
| `conformity` | `float` | Conformity dimension score (0-100). |
| `consistency` | `float` | Consistency dimension score (0-100). |
| `precision` | `float` | Precision dimension score (0-100). |
| `timeliness` | `float` | Timeliness dimension score (0-100). |
| `volumetrics` | `float` | Volumetrics dimension score (0-100). |
| `accuracy` | `float` | Accuracy dimension score (0-100). |

---

## Error Responses

| Status Code | Description |
| --- | --- |
| `401 Unauthorized` | Missing or invalid API token. |
| `403 Forbidden` | User does not have the required role or team permission. |
| `404 Not Found` | The datastore, container, or field with the specified ID does not exist. When it exists but has never been configured, the settings GET returns the defaults (decay of 180 days, `null` weights) instead of an error. |
| `422 Unprocessable Entity` | Invalid request body or parameter, such as `decay_period_days` outside 7-180, a weight outside 0-2.0, or an unknown `granularity`. |

> **Example: Error response examples**
>
> **403 Forbidden**:
>
> ```json
> { "detail": "You do not have the permission required [Editor] to perform this action" }
> ```
>
> **422 Unprocessable Entity**:
>
> ```json
> { "detail": [{ "type": "greater_than_equal", "loc": ["body", "decay_period_days"], "msg": "Input should be greater than or equal to 7" }] }
> ```

---

## Permission Summary

| Operation | Minimum Permission |
| --- | --- |
| Get datastore or container settings | Member user role + Reporter team permission |
| Update datastore or container settings | Member user role + Editor team permission (or the owner of a computed container, with the Author team permission) |
| Get datastore, container, or field score history | Member user role + Reporter team permission |

> **Note: When Settings Take Effect**
>
> Updating quality score settings does not recalculate existing scores. The new configuration is used the next time a score is recorded (for example, when a Scan or Profile completes or an anomaly changes status). There is no manual recalculation endpoint.

*Last updated: November 9, 2026.*