Diagnostics

Run the Agent Workload Efficiency Diagnostic over metadata traces, retrieve a stored run, and render a signed report with an evidence digest.

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.

All requests require a bearer API key. See authentication.

Run a diagnostic

POST /v2/diagnostics

tracesarrayrequired

At least one metadata trace. Each trace:

trace

trace_idstringrequired

Your opaque id for the traced request.

privacy_modestringrequired

The fidelity the trace was captured at: metadata, tokenized, encrypted_full_fidelity, or synthetic. The scorer weighs evidence accordingly.

prefix_family_idstring

Opaque id of the reusable-prefix family this request belonged to, or null.

scheduleobject

Optional timing and lineage: arrival_offset_ms, session_id, branch_id, concurrency_group.

observedobjectrequired

What was observed: resolved_target, ttft_ms, latency_ms, input_tokens, candidate_reuse_tokens, realized_reused_tokens, output_tokens, attempt_count.

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
        }
      }
    ]
  }'

{
  "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": ["..."]
  }
}

idstring

Opaque diagnostic id, prefixed dgn_.

objectstring

Always diagnostic.

project_idstring

The owning project.

created_atstring

RFC 3339 creation timestamp.

reportobject

The computed report.

report

objectstring

Always diagnostic_report.

trace_countinteger

Number of traces scored.

workload_reuse_scorenumber

The Workload Reuse Score, 0-10.

bandstring

The fit band the score falls in.

recommended_actionstring

The headline recommendation for the band.

componentsobject

The score's component breakdown.

waterfallobject

The reuse waterfall: candidate versus realized reuse tokens.

recommended_profilestring

The lowest-complexity profile the evidence supports: optimize_prompt_construction, managed_provider_tuning, byok_migration, or byoc_pilot_worth_evaluating.

notesarray

Honest caveats about the evidence.

Retrieve a diagnostic

GET /v2/diagnostics/{diagnostic_id}

diagnostic_idstringpathrequired

The dgn_... id to fetch.

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

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.

diagnostic_idstringpathrequired

The dgn_... id to render.

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

{
  "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"
}

objectstring

Always diagnostic_report.

diagnostic_idstring

The diagnostic this report renders.

generated_atstring

RFC 3339 render timestamp.

reportobject

The same report body as the stored diagnostic.

evidence_digeststring

A SHA-256 digest over the report, prefixed sig_. Recompute it to confirm integrity.

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.

Diagnostics

Run a diagnostic

Retrieve a diagnostic

Render a signed report

Errors

On this page