Skip to content

Datastore 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.

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.

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.

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 request and response

Request:

curl -X GET "https://your-instance.qualytics.io/api/datastores/42/score-settings" \
  -H "Authorization: Bearer YOUR_TOKEN"

Response:

{
  "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
}

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.

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.

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.

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:

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:

{
  "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
}
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:

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:

{
  "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
}
Disable Timeliness and Volumetrics

Set the two weights to 0.0 while restating the rest of the current configuration:

Request:

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:

{
  "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
}
Reset all weights to default

Set all weights to null to restore system defaults:

Request:

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:

{
  "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.

Get Historical Quality Scores

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

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

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

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

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

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.

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 request and response

Request:

curl -X GET "https://your-instance.qualytics.io/api/datastores/42/quality-scores" \
  -H "Authorization: Bearer YOUR_TOKEN"

Response:

[
  {
    "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.
Error response examples

403 Forbidden:

{ "detail": "You do not have the permission required [Editor] to perform this action" }

422 Unprocessable Entity:

{ "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

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.