Datastore Quality Score API

The Data Quality Score API allows you to retrieve and update quality score settings for a datastore, as well as access historical quality score data.

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.

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

Permission: Member user role (no team permission required)

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

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; it will not negatively impact the score.

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 Quality Score Settings.

Get Historical Quality Scores

Retrieve the last 10 quality score snapshots for a datastore, recorded as daily metrics.

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

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

Limitation

This endpoint returns a fixed maximum of 10 snapshots. There is no pagination or date range parameter; the response always contains the most recent 10 daily scores available.

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.
`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`	Datastore with the specified ID does not exist. When a datastore exists but has never been configured, GET returns the defaults (decay of 180 days, `null` weights) instead of an error.
`422 Unprocessable Entity`	Invalid request body (e.g., decay_period_days outside 7-180 range, weight outside 0-2.0).

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 quality score settings	Member user role
Update quality score settings	Member user role + Editor team permission
Get historical quality scores	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.