# Semantic Reporting

Source: https://userguide.qualytics.io/agentq/deep-dive/semantic-reporting/

Semantic reporting lets AgentQ combine filters, grouping, counts, and history requests through a shared query interface. It is the default reporting interface in full AgentQ chat and MCP. Ask a question in ordinary language; AgentQ discovers the relevant schema and prepares the structured request.

The query interface works with Qualytics metadata and permitted evidence. It does not execute SQL you supply, return bulk source records, or change your assets.

## Discover a Resource

When the resource is known, call `describe_query_schema` with its name, such as `anomalies`, to discover supported fields, metrics, defaults, lifecycle rules, and limits. Omit the resource only when you need the resource directory. Reuse the discovered schema for subsequent queries. Only permitted fields and projections are advertised.

Resources include datastores, containers, fields, quality checks, check templates, anomalies, detection-time failed checks, operations, recurring schedules, tags, datastore groups, integrations, stored container and field quality scores, anomaly and partition comments, curated container/anomaly history, and daily insight series (`platform_insights`, `datastore_insights`, `container_insights`, `field_insights`, `quality_check_insights`). Integration metadata requires the Manager or Admin role and supports a category filter, such as alerting or ticketing. Other datastore-owned resources require the Reporter team permission on the datastore.

The following examples show the `plan` argument to `query_qualytics`. Discover the live schema before composing a request: a field available on one resource is not necessarily available on another.

## Resolve an Ambiguous Asset Name

Use `global_search` when a name might identify a datastore, container, or field. For example, `{"search_term":"customers","limit":20}` returns authorized candidate IDs and parent names. A field includes its container and datastore context, so similarly named fields can be distinguished before requesting details.

Exact names, display names, and numeric IDs rank first, followed by prefixes and substrings. Ties use name, asset type, and ID. Numeric field-profile IDs also resolve to the field's stable ID. This is name navigation, not fuzzy similarity or a ranking of business importance. It searches these three asset types only.

The search accepts 1 to 256 characters and returns at most 250 candidates within a response-size limit. When `status` is `success`, `total_count` is the count of matching assets you can access. A failed or refused search returns a null count, which does not mean there are no matches. Check `complete` and `has_more`; refine the term when results are incomplete. Search has no offset paging. Once the resource is known, use schema discovery and `query_qualytics` for reporting filters, groups, and counts. Search does not supply the query grammar.

## Filter and Count by Tag

Datastores, containers, fields, quality checks, and anomalies support `tag.name` and `tag.id` filters. To answer “How many fields have the tag Compliance applied?”:

```json
{
  "resource": "fields",
  "mode": "aggregate",
  "where": {"field": "tag.name", "op": "eq", "value": "Compliance"},
  "metrics": ["field_count"]
}
```

This is a server-calculated count of distinct fields you can access. Multiple matching tags do not count a field more than once. Field metadata remains available for masked, excluded, or missing fields; filter `status` as well if you want a narrower set.

Use `eq` for an exact tag name or ID, `in` for any of several names or IDs, and `contains` for a case-insensitive substring of a tag name. Put separate tag predicates inside `all` to require all of them. Tags are filters here; they cannot be selected as columns or used as grouping keys.

The filter matches tags attached to the requested entity, including tags already propagated to it. For anomalies, it matches the anomaly's current tags. Use `container.tag.name` or `container.tag.id` when you mean tags on its parent container. Neither filter represents the failed check's tags at detection time; historical failed-check evidence remains a separate resource.

## Count Anomalies by Container

This request counts active anomalies by container and returns the largest counts first:

```json
{
  "schema_version": 1,
  "resource": "anomalies",
  "mode": "aggregate",
  "group_by": ["container.id"],
  "metrics": ["anomaly_count"],
  "order_by": [{"field": "anomaly_count", "direction": "desc"}],
  "page": {"limit": 20}
}
```

The count includes distinct anomaly entities visible to you. It is not the number of failed checks or the number of distinct source records affected. Permission and lifecycle filters apply before the count is calculated.

Anomalies default to Active. To include other statuses, specify them explicitly:

```json
{
  "resource": "anomalies",
  "mode": "aggregate",
  "where": {"field": "status", "op": "in", "value": ["Active", "Acknowledged"]},
  "metrics": ["anomaly_count"]
}
```

## List the Checks on a Container or Field

