# Observability API

Source: https://userguide.qualytics.io/observability/api/

REST endpoints for reading Observability listings and measurements, and for toggling Volume Tracking and Freshness Tracking on containers.

- **Base URL:** `https://<your-deployment>/api`
- **Authentication:** Bearer token in the `Authorization` header. See [Personal Access Tokens](https://userguide.qualytics.io/settings/access-tokens/personal-token/introduction/) for how to obtain one.

> **Tip: Complete API Reference**
>
> The full interactive OpenAPI schema is served at `/api/docs` and stays in sync with your deployment. Use this page for the Observability-specific endpoints, and `/api/docs` for the complete, current reference.

> **Note: Permissions**
>
> - Listing endpoints require a signed-in workspace user with at least a **Member** role. Team-permission gating on the underlying datastore still applies to the returned rows.
> - Modifying checks (thresholds, Maximum Age) requires the **Author** team permission on the datastore.
> - Toggling Volume or Freshness Tracking requires the **Editor** team permission on the datastore of every container in the request.

## Endpoints at a glance

| Method | Endpoint | Purpose |
| --- | --- | --- |
| `GET` | `/observability` | List Measures cards (Volumetric + Freshness per container) with filters, sort, timeframe, and report date. |
| `GET` | `/quality-checks/measurements` | List Metric checks with their most recent measurements. |
| `PATCH` | `/containers/volumetric-tracking` | Bulk update Volume Tracking and Freshness Tracking flags on containers. |
| `PUT` | `/quality-checks/{id}` | Update thresholds, Maximum Age, or other properties on a specific check. |

## List Measures

**Endpoint:** `GET /observability`
**Permission:** Any authenticated workspace user. Datastore-level team permissions gate the returned rows.

Returns a paginated list of container-observability rows for the **Measures** tab. Each row includes the container identity, its active anomaly count, its active-check summary, and its recent daily measurements.

Common query parameters:

| Parameter | Type | Description |
| --- | --- | --- |
| `datastore` | integer | Filter to a single datastore. |
| `container` | integer | Filter to a single container. |
| `search` | string | Match container name or identifier. |
| `tag` | string[] | Filter by one or more tag names. |
| `rule_type` | string | `volumetric` or `freshness`. |
| `report_date` | date | Anchor the timeframe to end on this date (YYYY-MM-DD). Send it on every request. When omitted, the window can end on an earlier day instead of today. |
| `timeframe` | string | `week`, `month`, `quarter`, or `year`. |
| `filters` | `string` (JSON) | Narrows the list by one or more filters, written as a JSON object. See [Filtering Lists](https://userguide.qualytics.io/observability/api/#filtering-lists). |
| `sort_name` | string | `asc` or `desc`. |
| `sort_container_type` | string | `asc` or `desc`. |
| `sort_created` | string | `asc` or `desc`. |
| `sort_observability_active_anomalies` | string | `asc` or `desc`. |
| `sort_observability_active_checks` | string | `asc` or `desc`. |
| `sort_last_scanned` | string | `asc` or `desc`. |

> **Example: List Measures rows for a datastore, sorted by anomalies**
>
> ```bash
> curl -X GET 'https://<your-deployment>/api/observability?datastore=42&timeframe=month&report_date=<YYYY-MM-DD>&sort_observability_active_anomalies=desc' \
>   -H 'Authorization: Bearer <token>'
> ```

### Filtering Lists

`GET /api/observability` and `GET /api/quality-checks/measurements` accept a `filters` parameter: a JSON object with one entry per filter, saying how that filter's values should match.

```bash
curl -G "https://your-instance.qualytics.io/api/observability" \
  --data-urlencode 'filters={"tag":{"not_in":["PII"]}}' \
  -H "Authorization: Bearer YOUR_TOKEN"
```

This returns the tables and files that aren't tagged `PII`.

| Key | Returns |
| --- | --- |
| `in` | The items that match at least one of the values. |
| `not_in` | The items that match none of the values. |
| `all_of` | The items that match every value, on filters an item can have several of, such as tags. |
| `empty` | The items with no value (`true`) or at least one (`false`), on filters an item can lack. |

- Different filters combine with AND, and so do keys on the same filter.
- `empty` can't be combined with other keys on the same filter.
- A filter sent both as its own parameter and inside `filters` returns a `422`. Put all of that filter's conditions in `filters`.
- `in`, `not_in` and `all_of` each take between 1 and 20 values.
- A filter or key the endpoint doesn't accept returns a `422` that names it. The [API docs](https://userguide.qualytics.io/api/docs) list what each endpoint accepts.

## List Metric measurements

**Endpoint:** `GET /quality-checks/measurements`
**Permission:** Any authenticated workspace user. Datastore-level team permissions gate the returned rows.

Returns Metric checks with their most recent measurements (up to the last 11 per check).

Common query parameters:

| Parameter | Type | Description |
| --- | --- | --- |
| `id` | integer[] | Filter to a specific check id. |
| `template` | integer[] | Filter to checks derived from a specific template. |
| `datastore` | integer | Filter to a single datastore. |
| `container` | integer | Filter to a single container. |
| `field` | string[] | Filter by one or more field identifiers. |
| `tag` | string[] | Filter by one or more tag names. |
| `search` | string | Match description or identifier. |
| `filters` | `string` (JSON) | Narrows the list by one or more filters, written as a JSON object. See [Filtering Lists](https://userguide.qualytics.io/observability/api/#filtering-lists). |
| `sort_id` | string | `asc` or `desc`. |
| `sort_favorite` | string | `asc` or `desc`. |
| `sort_created` | string | `asc` or `desc`. |
| `sort_active_anomalies` | string | `asc` or `desc`. |

> **Example: List Metric checks for a container, newest first**
>
> ```bash
> curl -X GET 'https://<your-deployment>/api/quality-checks/measurements?container=123&sort_created=desc' \
>   -H 'Authorization: Bearer <token>'
> ```

## Toggle Volume / Freshness Tracking

**Endpoint:** `PATCH /containers/volumetric-tracking`
**Permission:** **Editor** team permission on the datastore of every container in the request. The whole request is rejected when any container is missing or the caller lacks Editor on it, and nothing changes.

Bulk-updates the Volume Tracking and Freshness Tracking flags on one or more containers. This is the endpoint the Observability Settings modal calls.

The request body is a JSON array with one object per container. Each object takes these fields:

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `id` | integer | Yes | Id of the container to update. |
| `volumetric_tracking_enabled` | boolean | Yes | Toggle Volume Tracking. |
| `freshness_tracking_enabled` | boolean | Yes | Toggle Freshness Tracking. |
| `automate_volumetric_checks` | boolean | No | Toggle **Create AI Volumetric checks**. |
| `automate_freshness_checks` | boolean | No | Toggle **Create AI Freshness checks**. |

Turning tracking off cascades: the matching automation flag is also cleared server-side.

> **Example: Enable Volume + Freshness tracking on multiple containers**
>
> ```bash
> curl -X PATCH 'https://<your-deployment>/api/containers/volumetric-tracking' \
>   -H 'Authorization: Bearer <token>' \
>   -H 'Content-Type: application/json' \
>   -d '[
>     {
>       "id": 123,
>       "volumetric_tracking_enabled": true,
>       "freshness_tracking_enabled": true,
>       "automate_volumetric_checks": true,
>       "automate_freshness_checks": false
>     },
>     {
>       "id": 124,
>       "volumetric_tracking_enabled": true,
>       "freshness_tracking_enabled": true,
>       "automate_volumetric_checks": true,
>       "automate_freshness_checks": false
>     }
>   ]'
> ```

## Update thresholds or Maximum Age

**Endpoint:** `PUT /quality-checks/{id}`
**Permission:** **Author** team permission on the datastore (Editor on the datastore always allowed).

The inline **Edit Threshold** and **Edit Maximum Age** actions on the Observability chart both call this endpoint. The `PUT` endpoint requires `description` and the full `properties` object, which replaces the stored one. Include every property the check uses, not only the one you change. Metric checks also need `fields`.

- For Volumetric and Metric threshold edits, set `properties.min` and `properties.max`. Copy the other properties, such as `comparison` and `window_size`, from the existing check (read it with `GET /api/quality-checks/{id}`). The comparison cannot change once the check has been asserted, and a different `window_size` would also change the measurement period.
- For Freshness Maximum Age edits, set `properties.value` (milliseconds).

> **Example: Update Volumetric thresholds**
>
> ```bash
> curl -X PUT 'https://<your-deployment>/api/quality-checks/6789' \
>   -H 'Authorization: Bearer <token>' \
>   -H 'Content-Type: application/json' \
>   -d '{
>     "description": "Daily row count stays between 25,000 and 70,000",
>     "properties": {
>       "comparison": "Absolute Value",
>       "window_size": 1,
>       "min": 25000,
>       "max": 70000
>     }
>   }'
> ```

> **Example: Update Maximum Age to 3 hours**
>
> ```bash
> curl -X PUT 'https://<your-deployment>/api/quality-checks/6790' \
>   -H 'Authorization: Bearer <token>' \
>   -H 'Content-Type: application/json' \
>   -d '{
>     "description": "Table is refreshed at least every 3 hours",
>     "properties": {
>       "value": 10800000
>     }
>   }'
> ```

## Error responses

| Status | Meaning |
| --- | --- |
| 400 | Malformed request payload, invalid sort direction, or invalid enum value on `rule_type` / `timeframe`. |
| 401 | Missing or expired bearer token. |
| 403 | Authenticated but the requesting user lacks the required team permission on the datastore. |
| 404 | Referenced datastore, container, or check does not exist or is not visible to the requesting user. |
| 422 | Body validation failure (for example, `description` missing, `min` greater than `max`, or unsupported unit value). |

*Last updated: October 15, 2026.*
