Diagnostic exports

Diagnostic exports let an API client investigate Vibedata using operational logs, traces, metrics, and audit records. Use your Vibedata session or personal API key. You do not need separate Grafana credentials or direct access to its storage services. Your deployment must have Grafana configured.

How to choose the evidence

1. Choose one Intent, one Domain, or the instance. The choice travels in the request body as scope — {"kind":"intent","intentId":"…"} or {"kind":"domain","domainId":"…"} — and omitting it means the instance. There is no Domain- or Intent-specific URL. Vibedata limits evidence to your current access, including Intent sharing. Access to a Domain does not grant access to every Intent in it.
2. Choose logs, traces, metrics, or audit records. Audit requires its own permission. You can also correlate logs, traces, and permitted audit evidence using a session, request, or trace identifier.
3. Narrow the search with the filters supported by that operation. The self filter means your own activity within the selected scope. Multiple identifiers must all match; they do not expand your access.
4. Choose a time range. Ordinary searches default to the last hour and accept a maximum one-hour interval. A trace ID or traceparent copied from DevTools can be used without other filters or timestamps to search retained evidence. An optional time range narrows that lookup.

Metric names and observed field values can be discovered before submitting a query. Discovery is bounded and subject to your access; it is not a complete inventory of the deployment.

How to retrieve an export

1. Submit the diagnostic request from your API client and retain the returned run ID.
2. Poll the run until it finishes.
3. Download the ZIP using the download address returned by a successful run. A run with a warning can still have usable evidence.
4. Read the manifest first. It identifies the request, source outcomes, queried time windows, and known coverage limits. The remaining files contain the native responses from the sources that completed successfully.

Only the authenticated requester can inspect or download the run, including when another user is a Vibedata Owner. Vibedata checks your access again when you download: the export must still be covered by the access you have at that moment. If you have since lost a Domain, an Intent, or audit access that the export was captured under, the download is refused with 403 and the code diagnostic.access_denied. You still need valid credentials; a revoked key no longer authenticates.

The same diagnostic.access_denied answers a capture whose scope can no longer be re-verified, so the code on its own does not prove that your access was revoked — check the scope you asked for and your current access.

The export keeps the evidence exactly as it was captured. Vibedata does not re-filter it to your current access; it refuses the download instead.

Your export remains available across backend restarts and routing changes while its shared file exists. It is retained for the deployment's diagnostic run-history retention plus a one-day safety margin, and the daily lifecycle job removes it after that, so an export is not stored indefinitely. Submit a new request if the file is gone, and keep your own copy if you need it longer.

Diagnostic submits and reads are rate-limited per caller and per backend process: 60 queries and 120 reads per minute. A refusal answers 429 with Retry-After; wait for that interval rather than retrying immediately.

How to interpret the result

Outcome	Meaning and next step
Queued or running	Poll again; the archive is not ready.
Succeeded	The queried sources completed. Check the manifest for native result limits.
Warning	Some evidence is usable, but a source failed, was denied, or reported partial results. Inspect the source outcomes.
Failed	No usable export was produced. Inspect the reported error before retrying.
Empty native result	The query completed with no matches. This does not prove that no event occurred or that older evidence is retained.
Operation not supported	Grafana is not configured for this Vibedata deployment.
Source unavailable	Grafana or a configured source could not serve the request. This is distinct from no matching records.
Missing artifact	The archive file is gone. Submit another request.

Error codes

Failures carry a stable dotted code in the response body, and a finished run reports the same vocabulary on its own error.code, so a code reads the same whichever surface you check.

Code	Meaning and next step
diagnostic.invalid_query	The query is well-formed but not valid for that operation: step outside a range metric, metric selectors on a non-metric query, a correlation request with no identifier, or a trace-ID search with no verified retention. Change the request, not the credentials.
diagnostic.access_denied	You lost access the capture depended on. A download answers it when your current access no longer covers the scope the export was captured under, or that scope could no longer be re-verified; a run reports it when you lost the authority before execution began. Check your current Domain, Intent and audit access.
diagnostic.resource_unavailable	The scope no longer exists — for example a Domain or Intent that was deleted while the request was running.
diagnostic.monitor_failed	Vibedata could not verify the run's queue state while executing it.
diagnostic.scope_too_large	A submit-time refusal: your access covers too many Domains or Intents to resolve into one authorized scope, so the query never runs — select one Intent. A download never answers this code; the same condition there is diagnostic.access_denied.
validation.failed	The request body did not match the schema — an unknown field, a malformed UUID, a wrong type, a contradictory trace ID and traceparent, or a window longer than one hour. This is the API-wide shape code, not a query result.

Audit Records answers its own audit_records.* codes; its shape failures are validation.failed too.

Native query limits still apply. A trace search returns matching span sets and native trace metadata; it does not promise a complete trace tree. Exports are limited to 25 MiB of uncompressed content, and queries have a 60-second execution budget. Oversized or interrupted responses are omitted and reported in the manifest when other sources succeeded.

Direct Grafana access is separately restricted to Vibedata Owners. Permission to use Vibedata diagnostic exports does not grant access to the shared Grafana UI.