Quality checks expose their current field assignment as a filter and their template linkage as columns. To list the active checks on the `orders` container that involve the `email` field:

```json
{
  "resource": "quality_checks",
  "where": {
    "all": [
      {"field": "container.name", "op": "eq", "value": "orders"},
      {"field": "field.name", "op": "eq", "value": "email"}
    ]
  },
  "select": ["id", "description", "rule_type", "status", "field_count", "template_id", "template_locked"],
  "order_by": [{"field": "created_at", "direction": "desc"}],
  "page": {"limit": 25}
}
```

`field.id` and `field.name` match the check's current field assignment, not the fields involved when an anomaly was detected. `template_id` is null for standalone checks; `template_locked` reports the source template's lock, so a true value means the check's properties follow its template. Checks default to Active; include `Draft` or the archived statuses with an explicit `status` filter. Personal flags such as favorites are not reporting fields.

Templates use the `quality_check_templates` resource, which exposes `template_locked`, `tag.name` filters, and `derived_check_count`. Templates are shared across the workspace, but this count includes only checks in datastores where you have the **Reporter** team permission or higher. It includes all check statuses and excludes deleted checks and deleted parent containers. Your current access applies before the count is selected, filtered, grouped, or sorted.

For example, list the most-used templates within your reporting scope:

```json
{
  "resource": "quality_check_templates",
  "select": ["id", "description", "template_locked", "derived_check_count"],
  "order_by": [{"field": "derived_check_count", "direction": "desc"}],
  "page": {"limit": 10}
}
```

## Count Anomalies by Rule at Detection Time

Each anomaly records the checks that failed when it was detected. That evidence does not change when a check is later edited, archived, or deleted. The `failed_checks` resource has one row per anomaly and failed check, and its `anomaly_count` metric counts distinct anomalies:

```json
{
  "resource": "failed_checks",
  "mode": "aggregate",
  "group_by": ["rule_type"],
  "metrics": ["anomaly_count"],
  "order_by": [{"field": "anomaly_count", "direction": "desc"}]
}
```

An anomaly that failed two checks of different rule types appears in both groups, and once in each. A check's rule type never changes, so the rule type is the detection-time value even when the check has since been archived. Row projections separate current check state (`quality_check.status`, `quality_check.description`) from detection-time evidence (`quality_check.description_at_detection`, `message`); a missing recorded version returns null rather than the current text. Failure messages require Source Data Shared.

The `anomalies` resource carries the same evidence as filters. To list active anomalies whose failed checks involved the `email` field, or that failed a Data Diff check:

```json
{
  "resource": "anomalies",
  "where": {
    "any": [
      {"field": "field.name", "op": "eq", "value": "email"},
      {"field": "failed_check.rule_type", "op": "eq", "value": "dataDiff"}
    ]
  },
  "select": ["id", "type", "status", "container.name", "anomalous_records_count", "failed_check_count", "field_count"],
  "order_by": [{"field": "created_at", "direction": "desc"}],
  "page": {"limit": 25}
}
```

Here `field.name` means the fields involved at detection time, which can differ from the check's current fields. `failed_check_count` and `field_count` describe the same evidence. Both resources apply the ordinary anomaly defaults: Active status unless you filter otherwise, live parent containers, and no soft-deleted anomalies. Retained evidence for deleted anomalies stays on the `anomaly_failed_checks` history resource.

## Count Data Diff Checks

Use `dataDiff` to report on comparison checks. The reporting schema exposes canonical rule names and rejects unsupported values before running a query.

```json
{
  "resource": "quality_checks",
  "mode": "aggregate",
  "where": {"field": "rule_type", "op": "eq", "value": "dataDiff"},
  "metrics": ["check_count"]
}
```

This counts the Data Diff checks you can access, subject to the usual Active default. Use the same rule identifier for templates and grouped reports. Comparison checks do not need separate current and legacy counts.

## Find the Data Diff Check on the Largest Container

Quality checks expose their target container's reporting fields under `container.*`. This request ranks all matching checks you can access by the latest known row count, then returns the first result:

```json
{
  "resource": "quality_checks",
  "where": {"field": "rule_type", "op": "eq", "value": "dataDiff"},
  "select": ["id", "description", "container.id", "container.name", "container.latest_row_count", "container.latest_row_count_at", "container.latest_row_count_source"],
  "order_by": [{"field": "container.latest_row_count", "direction": "desc"}],
  "page": {"limit": 1}
}
```

