Retrieve an underwriting run (poll for status)

curl --request GET \
  --url https://api.trycactus.com/v1/underwritings/{underwriting_id} \
  --header 'Authorization: Bearer <token>'

import requests

url = "https://api.trycactus.com/v1/underwritings/{underwriting_id}"

headers = {"Authorization": "Bearer <token>"}

response = requests.get(url, headers=headers)

print(response.text)

const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};

fetch('https://api.trycactus.com/v1/underwritings/{underwriting_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://api.trycactus.com/v1/underwritings/{underwriting_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 => [
    "Authorization: Bearer <token>"
  ],
]);

$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://api.trycactus.com/v1/underwritings/{underwriting_id}"

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

	req.Header.Add("Authorization", "Bearer <token>")

	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://api.trycactus.com/v1/underwritings/{underwriting_id}")

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

request = Net::HTTP::Get.new(url)
request["Authorization"] = 'Bearer <token>'

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

{
  "id": "uw_01J9ZK3M",
  "object": "underwriting",
  "status": "queued",
  "sandbox": true,
  "created_at": "2023-11-07T05:31:56Z",
  "progress": {
    "phase": "<string>",
    "stage": "<string>",
    "detail": "<string>"
  },
  "property": {},
  "end_user_ref": "<string>",
  "version": 123,
  "previous_underwriting_id": "<string>",
  "documents": [
    {
      "document_id": "<string>",
      "role": "rent_roll"
    }
  ],
  "options": {},
  "billed_total_usd": "<string>",
  "completed_at": "2023-11-07T05:31:56Z",
  "elapsed_seconds": 640,
  "poll_after_seconds": 30,
  "report": {
    "url": "<string>",
    "excel_url": "/v1/underwritings/uw_01J9ZK3M/model"
  },
  "summary": {},
  "results": {},
  "error": {
    "code": "<string>",
    "message": "<string>"
  }
}

Underwritings

Retrieve an underwriting run (poll for status)

Live runs take ~20-30 minutes; progress.phase tracks the coarse status and progress.stage the pipeline step behind it.

Pass wait to long-poll instead of sleeping between calls. While a run is active the response carries poll_after_seconds and a Retry-After header — use those rather than a fixed interval.

A completed run carries the whole report inline: both links, the headline summary, and the full results projection. This is the only place results is returned — list responses and webhook payloads omit it.

A run cannot exceed 4 hours; past that the worker fails it and refunds every billed line in full. A run the analyst could not resolve without a human fails with underwriting_needs_review and is likewise refunded.

GET

underwritings

{underwriting_id}

Retrieve an underwriting run (poll for status)

curl --request GET \
  --url https://api.trycactus.com/v1/underwritings/{underwriting_id} \
  --header 'Authorization: Bearer <token>'

import requests

url = "https://api.trycactus.com/v1/underwritings/{underwriting_id}"

headers = {"Authorization": "Bearer <token>"}

response = requests.get(url, headers=headers)

print(response.text)

const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};

fetch('https://api.trycactus.com/v1/underwritings/{underwriting_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://api.trycactus.com/v1/underwritings/{underwriting_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 => [
    "Authorization: Bearer <token>"
  ],
]);

$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://api.trycactus.com/v1/underwritings/{underwriting_id}"

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

	req.Header.Add("Authorization", "Bearer <token>")

	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://api.trycactus.com/v1/underwritings/{underwriting_id}")

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

request = Net::HTTP::Get.new(url)
request["Authorization"] = 'Bearer <token>'

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

{
  "id": "uw_01J9ZK3M",
  "object": "underwriting",
  "status": "queued",
  "sandbox": true,
  "created_at": "2023-11-07T05:31:56Z",
  "progress": {
    "phase": "<string>",
    "stage": "<string>",
    "detail": "<string>"
  },
  "property": {},
  "end_user_ref": "<string>",
  "version": 123,
  "previous_underwriting_id": "<string>",
  "documents": [
    {
      "document_id": "<string>",
      "role": "rent_roll"
    }
  ],
  "options": {},
  "billed_total_usd": "<string>",
  "completed_at": "2023-11-07T05:31:56Z",
  "elapsed_seconds": 640,
  "poll_after_seconds": 30,
  "report": {
    "url": "<string>",
    "excel_url": "/v1/underwritings/uw_01J9ZK3M/model"
  },
  "summary": {},
  "results": {},
  "error": {
    "code": "<string>",
    "message": "<string>"
  }
}

