Analyses

Poll an analysis

Returns run status, readyForExport, enrichment progress, per-module statuses (deep runs), and report/share URLs. Accepts the run id or the report id; any personal starter or deep report the key's account owns resolves, including ones created on the preuve.ai dashboard (their analysis id is the report id, clientRunId is null). Agency client reports are outside that fallback - read those with workspace agency - and so are legacy roast reports, which answer 404. That wider reach is specific to this route, because it returns status rather than payload: export and enrich answer 403 REPORT_NOT_FROM_AGENT_RUN for a dashboard report, and such a response carries exportable false with the reason. Does not return the report payload: use export, on an analysis this API started.

get/api/agent/analyses/{id}

Request

  • Base URL: https://preuve.ai
  • URL: https://preuve.ai/api/agent/analyses/{id}
  • Auth: API key in header x-preuve-key

Path parameters

idstring uuid required

Run id (returned by create) or report id. What resolves differs per route: the poll also accepts any personal starter or deep report the account owns, including dashboard-created ones (the UUID in /app/results?id=...), while export and enrich serve analyses this API started. See each operation.

Response

Current run state.

idstring uuid
reportIdstring uuid nullable

Null until the report row is attached, which is why a run that failed before dispatch is retryable under the same clientRunId.

clientRunIdstring nullable

The caller-chosen id from create. Null when the analysis is a dashboard-created report resolved by its report id: no run row exists, so there is no clientRunId to replay.

batchIdstring uuid nullable

The batch this run belongs to, or null for a standalone run.

scanType'starter' | 'deep'

Your request type. Reliable from creation, even while PROCESSING.

enrichmentMode'core' | 'none'
publishboolean
reportType'quick' | 'deep_dive' | 'null' nullable
analysisTier'basic' | 'advanced' | 'null' nullable

Derived from the report. Deep runs read "basic" until deep sections land.

status'PENDING' | 'PROCESSING' | 'COMPLETED' | 'FAILED'
progressStepstring nullable

Free-text pipeline stage while PROCESSING.

errorCodestring nullable

Set on a FAILED run. Two internal markers are deliberately rewritten before they leave: an ambiguous dispatch reports TRIGGER_DISPATCH_FAILED and an ambiguous claim refund reports REPORT_CREATE_FAILED.

errorMessagestring nullable
resetAtstring date-time

Present only on a batch item refused by the rolling daily cap; absent, not null, on every other run.

pollAfterSecondsinteger

Present only while polling is still useful. Pace by this rather than by a fixed interval.

pollHintstring

Present alongside pollAfterSeconds.

createdAtstring date-time
updatedAtstring date-time
readyForExportboolean

Whether GET /export will serve this analysis now. Always false for a report created on the preuve.ai dashboard, whatever state the report is in, because that export answers 403 REPORT_NOT_FROM_AGENT_RUN. Branch on exportable first.

exportableboolean

Present, and false, only on a report created on the preuve.ai dashboard. Absent means the ordinary contract applies and readyForExport is the gate. When it is false, no amount of polling or enriching changes it.

exportBlockedCode'REPORT_NOT_FROM_AGENT_RUN'

Present alongside exportable, naming the refusal.

exportBlockedHintstring

Present alongside exportable. Relayable prose.

reportUrlstring uri nullable

Null until the report row exists.

shareUrlstring uri nullable

Changes

No recorded changes to this operation across all 1 revision of this API.