The target is the container that owns the check. This does not rank its reference container. Checks default to Active. Equal row counts use check ID as a stable tie-breaker; increase the limit to see more matches. Unknown row counts sort last. If the returned row count is null, the available measurements cannot establish a largest container.

`latest_row_count` selects the newer of a valid current profile total and a volume measurement. A freshness-only measurement does not erase an older known volume. A profile that processed more records than its recorded total is not treated as proof that the container is empty. Zero means measured empty; null means unknown. The accompanying time and source identify the selected evidence.

## Query Current Profiles and Derived Properties

Containers expose current profile properties as `latest_profile.*`, including record totals, records processed, profile result, observation time, and check synchronization counts. Fields expose current profile type information and scalar statistics under the same prefix. The current profile is the one selected by Qualytics for that entity, which may differ from the newest profile in its history.

For example, find fields whose current profile reports low completeness:

```json
{
  "resource": "fields",
  "where": {"field": "latest_profile.completeness", "op": "lt", "value": 0.9},
  "select": ["id", "name", "container.name", "latest_profile.completeness", "latest_profile.created_at"],
  "order_by": [{"field": "latest_profile.completeness", "direction": "asc"}],
  "page": {"limit": 20}
}
```

Field statistics require Source Data Shared for selection, filtering, grouping, and sorting. Statistics for masked fields are null in all these operations. Missing profiles also return null. Histograms, source samples, opaque sketches, correlations, and regression models are not exposed through these scalar fields.

Other reporting fields include:

| Resource | Available reporting properties |
| --- | --- |
| Containers | Latest profile, observability measurement, scan and stored quality score; latest row count with its time/source; field, partition, anomaly, and check counts; last profile and scan times. |
| Fields | Latest profile metadata and scalar statistics; stored quality score; anomaly counts based on field membership when anomalies were detected; current active check count. |
| Datastores | Field, container, partition, anomaly and check counts; stored total quality score and container-weighted dimension scores; observability totals and coverage; Data Under Management; latest operation metadata. |
| Quality checks | Target-container reporting properties, assertion times, active anomaly count, passing state, and importance. |

Discover the resource to see exact names, data requirements, and definitions. Numeric fields can be selected, filtered, and sorted; grouping is available where the discovered schema permits it. These are reporting fields on existing resources, so combining them does not require another tool.

## Interpret Datastore Measurements and Counts

Datastore observability totals combine each live container's newest measurement. Some measurements contain freshness information without volume or size, so a total can cover only part of the datastore. Request coverage alongside the total:

```json
{
  "resource": "datastores",
  "select": ["id", "name", "latest_observability_measurement.total_row_count", "latest_observability_measurement.row_count_container_count", "latest_observability_measurement.live_container_count", "latest_observability_measurement.last_measurement_time"],
  "page": {"limit": 20}
}
```

Compare `row_count_container_count` with `live_container_count`. A null total means no included measurement supplies a row count. `last_measurement_time` is the most recent measurement time across the containers, not a guarantee that every container was measured then. Size totals have a separate coverage count.

Datastore `records_count` follows Data Under Management: it uses each container's latest known non-null volume at query time, including enrichment datastores. It can therefore differ from an observability total whose newest measurements contain only freshness information. Unknown container volumes do not become zero in either calculation.

Counts also have different time scopes. `anomaly_count` includes retained anomalies across statuses, including soft-deleted evidence, for live containers. Container active anomaly counts exclude deleted anomalies; field active anomaly counts preserve retained evidence whose status is Active. Field counts use membership at detection time, even when a check's fields have since changed. The derived counts under a field's `latest_profile.*` describe current state, not a snapshot taken when profiling ran.

A container's `fields_count` excludes excluded fields; a datastore's `field_count` includes all field statuses. Application-maintained datastore counters and stored scores can lag recent changes. Passing and failing check counts require a prior assertion; an unasserted check is unknown. Latest operation metadata can describe a queued, running, or failed operation, so inspect its result as well as its time.

## Read Quality Scores and Datastore Dimensions

Containers and fields expose their current stored score under `latest_quality_score.*`, and the `container_scores` and `field_scores` resources hold score history. Datastores expose the same eight dimensions under `quality_score.*`, calculated exactly as the datastore card does:

