# Diagnostics (/api-v2/diagnostics)



A diagnostic scores reuse opportunity from metadata traces and recommends the lowest-complexity execution profile that improves cost or latency. It runs entirely on metadata: no raw prompt text is required or accepted, matching the privacy-first default. Runs are stored (`dgn_...`) so they can be retrieved by id and rendered as a signed report. See the [workload diagnostics guide](/guides/workload-diagnostics).

All requests require a bearer API key. See [authentication](/api-reference/authentication).

## Run a diagnostic [#run-a-diagnostic]

`POST /v2/diagnostics`

<ParamField body="traces" type="array">
  At least one metadata trace. Each trace:

  <Expandable title="trace">
    <ParamField body="trace_id" type="string">
      Your opaque id for the traced request.
    </ParamField>

    <ParamField body="privacy_mode" type="string">
      The fidelity the trace was captured at: `metadata`, `tokenized`, `encrypted_full_fidelity`, or `synthetic`. The scorer weighs evidence accordingly.
    </ParamField>

    <ParamField body="prefix_family_id" type="string">
      Opaque id of the reusable-prefix family this request belonged to, or `null`.
    </ParamField>

    <ParamField body="schedule" type="object">
      Optional timing and lineage: `arrival_offset_ms`, `session_id`, `branch_id`, `concurrency_group`.
    </ParamField>

    <ParamField body="observed" type="object">
      What was observed: `resolved_target`, `ttft_ms`, `latency_ms`, `input_tokens`, `candidate_reuse_tokens`, `realized_reused_tokens`, `output_tokens`, `attempt_count`.
    </ParamField>
  </Expandable>
</ParamField>

```bash
curl https://api.zumik.ai/v2/diagnostics \
  -H "Authorization: Bearer $ZUMIK_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "traces": [
      {
        "trace_id": "t1",
        "privacy_mode": "metadata",
        "prefix_family_id": "pf_repo_instructions",
        "schedule": { "arrival_offset_ms": 0, "session_id": "ses_abc" },
        "observed": {
          "resolved_target": "openai/gpt-4o",
          "ttft_ms": 410, "latency_ms": 2200,
          "input_tokens": 18240, "candidate_reuse_tokens": 17100,
          "realized_reused_tokens": 14980, "output_tokens": 320, "attempt_count": 1
        }
      }
    ]
  }'
```

```json
{
  "id": "dgn_01jy7nef90h1j2k3l4m5n6o7pq",
  "object": "diagnostic",
  "project_id": "prj_01jy7n0a4c8m2t6v9q3wrxk7bd",
  "created_at": "2026-06-15T16:14:02Z",
  "report": {
    "object": "diagnostic_report",
    "trace_count": 1,
    "workload_reuse_score": 7.4,
    "band": "strong_fit",
    "recommended_action": "...",
    "components": { "...": "..." },
    "waterfall": { "candidate_reuse_tokens": 17100, "realized_reused_tokens": 14980 },
    "recommended_profile": "managed_provider_tuning",
    "notes": ["..."]
  }
}
```

<ResponseField name="id" type="string">
  Opaque diagnostic id, prefixed `dgn_`.
</ResponseField>

<ResponseField name="object" type="string">
  Always `diagnostic`.
</ResponseField>

<ResponseField name="project_id" type="string">
  The owning project.
</ResponseField>

<ResponseField name="created_at" type="string">
  RFC 3339 creation timestamp.
</ResponseField>

<ResponseField name="report" type="object">
  The computed report.

  <Expandable title="report">
    <ResponseField name="object" type="string">
      Always `diagnostic_report`.
    </ResponseField>

    <ResponseField name="trace_count" type="integer">
      Number of traces scored.
    </ResponseField>

    <ResponseField name="workload_reuse_score" type="number">
      The Workload Reuse Score, 0-10.
    </ResponseField>

    <ResponseField name="band" type="string">
      The fit band the score falls in.
    </ResponseField>

    <ResponseField name="recommended_action" type="string">
      The headline recommendation for the band.
    </ResponseField>

    <ResponseField name="components" type="object">
      The score's component breakdown.
    </ResponseField>

    <ResponseField name="waterfall" type="object">
      The reuse waterfall: candidate versus realized reuse tokens.
    </ResponseField>

    <ResponseField name="recommended_profile" type="string">
      The lowest-complexity profile the evidence supports: `optimize_prompt_construction`, `managed_provider_tuning`, `byok_migration`, or `byoc_pilot_worth_evaluating`.
    </ResponseField>

    <ResponseField name="notes" type="array">
      Honest caveats about the evidence.
    </ResponseField>
  </Expandable>
</ResponseField>

## Retrieve a diagnostic [#retrieve-a-diagnostic]

`GET /v2/diagnostics/{diagnostic_id}`

<ParamField path="diagnostic_id" type="string">
  The `dgn_...` id to fetch.
</ParamField>

```bash
curl https://api.zumik.ai/v2/diagnostics/dgn_01jy7nef90h1j2k3l4m5n6o7pq \
  -H "Authorization: Bearer $ZUMIK_API_KEY"
```

Returns the same stored diagnostic object.

## Render a signed report [#render-a-signed-report]

`GET /v2/diagnostics/{diagnostic_id}/report`

Returns a presentation-ready view of the diagnostic with an `evidence_digest`, so a recipient can verify the report was not altered after issuance.

<ParamField path="diagnostic_id" type="string">
  The `dgn_...` id to render.
</ParamField>

```bash
curl https://api.zumik.ai/v2/diagnostics/dgn_01jy7nef90h1j2k3l4m5n6o7pq/report \
  -H "Authorization: Bearer $ZUMIK_API_KEY"
```

```json
{
  "object": "diagnostic_report",
  "diagnostic_id": "dgn_01jy7nef90h1j2k3l4m5n6o7pq",
  "generated_at": "2026-06-15T16:15:30Z",
  "report": { "object": "diagnostic_report", "workload_reuse_score": 7.4, "...": "..." },
  "evidence_digest": "sig_3f9a...c2"
}
```

<ResponseField name="object" type="string">
  Always `diagnostic_report`.
</ResponseField>

<ResponseField name="diagnostic_id" type="string">
  The diagnostic this report renders.
</ResponseField>

<ResponseField name="generated_at" type="string">
  RFC 3339 render timestamp.
</ResponseField>

<ResponseField name="report" type="object">
  The same report body as the stored diagnostic.
</ResponseField>

<ResponseField name="evidence_digest" type="string">
  A SHA-256 digest over the report, prefixed `sig_`. Recompute it to confirm integrity.
</ResponseField>

## Errors [#errors]

| Status | Code                    | When                                           |
| ------ | ----------------------- | ---------------------------------------------- |
| 400    | `invalid_request_error` | `traces` is empty.                             |
| 401    | `invalid_api_key`       | Missing or invalid API key.                    |
| 404    | `invalid_request_error` | The diagnostic does not exist in this project. |

See the full table on [errors](/api-reference/errors).