Skip to content

Checks API

This page documents the endpoints that apply to every check regardless of its rule type: the change log of a check, its definition at a point in time, and the daily assertion history behind its Insights section. Create, read, update, and delete payloads are rule-specific and live on each rule type's API page (see Getting Started with Checks).

All endpoints use the base URL of your Qualytics deployment (for example, https://your-instance.qualytics.io/api) and require a Bearer token. Every timestamp is returned in UTC as ISO 8601 with a trailing Z; see Timestamps.

Tip

For complete API documentation, including request/response schemas, visit the API docs.

Permissions

All three endpoints require the Member role and the Reporter team permission on the check's datastore.

History

Returns the paginated change log of a check: one entry per saved version, with the fields that changed, their before and after values, the user who made the change, and when. Use it to reconstruct every state a check has been in.

Endpoint: GET /api/quality-checks/{id}/history

Query parameters:

Parameter Type Description
page int (default 1) Page number to return, starting at 1.
size int (default 50, max 100) Number of entries per page.
include_deleted bool (default false) When true, also returns the history of a deleted check.
Example request 
curl -X GET "https://your-instance.qualytics.io/api/quality-checks/778/history?page=1&size=50" \
  -H "Authorization: Bearer YOUR_TOKEN"
Example response (abbreviated) 
{
  "items": [
    {
      "changeset": {
        "filter": ["order_date >= '2026-01-01'", "order_date >= '2026-06-01'"],
        "description": ["Orders must reference a customer", "Orders must reference an active customer"]
      },
      "transaction": {
        "id": 9876,
        "issued_at": "2026-06-02T13:40:11Z",
        "user": { "id": 42, "name": "Alice Lee" }
      },
      "operation": "update"
    },
    {
      "changeset": {
        "fields": [null, ["customer_id"]],
        "status": [null, "Active"]
      },
      "transaction": {
        "id": 8120,
        "issued_at": "2026-01-15T09:02:47Z",
        "user": { "id": 42, "name": "Alice Lee" }
      },
      "operation": "insert"
    }
  ],
  "total": 2,
  "page": 1,
  "size": 50,
  "pages": 1
}

Each field inside items[].changeset is a [before, after] pair. The transaction object carries the change id, the issued_at timestamp, and the user who saved it. The operation field reports whether the entry is an insert, update, or delete. To load successive windows, increment page until it reaches pages.

Version at a Point in Time

Returns the full check definition as it stood at a given instant. Pass the start_time of a scan (from GET /api/operations/{id} or GET /api/container-scans/{id}) to retrieve the exact definition that scan evaluated, even if the check has been edited since.

Endpoint: GET /api/quality-checks/{id}/version?version_at={UTC timestamp}

Query parameters:

Parameter Type Description
version_at string (ISO 8601) The instant to resolve, interpreted as UTC (for example 2026-06-01T02:00:00Z). When omitted, the current definition is returned. A value earlier than the check's creation returns the first saved version.
Example request 
curl -X GET "https://your-instance.qualytics.io/api/quality-checks/778/version?version_at=2026-05-15T02:00:00Z" \
  -H "Authorization: Bearer YOUR_TOKEN"
Example response (abbreviated) 
{
  "id": 778,
  "rule_type": "notNull",
  "description": "Orders must reference a customer",
  "filter": "order_date >= '2026-01-01'",
  "coverage": 1.0,
  "status": "Active",
  "fields": [{ "id": 3101, "name": "customer_id" }],
  "container": { "id": 235, "name": "orders" },
  "datastore": { "id": 101, "name": "Sales" },
  "created": "2026-01-15T09:02:47Z",
  "last_asserted": "2026-06-02T02:00:04Z"
}

The response has the same shape as GET /api/quality-checks/{id}, so any client that already reads a check can read a historical version. Deleted checks can be resolved as well.

Execution state is not versioned

Only the check's definition is restored to the requested instant. Execution state such as last_asserted, first_asserted, and active_anomaly_count, along with rule_type (which never changes), always reflects the check as it is now. In the example above, last_asserted is later than version_at because a scan ran after the requested instant. Use latest_container_scan_start_time from Insights or START_TIME in _scan_operations for the timing of a specific evaluation.

Insights

Returns the daily assertion history behind the Insights section of a check: for each day in the window, the result of the latest evaluation, the scan that produced it, and the asserted and anomalous record counts. This is the API equivalent of the pass/fail timeline in the UI and distinguishes checks that could not be evaluated from checks that passed.

Endpoint: GET /api/quality-checks/{id}/insights

Query parameters:

Parameter Type Description
report_date date (default today) Last day of the window, YYYY-MM-DD.
timeframe "week" \| "month" \| "quarter" \| "year" (default week) Length of the window ending on report_date.
offset int Your timezone offset from UTC in minutes, so that days are bucketed in local time. Omit to bucket in UTC.
Example request 
curl -X GET "https://your-instance.qualytics.io/api/quality-checks/778/insights?report_date=2026-06-07&timeframe=week" \
  -H "Authorization: Bearer YOUR_TOKEN"
Example response (abbreviated) 
{
  "generated_at": "2026-06-07T18:21:03Z",
  "start_date": "2026-06-01",
  "end_date": "2026-06-07",
  "timeframe": "week",
  "daily_assertion_measured": [
    {
      "date": "2026-06-01",
      "latest_scan_id": 12345,
      "latest_container_scan_id": 456,
      "latest_container_scan_start_time": "2026-06-01T02:00:00Z",
      "latest_partition_scan_id": 9001,
      "latest_assertion_result": "passed",
      "latest_asserted_records": 120000,
      "latest_anomalous_records": 0,
      "total_scans": 1,
      "total_asserted_records": 120000,
      "total_anomalous_records": 0
    },
    {
      "date": "2026-06-02",
      "latest_scan_id": 12360,
      "latest_container_scan_id": 471,
      "latest_container_scan_start_time": "2026-06-02T02:00:00Z",
      "latest_partition_scan_id": 9017,
      "latest_assertion_result": "failed",
      "latest_asserted_records": 121500,
      "latest_anomalous_records": 37,
      "total_scans": 2,
      "total_asserted_records": 243000,
      "total_anomalous_records": 37
    }
  ]
}

Daily metric fields:

Field Type Description
date date The day the metrics belong to.
latest_scan_id int \| null The scan operation that last evaluated the check that day. Use it with GET /api/operations/{id}.
latest_container_scan_id int \| null The container scan of that evaluation.
latest_container_scan_start_time string \| null When that container scan started, in UTC.
latest_partition_scan_id int \| null The partition scan of that evaluation.
latest_assertion_result "passed" \| "failed" \| "unasserted" \| null Result of the latest evaluation. unasserted means the scan could not evaluate the check (for example, a filter with invalid syntax or a missing column). null means no scan evaluated the check that day.
latest_asserted_records int \| null Records the latest evaluation asserted.
latest_anomalous_records int \| null Records the latest evaluation flagged as anomalous.
total_scans int \| null Number of evaluations that day.
total_asserted_records int \| null Records asserted across all evaluations that day.
total_anomalous_records int \| null Records flagged across all evaluations that day.

Timestamp fields

Field Notes
last_asserted Returned on every check payload. It is the UTC start time of the partition scan that last evaluated the check with a passed or failed result; unasserted evaluations do not move it. null for checks that have never been evaluated. Not versioned: the /version endpoint returns its current value.
created When the check was created, in UTC.