```json
{
  "resource": "datastores",
  "select": ["id", "name", "quality_score.total", "quality_score.completeness", "quality_score.coverage", "quality_score.timeliness", "quality_score.created_at"],
  "order_by": [{"field": "quality_score.total", "direction": "asc"}],
  "page": {"limit": 20}
}
```

A datastore dimension is a weighted average: multiply each live, scanned container's newest stored score by its container weight, add those values, and divide by the total weight of the containers that contributed a score. Newest means the latest creation time; if timestamps tie, the higher score ID wins. Each container contributes once, and scanned containers without scores do not increase the denominator.

The datastore card and listings use the same calculation. A measured score of zero stays zero. A dimension is null when the datastore has never been scanned, is an enrichment datastore, has no contributing measurement for that dimension, or has no positive total weight. These are stored domain measurements; the interface does not compute new averages across arbitrary sets of containers.

To compare containers in a datastore, or tagged containers across datastores, select `latest_quality_score.*` on the `containers` resource with a `datastore.id` or `tag.name` filter and order by `latest_quality_score.total`. A null score means no stored measurement is available; it does not establish a score of zero.

## Read Daily Insights

Insight resources return one row per UTC calendar day of a window ending today, using the same calculations as the Insights pages. Use `insights` mode with one positive target ID and an optional `timeframe` of `week`, `month`, `quarter` or `year`. The default is `week`:

```json
{
  "resource": "container_insights",
  "mode": "insights",
  "where": {
    "all": [
      {"field": "container.id", "op": "eq", "value": 123},
      {"field": "timeframe", "op": "eq", "value": "month"}
    ]
  },
  "select": ["date", "quality_score.total", "anomalies_identified", "records_measured"]
}
```

`platform_insights` needs no target and accepts optional `datastore.id` and `tag.name` filters; it is always restricted to the datastores you can report on. Use `eq` with one value, such as `123` or `"Finance"`, and `in` with a non-empty array, such as `[123, 456]` or `["Finance", "Compliance"]`. Entity insight resources require `eq` with one target ID. Combine different filters in an `all` group; repeated filters and `any` groups are unsupported.

Each insight row contains `date` and the available values directly under column names such as `quality_score.total` or `anomalies_identified`. The columns vary by resource:

| Resource | Daily columns |
| --- | --- |
| `platform_insights` | `records_measured`, `size_measured`, `anomalies_identified`, `profile_operations`, `scan_operations`, `records_profiled`, `fields_profiled`, `records_scanned`, and `quality_score.*`. The operation counts include successful operations only. |
| `datastore_insights` | `records_measured`, `size_measured`, `anomalies_identified`, and `quality_score.*`. |
| `container_insights` | `records_measured`, `size_measured`, `records_profiled`, `fields_profiled`, `anomalies_identified`, and `quality_score.*`. |
| `field_insights` | `quality_score.*` through the field's current profile. |
| `quality_check_insights` | `assertion.*`, including the latest scan outcome, asserted and anomalous record counts, and daily totals. |

Field insights support active, missing, and excluded fields under live containers you can access. A field without a current profile has no insights.

Totals, trends, and histograms are returned in `provenance.summary`, separate from daily rows. For platform and datastore insights, the check distribution is at `provenance.summary.checks_histogram`. Discover each resource for its exact columns. `select` narrows the daily columns; `date` is always returned, whether or not you select it.

Schema discovery exposes `lifecycle` before you query; the result repeats it in `provenance.lifecycle`. Daily score behavior depends on the resource:

- **Platform and datastore scores** use the latest known score up to each day, so a score can carry forward across days without a new measurement.
- **Container and field scores** include only measurements recorded on that day. **Check assertions** also describe that day's results. These resources do not carry measurements forward.

An omitted column means no measurement is available for that day, not zero activity. A missing score does not establish that checks are absent or that the asset has never been scanned; inspect check coverage and operation history before drawing that conclusion. Insight series do not support pagination, custom sorting, grouping, or `time_series`. They have a **100,000-byte** output budget; an oversized series is refused rather than truncated. Select fewer columns or a shorter timeframe if it exceeds the budget.

For operation activity over time, including failed or aborted runs, use the `operations` resource in aggregate mode with a `time_series` on `created_at`, filtering `type`, `result` or `datastore.id`. `duration_seconds` is available on operation rows; averages and success ratios across operations are model calculations and are disclosed as such.