Authorizations

Authorization

string

header

required

Partner API key issued by Cactus.

Path Parameters

underwriting_id

string

required

Query Parameters

wait

integer

default:0

Seconds to hold the request open waiting for the job to reach a terminal state (long polling). 0 (the default) returns the current state immediately.

The response returns as soon as the job completes or fails, so a short job costs one request instead of a sleep loop. If the budget runs out first the request still returns 200 with the job's current state — a still-running job is not an error. Check status and call again.

Capped at 45 seconds, below the 60-second request timeout.

Required range: 0 <= x <= 45

Response

Current run state; report link and summary when complete.

string

required

Example:

"uw_01J9ZK3M"

object

string

required

Allowed value: "underwriting"

status

enum<string>

required

queued → ingesting (reading the documents and the market) → underwriting (analysis) → calculating (the financial model) → completed. progress.stage carries the finer-grained pipeline step behind each.

Available options:

queued,

ingesting,

underwriting,

calculating,

completed,

failed

sandbox

boolean

required

created_at

string<date-time>

required

progress

object

Show child attributes

property

object

Echo of the submitted property.

end_user_ref

string

Echo of the submitted end-user identifier, when one was supplied.

version

integer

Report version. 1 for a first run; a confirmed change creates a new underwriting with the next number.

previous_underwriting_id

string

The version this one changed (absent on version 1).

documents

object[]

Echo of the submitted selection, with each role settled.

Show child attributes

options

object

Echo of the submitted options, with defaults applied.

billed_total_usd

string

completed_at

string<date-time>

elapsed_seconds

integer

Whole seconds since created_at. Present while the run is active, so a caller can tell a run that just started from one approaching the 4-hour ceiling without doing date math.

Example:

640

poll_after_seconds

integer

Recommended seconds to wait before polling again. Present while the run is active; mirrors the Retry-After header. Prefer this over a hard-coded interval.

Example:

30

report

object

Present when completed. Private delivery omits url.

Show child attributes

summary

object

Headline metrics as plain numbers, lifted out of results for convenience: value_base_usd, cap_rate, normalized_noi_usd, levered_irr, dscr, equity_multiple, total_units and so on, plus readiness_status and disclosure_count.

A metric the run could not establish is absent, never null — the reason it is missing is in results, beside the figure.

results

object

The whole report, in the same shape the public report page is rendered from (broker-public-underwriting-delivery-v1). Present on a completed run when fetched individually; omitted from list responses and webhook payloads, which would otherwise carry megabytes.

Every figure is a {state, value, reason} triple, because the product distinguishes a known zero from something it could not establish. state is one of known, zero, unavailable, not_applicable; when it is not known or zero, value is null and reason says why in a sentence you can show a user. Collections carry {state, items, reason}, where state is available, partial, confirmed_empty or unavailable — "we found none" and "we could not look" are different answers.

Top level: schema_version, generated_at, property, chapters, critical_assumptions, readiness, release.

The chapters follow the argument the report makes: answer (what it is worth, and the cap rate and NOI behind that), income (unit mix and rent comparables), revenue (the trailing-twelve income statement and the year-one revenue waterfall), cost (the expense statement and the normalizations applied to it), value (sale comparables and a cap-rate sensitivity grid), buyer (returns, financing and the annual cash-flow table), risk (market watch), next (talking points).

readiness.disclosures is the part to surface next to any figure you quote: each names something the run had to assume or could not establish, with copy written to be shown to an end user. critical_assumptions.items ranks the assumptions the valuation is most sensitive to, with the dollar and IRR impact of moving each.

error

object

Show child attributes

Documents

Extractions

Underwritings

Usage

Webhook Endpoints

API Reference

Retrieve an underwriting run (poll for status)

Authorizations

Path Parameters

Query Parameters

Response