Poll an analysis

curl --request GET \
  --url https://preuve.ai/api/agent/analyses/{id} \
  --header 'x-preuve-key: <api-key>'

const options = {method: 'GET', headers: {'x-preuve-key': '<api-key>'}};

fetch('https://preuve.ai/api/agent/analyses/{id}', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://preuve.ai/api/agent/analyses/{id}",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_HTTPHEADER => [
    "x-preuve-key: <api-key>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://preuve.ai/api/agent/analyses/{id}"

	req, _ := http.NewRequest("GET", url, nil)

	req.Header.Add("x-preuve-key", "<api-key>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

require 'uri'
require 'net/http'

url = URI("https://preuve.ai/api/agent/analyses/{id}")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)
request["x-preuve-key"] = '<api-key>'

response = http.request(request)
puts response.read_body

{
  "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "reportId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "clientRunId": "<string>",
  "batchId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "scanType": "starter",
  "enrichmentMode": "core",
  "publish": true,
  "reportType": "quick",
  "analysisTier": "basic",
  "status": "PENDING",
  "progressStep": "<string>",
  "errorCode": "<string>",
  "errorMessage": "<string>",
  "resetAt": "2023-11-07T05:31:56Z",
  "pollAfterSeconds": 123,
  "pollHint": "<string>",
  "createdAt": "2023-11-07T05:31:56Z",
  "updatedAt": "2023-11-07T05:31:56Z",
  "readyForExport": true,
  "exportable": true,
  "exportBlockedCode": "REPORT_NOT_FROM_AGENT_RUN",
  "exportBlockedHint": "<string>",
  "enrichment": {
    "mode": "core",
    "status": "not_required",
    "required": [
      "<string>"
    ],
    "completed": [
      "<string>"
    ],
    "missing": [
      "<string>"
    ],
    "processing": [
      "<string>"
    ],
    "failed": [
      "<string>"
    ],
    "sections": {}
  },
  "modules": {
    "proofOfDemand": {
      "status": "not_generated"
    },
    "founderFit": {
      "status": "not_generated"
    },
    "playbook": {
      "status": "not_generated"
    },
    "trends": {
      "status": "not_generated"
    },
    "community": {
      "status": "not_generated"
    }
  },
  "reportUrl": "<string>",
  "shareUrl": "<string>"
}

{
  "error": "<string>",
  "code": "<string>",
  "details": {},
  "limit": 123,
  "remaining": 123,
  "resetAt": "2023-11-07T05:31:56Z",
  "tokenBalance": 123,
  "scansUsed": 123,
  "scansRemaining": 123,
  "limitType": "<string>",
  "upgradeHint": "<string>",
  "paused": true,
  "upsell": {
    "offer": "founder_report",
    "price": "<string>",
    "guarantee": "<string>",
    "url": "<string>",
    "locked": [
      "<string>"
    ],
    "note": "<string>"
  }
}

{
  "error": "<string>",
  "code": "<string>",
  "details": {},
  "limit": 123,
  "remaining": 123,
  "resetAt": "2023-11-07T05:31:56Z",
  "tokenBalance": 123,
  "scansUsed": 123,
  "scansRemaining": 123,
  "limitType": "<string>",
  "upgradeHint": "<string>",
  "paused": true,
  "upsell": {
    "offer": "founder_report",
    "price": "<string>",
    "guarantee": "<string>",
    "url": "<string>",
    "locked": [
      "<string>"
    ],
    "note": "<string>"
  }
}

{
  "error": "<string>",
  "code": "<string>",
  "details": {},
  "limit": 123,
  "remaining": 123,
  "resetAt": "2023-11-07T05:31:56Z",
  "tokenBalance": 123,
  "scansUsed": 123,
  "scansRemaining": 123,
  "limitType": "<string>",
  "upgradeHint": "<string>",
  "paused": true,
  "upsell": {
    "offer": "founder_report",
    "price": "<string>",
    "guarantee": "<string>",
    "url": "<string>",
    "locked": [
      "<string>"
    ],
    "note": "<string>"
  }
}

{
  "error": "<string>",
  "code": "<string>",
  "details": {},
  "limit": 123,
  "remaining": 123,
  "resetAt": "2023-11-07T05:31:56Z",
  "tokenBalance": 123,
  "scansUsed": 123,
  "scansRemaining": 123,
  "limitType": "<string>",
  "upgradeHint": "<string>",
  "paused": true,
  "upsell": {
    "offer": "founder_report",
    "price": "<string>",
    "guarantee": "<string>",
    "url": "<string>",
    "locked": [
      "<string>"
    ],
    "note": "<string>"
  }
}

{
  "error": "<string>",
  "code": "<string>",
  "details": {},
  "limit": 123,
  "remaining": 123,
  "resetAt": "2023-11-07T05:31:56Z",
  "tokenBalance": 123,
  "scansUsed": 123,
  "scansRemaining": 123,
  "limitType": "<string>",
  "upgradeHint": "<string>",
  "paused": true,
  "upsell": {
    "offer": "founder_report",
    "price": "<string>",
    "guarantee": "<string>",
    "url": "<string>",
    "locked": [
      "<string>"
    ],
    "note": "<string>"
  }
}

{
  "error": "<string>",
  "code": "<string>",
  "details": {},
  "limit": 123,
  "remaining": 123,
  "resetAt": "2023-11-07T05:31:56Z",
  "tokenBalance": 123,
  "scansUsed": 123,
  "scansRemaining": 123,
  "limitType": "<string>",
  "upgradeHint": "<string>",
  "paused": true,
  "upsell": {
    "offer": "founder_report",
    "price": "<string>",
    "guarantee": "<string>",
    "url": "<string>",
    "locked": [
      "<string>"
    ],
    "note": "<string>"
  }
}

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}