## Find Datastores without Active Recurring Schedules

```json
{
  "resource": "datastores",
  "where": {"field": "has_active_recurring_schedule", "op": "eq", "value": false},
  "select": ["id", "name"],
  "page": {"limit": 25}
}
```

Schedules attached to flow actions do not count as recurring schedules. A paused recurring schedule does not satisfy the active-schedule condition.

## Find the Next Five Scheduled Operations

```json
{
  "resource": "schedules",
  "where": {"field": "has_next_run", "op": "eq", "value": true},
  "select": ["id", "name", "type", "datastore.name", "next_trigger", "timezone"],
  "order_by": [{"field": "next_trigger", "direction": "asc"}],
  "page": {"limit": 5}
}
```

This returns the earliest persisted next-run times for recurring operation schedules you can access. Deactivated schedules, paused jobs, missing jobs, and schedules attached to flow actions do not qualify. Equal times use schedule ID as a stable tie-breaker.

Each row represents one pending occurrence of a schedule. This does not expand a recurring schedule into several future runs or include scheduled flows. Overdue times remain visible because they may still be pending. The time is a scheduling record, not a guarantee that work will start then. Use `scheduler_state` to distinguish scheduled, paused, missing, and deactivated records; it does not establish scheduler health. A missing timezone setting means UTC.

## Find Failed Operations on a Calendar Day

For “any failed operations from May 15,” establish the year, timezone, and intended time field. This example finds failures completed on May 15, 2026 in New York:

```json
{
  "resource": "operations",
  "where": {
    "all": [
      {"field": "result", "op": "eq", "value": "failure"},
      {"field": "end_time", "op": "gte", "value": "2026-05-15T00:00:00-04:00"},
      {"field": "end_time", "op": "lt", "value": "2026-05-16T00:00:00-04:00"}
    ]
  },
  "select": ["id", "type", "datastore.name", "result", "end_time", "error_code", "fault_domain"],
  "order_by": [{"field": "end_time", "direction": "asc"}],
  "page": {"limit": 25}
}
```

The range includes the start of May 15 and excludes the start of May 16. Use `start_time` instead when you mean operations that started on that date. `created_at` records creation, while `dispatched_at` can reflect a later restart. An operation without a completion time does not match an `end_time` range.

`result` retains the exact outcome or lifecycle state: queued, running, success, failure, partial, or aborted. Failure is distinct from partial completion or an abort. The coarser `status` field matches the polling summary: queued/running map to running, success/partial to completed, and other outcomes to failed. Use `result` when that distinction matters. These reports read stored state; they do not contact workers or wait for an operation to finish.

## List Recent Operations on a Container

Operations expose their target containers as filters. To see the latest runs that targeted the `orders` container:

```json
{
  "resource": "operations",
  "where": {"field": "container.name", "op": "eq", "value": "orders"},
  "select": ["id", "type", "result", "status", "created_at", "end_time", "target_container_count", "has_message"],
  "order_by": [{"field": "created_at", "direction": "desc"}],
  "page": {"limit": 25}
}
```

`container.id` and `container.name` are filters only. They match live containers that belong to the operation's own datastore; a container in another datastore, such as an enrichment datastore, never matches. `target_container_count` counts those same targets, so zero also describes a datastore-wide operation such as a sync. Combine `datastore.id`, `type`, `result` or `status`, and `schedule.id` to narrow the list, and use `status` equal to `running` for work that has not finished. Promotions report their `promote_type`. Target container names and the operation message, when there is one, are available in the operation details; `has_message` tells you whether a message exists.

Recurring schedules expose the same `container.id` and `container.name` filters for their saved target containers, plus `target_tag.name` and `target_tag.id` for saved tag selectors and counts of both. Select `cadence` for the saved five-field cron expression and `timezone` for its interpretation. Cadence supports ordinary filters, grouping, and ordering. Use the schedule detail projection for saved target names and operation options.

## List Schedule Cadence

Schedule listings use `query_qualytics`; the former `list_schedules` tool is no longer available in chat or MCP. To list the newest recurring scan schedules for a datastore:

```json
{
  "resource": "schedules",
  "select": ["id", "name", "type", "cadence", "timezone", "deactivated"],
  "where": {"all": [
    {"field": "datastore.name", "op": "eq", "value": "Warehouse"},
    {"field": "type", "op": "eq", "value": "scan"}
  ]},
  "order_by": [{"field": "created_at", "direction": "desc"}],
  "page": {"limit": 25}
}
```

