> ## Documentation Index
> Fetch the complete documentation index at: https://docs.mediamagicverify.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Insights

> Workspace telemetry: asset, issue, submission, and processing metrics

## What are insights?

Insights are read-only, workspace-scoped analytics derived from your own
submissions, issues, and processing jobs. They answer questions like *how many
assets did we process this month*, *which rules trip most often*, *what share of
submissions pass clean*, and *how much review time are we saving*.

The workspace is implicit — every insights request is scoped to the workspace
behind your API key, so there is no workspace parameter to pass.

<Note>
  Sandbox submissions are excluded from every insights metric. Sandbox keys are
  for integration testing only, so their canned results never count toward your
  workspace's counts, rates, or durations.
</Note>

## Endpoints

Each metric is its own endpoint, so an endpoint's query parameters apply to
exactly the stat it returns (no parameter that quietly does nothing).

| Endpoint                                          | Returns                              | Params                                        |
| ------------------------------------------------- | ------------------------------------ | --------------------------------------------- |
| `GET /insights/assets/count`                      | assets created per day               | `days`, `sidekickId`                          |
| `GET /insights/assets/by-type`                    | asset distribution by file type      | `sidekickId`                                  |
| `GET /insights/assets/violation-rate`             | share of assets with issues, per day | `days`, `sidekickId`                          |
| `GET /insights/issues/by-severity`                | issue counts by severity, per day    | `days`, `sidekickId`                          |
| `GET /insights/issues/by-sidekick`                | issues grouped by sidekick           | `days`                                        |
| `GET /insights/issues/by-file-type`               | issues grouped by file type          | `days`, `sidekickId`                          |
| `GET /insights/submissions/pass-rate`             | clean-completion rate, per day       | `days`, `sidekickId`                          |
| `GET /insights/submissions/by-file-type-sidekick` | success/failure by type × sidekick   | `days`                                        |
| `GET /insights/rules/top-violations`              | most-triggered rule codes            | `days`, `limit`, `sidekickId`                 |
| `GET /insights/processing/duration`               | duration avg + percentiles           | `days`, `sidekickId`                          |
| `GET /insights/processing/time-saved`             | estimated review time saved          | `days`, `sidekickId`, `manualBaselineSeconds` |

All paths are prefixed with `/api`.

## Parameters

* **`days`** — size of the rolling window, `1`–`365` (default `28`). Trend
  series return one point per day in the window, with empty days filled as zero.
* **`sidekickId`** — narrows a metric to a single sidekick. Only present on the
  endpoints where it applies; `by-sidekick` and `by-file-type-sidekick` already
  group *by* sidekick, so they don't take it.
* **`limit`** — caps `top-violations`, `1`–`50` (default `10`).
* **`manualBaselineSeconds`** — the manual-review baseline for the time-saved
  calculation, default `300`. Time saved per asset is
  `max(0, manualBaselineSeconds − averageProcessingSeconds)`.

## Example

```bash theme={null}
curl -H "X-API-Key: your-api-key-here" \
  "https://api.northell.io/nhl/prod/mediamagic-verify-integrations/api/insights/rules/top-violations?days=30&limit=5"
```

```json theme={null}
[
  { "ruleCode": "RULE_A", "count": 9 },
  { "ruleCode": "RULE_B", "count": 4 }
]
```

## Notes

* All counts and rates reflect live data for your workspace — no collection or
  opt-in step is required — and exclude sandbox submissions.
* Processing-duration and time-saved are computed per asset, from the time each
  asset spends in processing (start to completion). Assets still in flight are
  excluded until they finish.
* For high-frequency dashboards, cache responses for a short interval — these are
  daily rollups, so a few seconds of staleness is usually acceptable.