Poll an analysis

curl --request GET \
  --url https://preuve.ai/api/agent/analyses/{id} \
  --header 'x-preuve-key: <api-key>'

const options = {method: 'GET', headers: {'x-preuve-key': '<api-key>'}};

fetch('https://preuve.ai/api/agent/analyses/{id}', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://preuve.ai/api/agent/analyses/{id}",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_HTTPHEADER => [
    "x-preuve-key: <api-key>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://preuve.ai/api/agent/analyses/{id}"

	req, _ := http.NewRequest("GET", url, nil)

	req.Header.Add("x-preuve-key", "<api-key>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

require 'uri'
require 'net/http'

url = URI("https://preuve.ai/api/agent/analyses/{id}")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)
request["x-preuve-key"] = '<api-key>'

response = http.request(request)
puts response.read_body

{
  "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "reportId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "clientRunId": "<string>",
  "batchId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "scanType": "starter",
  "enrichmentMode": "core",
  "publish": true,
  "reportType": "quick",
  "analysisTier": "basic",
  "status": "PENDING",
  "progressStep": "<string>",
  "errorCode": "<string>",
  "errorMessage": "<string>",
  "resetAt": "2023-11-07T05:31:56Z",
  "pollAfterSeconds": 123,
  "pollHint": "<string>",
  "createdAt": "2023-11-07T05:31:56Z",
  "updatedAt": "2023-11-07T05:31:56Z",
  "readyForExport": true,
  "exportable": true,
  "exportBlockedCode": "REPORT_NOT_FROM_AGENT_RUN",
  "exportBlockedHint": "<string>",
  "enrichment": {
    "mode": "core",
    "status": "not_required",
    "required": [
      "<string>"
    ],
    "completed": [
      "<string>"
    ],
    "missing": [
      "<string>"
    ],
    "processing": [
      "<string>"
    ],
    "failed": [
      "<string>"
    ],
    "sections": {}
  },
  "modules": {
    "proofOfDemand": {
      "status": "not_generated"
    },
    "founderFit": {
      "status": "not_generated"
    },
    "playbook": {
      "status": "not_generated"
    },
    "trends": {
      "status": "not_generated"
    },
    "community": {
      "status": "not_generated"
    }
  },
  "reportUrl": "<string>",
  "shareUrl": "<string>"
}

{
  "error": "<string>",
  "code": "<string>",
  "details": {},
  "limit": 123,
  "remaining": 123,
  "resetAt": "2023-11-07T05:31:56Z",
  "tokenBalance": 123,
  "scansUsed": 123,
  "scansRemaining": 123,
  "limitType": "<string>",
  "upgradeHint": "<string>",
  "paused": true,
  "upsell": {
    "offer": "founder_report",
    "price": "<string>",
    "guarantee": "<string>",
    "url": "<string>",
    "locked": [
      "<string>"
    ],
    "note": "<string>"
  }
}

{
  "error": "<string>",
  "code": "<string>",
  "details": {},
  "limit": 123,
  "remaining": 123,
  "resetAt": "2023-11-07T05:31:56Z",
  "tokenBalance": 123,
  "scansUsed": 123,
  "scansRemaining": 123,
  "limitType": "<string>",
  "upgradeHint": "<string>",
  "paused": true,
  "upsell": {
    "offer": "founder_report",
    "price": "<string>",
    "guarantee": "<string>",
    "url": "<string>",
    "locked": [
      "<string>"
    ],
    "note": "<string>"
  }
}

{
  "error": "<string>",
  "code": "<string>",
  "details": {},
  "limit": 123,
  "remaining": 123,
  "resetAt": "2023-11-07T05:31:56Z",
  "tokenBalance": 123,
  "scansUsed": 123,
  "scansRemaining": 123,
  "limitType": "<string>",
  "upgradeHint": "<string>",
  "paused": true,
  "upsell": {
    "offer": "founder_report",
    "price": "<string>",
    "guarantee": "<string>",
    "url": "<string>",
    "locked": [
      "<string>"
    ],
    "note": "<string>"
  }
}

{
  "error": "<string>",
  "code": "<string>",
  "details": {},
  "limit": 123,
  "remaining": 123,
  "resetAt": "2023-11-07T05:31:56Z",
  "tokenBalance": 123,
  "scansUsed": 123,
  "scansRemaining": 123,
  "limitType": "<string>",
  "upgradeHint": "<string>",
  "paused": true,
  "upsell": {
    "offer": "founder_report",
    "price": "<string>",
    "guarantee": "<string>",
    "url": "<string>",
    "locked": [
      "<string>"
    ],
    "note": "<string>"
  }
}

{
  "error": "<string>",
  "code": "<string>",
  "details": {},
  "limit": 123,
  "remaining": 123,
  "resetAt": "2023-11-07T05:31:56Z",
  "tokenBalance": 123,
  "scansUsed": 123,
  "scansRemaining": 123,
  "limitType": "<string>",
  "upgradeHint": "<string>",
  "paused": true,
  "upsell": {
    "offer": "founder_report",
    "price": "<string>",
    "guarantee": "<string>",
    "url": "<string>",
    "locked": [
      "<string>"
    ],
    "note": "<string>"
  }
}

{
  "error": "<string>",
  "code": "<string>",
  "details": {},
  "limit": 123,
  "remaining": 123,
  "resetAt": "2023-11-07T05:31:56Z",
  "tokenBalance": 123,
  "scansUsed": 123,
  "scansRemaining": 123,
  "limitType": "<string>",
  "upgradeHint": "<string>",
  "paused": true,
  "upsell": {
    "offer": "founder_report",
    "price": "<string>",
    "guarantee": "<string>",
    "url": "<string>",
    "locked": [
      "<string>"
    ],
    "note": "<string>"
  }
}

Authorizations

x-preuve-key

string

header

required

Your API key (prv_...), sent as-is. It is the only credential the API needs - see the Authentication guide.

Path Parameters

string<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.

string<uuid>

reportId

string<uuid> | null

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

clientRunId

string | null

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.

batchId

string<uuid> | null

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

scanType

enum<string>

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

Available options:

starter,

deep

enrichmentMode

enum<string>

Available options:

core,

none

publish

boolean

reportType

enum<string> | null

Available options:

quick,

deep_dive,

null

analysisTier

enum<string> | null

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

Available options:

basic,

advanced,

null

status

enum<string>

Available options:

PENDING,

PROCESSING,

COMPLETED,

FAILED

progressStep

string | null

Free-text pipeline stage while PROCESSING.

errorCode

string | null

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.

errorMessage

string | null

resetAt

string<date-time>

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

pollAfterSeconds

integer

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

pollHint

string

Present alongside pollAfterSeconds.

createdAt

string<date-time>

updatedAt

string<date-time>

readyForExport

boolean

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.

exportable

boolean

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

enum<string>

Present alongside exportable, naming the refusal.

Available options:

REPORT_NOT_FROM_AGENT_RUN

exportBlockedHint

string

Present alongside exportable. Relayable prose.

enrichment

object

Progress of the core export sections. The four name arrays partition required, so a poller decides what to do next by reading them rather than by parsing status: anything in processing means keep polling, anything in failed means call enrich again, and missing with nothing processing means enrichment was never started for it.

Show child attributes

modules

object | null

Per-module statuses. Deep reports only; null on free runs.

Show child attributes

reportUrl

string<uri> | null

Null until the report row exists.

API Reference

Endpoints

Poll an analysis

Authorizations

Path Parameters

Response