Omit `deactivated` from the filter to include active and deactivated configurations. Filter it to `true` for deactivated schedules or `false` for active configurations. Unlike the former tool's `only_deactivated=false`, an explicit false predicate narrows the result. Add `container.name` for a saved target container or `target_tag.name` for a saved tag selector. Use `schedule_count` in aggregate mode for an exact count; row pages expose `has_more` and `next_offset`.

## Find Datastores with Daily Schedules

To count pending schedules configured once per calendar day, grouped by datastore:

```json
{
  "resource": "schedules",
  "mode": "aggregate",
  "metrics": ["schedule_count"],
  "group_by": ["datastore.id", "datastore.name"],
  "where": {"all": [
    {"field": "runs_daily", "op": "eq", "value": true},
    {"field": "has_next_run", "op": "eq", "value": true}
  ]}
}
```

`runs_daily` recognizes a saved expression with one numeric minute and hour on every day, such as `30 4 * * *`. It means once per calendar day in the schedule's timezone, not every 24 elapsed hours across daylight-saving changes. Other expressions, including multiple times per day, are not classified as daily. To inspect an exact expression, filter `cadence` with `eq`, or use rows and select `cadence` and `timezone`.

The pending-work filter excludes deactivated schedules, paused jobs, missing jobs, and flow-action schedules. A null cadence means its legacy configuration could not be recovered; it does not mean the schedule does not exist. `runs_daily` is also null in that case. Cadence describes saved configuration, and `scheduler_state` does not establish scheduler health or guarantee execution. Queries do not change schedules or expand recurring schedules into future occurrences.

## Count and Read Anomaly Comments

To answer “how many comments exist on anomaly 123?”:

```json
{
  "resource": "anomaly_comments",
  "mode": "aggregate",
  "where": {"field": "anomaly.id", "op": "eq", "value": 123},
  "metrics": ["comment_count"]
}
```

This counts live root comments and replies. Deleted comment placeholders do not count, but their surviving replies do. The anomaly can be Active, Acknowledged, archived, or retained after soft deletion, provided its parent container is live and you have access. Unlike ordinary anomaly queries, this resource has no Active-status default. Zero means no eligible comments were found; it does not confirm that an inaccessible or nonexistent anomaly exists.

Read recent comment text with Source Data Shared:

```json
{
  "resource": "anomaly_comments",
  "where": {"field": "anomaly.id", "op": "eq", "value": 123},
  "select": ["id", "parent_id", "created_at", "message"],
  "order_by": [{"field": "created_at", "direction": "desc"}],
  "page": {"limit": 20}
}
```

Comment text can contain source values, so selecting, filtering, or sorting by `message` requires Source Data Shared. Metadata counts remain available at Metadata Shared. The result is a flat page of live comments, not a reconstructed conversation with deleted placeholders.

Filter or group comments by `anomaly.status` when you need discussion counts for a particular current status. This is the anomaly's status now, not when the comment was written. Ordinary `anomalies` queries also expose `comment_count` and `latest_comment_at`, subject to their Active default; an explicit `status` filter includes other statuses. The latest-comment time records creation rather than edits. Historical status changes remain available through anomaly history.

## Read Partition Comments

Comments on partitions use the `partition_comments` resource with the same shape. To read the discussion on partition 45 with its authors:

```json
{
  "resource": "partition_comments",
  "where": {"field": "partition.id", "op": "eq", "value": 45},
  "select": ["id", "parent_id", "is_reply", "author.id", "author.name", "created_at", "message"],
  "order_by": [{"field": "created_at", "direction": "asc"}],
  "page": {"limit": 25}
}
```

Both comment resources expose `author.id` and `author.name`, `parent_id` for the parent in the same thread, and `is_reply`. A reply whose parent was deleted still reports that parent ID, although the deleted placeholder itself is never returned. Partition comments require Reporter access to the partition's datastore and a live parent container; comments on containers and quality checks are not available through reporting.

## Request a Weekly Trend

```json
{
  "resource": "operations",
  "mode": "aggregate",
  "where": {
    "all": [
      {"field": "result", "op": "eq", "value": "failure"},
      {"field": "tag.name", "op": "eq", "value": "Finance"}
    ]
  },
  "metrics": ["operation_count"],
  "time_series": {
    "field": "created_at",
    "interval": "week",
    "start": "2026-09-01T00:00:00Z",
    "end": "2026-10-01T00:00:00Z",
    "timezone": "UTC"
  }
}
```

This example groups operations by creation time and uses the datastore's current tags. Buckets use UTC and exclude the end timestamp. An absent bucket means no matching observations were returned. A trend in counts does not by itself establish a cause.

Operation trends use paged aggregate results, with at most 75 rows per page. A quarter of daily buckets can exceed one page, and grouping by result adds more rows. Whenever `has_more` is true, repeat the request with `page.offset` set to `next_offset` until all pages are read before analyzing the full trend.

## Read Details or Configuration History

Use a positive numeric ID from an authorized result. This example requests the current details of container 123:

```json
{
  "resource": "containers",
  "mode": "detail",
  "where": {"field": "id", "op": "eq", "value": 123}
}
```

For the current definition of a computed container, use `mode: "definition"`. Detail and definition requests return fixed, curated projections; omit `select`, sorting, and offsets. Use row mode when you need a smaller selection of scalar fields.

Configuration history is a separate resource:

```json
{
  "resource": "container_history",
  "mode": "history",
  "where": {"field": "container.id", "op": "eq", "value": 123},
  "page": {"limit": 20}
}
```

Container history combines relevant container configuration, grouping, field, and computed-field changes. Read the returned interpretation and coverage notes. Retention and the start of version tracking can limit what is available; an absent event does not prove that a change never happened. Anomaly history and failed-check evidence use `anomaly.id` instead.

History requests return a bounded set of the newest evidence and do not support offsets, arbitrary field selections, or time-series grouping. Anomaly failed-check evidence preserves the check definition used when the anomaly was detected.

## Defaults and Result Interpretation

| Resource or behavior | Default and meaning |
| --- | --- |
| Containers | Includes live source and computed containers. Filter `container_type` to select particular kinds. |
| Fields | Includes active, masked, excluded, and missing field metadata. This does not grant access to masked values. |
| Quality checks | Defaults to Active; an explicit status filter can request Draft or archived states. Soft-deleted checks remain excluded from ordinary reads. Field filters use the current assignment. |
| Quality check templates | Shared template definitions. `derived_check_count` includes checks of all statuses only in your reporting scope and excludes deleted checks and parent containers. |
| Failed checks | One row per anomaly and failed check; `anomaly_count` counts distinct anomalies. Follows anomaly defaults. Rule type and field membership are detection-time; fields labelled current describe the check now. |
| Anomalies | Defaults to Active; an explicit status filter can include archived statuses. Ordinary reads exclude soft-deleted anomalies. |
| Historical anomalies | Can include archived or deleted evidence when its parent container remains available and you are authorized. |
| Schedules | Includes active and paused recurring schedules. Filter `has_next_run` for pending scheduled work. Flow-action schedules are excluded. |
| Operations | Stored lifecycle, outcomes and same-datastore target containers. Use explicit time fields and timezone-aware calendar boundaries; read messages and target names from detail. |
| Anomaly and partition comments | Live comments and replies with author metadata; anomaly comments cover any retained anomaly status with an accessible live parent. Deleted placeholders are excluded. A missing or inaccessible target yields zero comments rather than an error. Text requires Source Data Shared. |
| Tags | Lists shared definitions, including external tags. Entity tag filters use current attached tags. Operations and score queries use the documented parent tags; historical failed-check tags are separate. |
| Scores | Returns stored domain scores, with the latest measurement selected by default. A null score means unmeasured, not zero. |
| Insights | One row per UTC day, ending today; defaults to a week. Platform/datastore scores carry forward; container/field scores and check assertions report only measurements on that day. Missing columns are not zero. |
| Personal and richer reports | Rich profile distributions and personal context (including check favorites) remain on their existing tools. Cross-resource name navigation remains on global_search; schedule cadence is available through reporting. |

Results include applied defaults, scope, page information, and limitations. `returned_count` describes the current page; an unavailable `total_count` is not zero. Follow `next_offset` only when it is present. Pages are separate observations, so concurrent changes may affect a multi-page listing.

A detail or history projection is evidence about one entity. It does not claim that all nested relationships or all past events are included. Explaining a cause or combining several results can still require a model-derived answer and the usual disclosure.

## Permissions, Sharing, and Limits

Every query runs with your current role and team access. Query arguments cannot choose another user or widen your datastore permissions. Unauthorized data does not contribute to counts, sorting, grouping, or relationship filters.

Metadata-only plans remain available at Metadata Shared. Field-profile statistics, container profile completeness, comment text, anomaly descriptions, and historical evidence that can quote values require Source Data Shared. Filtering, sorting, or grouping by those fields also requires that level, even if the field is not returned. Query-specific sharing checks apply to both AgentQ chat and the semantic reporting tools over MCP.

Queries have bounded page sizes, output sizes, filter complexity, and execution time. Time-series requests use UTC and cover at most 366 days, except operation reports, which support up to 1,827 days for five-year reporting. The start is inclusive and the end is exclusive, so include the day after the last date you want to report. Unsupported metrics, arbitrary joins, raw SQL, and overly expensive requests are refused. A refusal or partial result is not evidence that no matching data exists.

The interface supplies counts and stored quality scores. It does not calculate new score formulas, arbitrary averages, or causal explanations. Use the returned schema and limitations to decide whether a question is supported.

## Inspect a Check Template

Use the template resource to read a template's configuration before creating a check from it:

```json
{
  "resource": "quality_check_templates",
  "mode": "detail",
  "where": {"field": "id", "op": "eq", "value": 123}
}
```

Replace the example ID with one discovered from your workspace. Use `quality_checks` for a check attached to a container. Detail requests require a numeric ID and return a curated projection, which may include bounded nested lists.

## See Also

- **Supported AI Providers**

  Every provider you can connect and which ones support file attachments.

  [Supported AI Providers](https://userguide.qualytics.io/agentq/deep-dive/supported-ai-providers/)
- **Amazon Bedrock Authentication**

  The three ways to authenticate to Bedrock, and what an IAM role setup expects.

  [Amazon Bedrock Authentication](https://userguide.qualytics.io/agentq/deep-dive/bedrock-authentication/)
- **Access Controls**

  How an administrator chooses what chat may share with the model, and what each level unlocks.

  [Access Controls](https://userguide.qualytics.io/agentq/deep-dive/access-controls/)
- **AgentQ Audit**

  What each audit entry holds, how cost estimates work, and what the period summary reports.

  [AgentQ Audit](https://userguide.qualytics.io/agentq/deep-dive/audit/)
- **Examples**

  Worked scenarios showing what you ask AgentQ, what it does, and the shape of the answer.

  [Examples](https://userguide.qualytics.io/agentq/deep-dive/examples/)
- **Best Practices**

  Prompt design, cost management, guardrail behavior, rate limits, and async operation patterns.

  [Best Practices](https://userguide.qualytics.io/agentq/deep-dive/best-practices/)
- **Permissions**

  The user roles behind chatting with AgentQ, configuring it, and reading the audit.

  [Permissions](https://userguide.qualytics.io/agentq/deep-dive/permissions/)
- **Introduction**

  What this section covers, and the order to read it in.

  [Introduction](https://userguide.qualytics.io/agentq/deep-dive/introduction/)
- **How It Works**

  Where AgentQ appears, how a turn runs, what it is allowed to see, and its built-in features, including description suggestions.

  [How It Works](https://userguide.qualytics.io/agentq/deep-dive/how-it-works/)
- **The Chat Interface**

  Every control in the full-page and floating chat, and what the input accepts.

  [The Chat Interface](https://userguide.qualytics.io/agentq/deep-dive/chat-interface/)
- **Conversations, Responses & Context**

  How to write prompts, read AgentQ responses, and work with context-aware chats.

  [Conversations, Responses & Context](https://userguide.qualytics.io/agentq/deep-dive/conversations/)
- **AgentQ Limits**

  Rate limits, token usage, timeouts, SQL constraints, and scope constraints.

  [AgentQ Limits](https://userguide.qualytics.io/agentq/deep-dive/limits/)
- **AgentQ in Action**

  Worked examples of AgentQ, its tools, and the steps shown in chat.

  [AgentQ in Action](https://userguide.qualytics.io/agentq/deep-dive/in-action/)
- **Tool Catalog**

  Every tool AgentQ can call, what each one does, and what it shares with the model.

  [Tool Catalog](https://userguide.qualytics.io/agentq/deep-dive/tool-catalog/)

*Last updated: November 7, 2026.*
