---
title: "Prepare an owned structured investigation handoff"
method: GET
path: "/api/v1/intelligence/runs/{runId}/handoff"
tags: ["Property Intelligence"]
---

# Prepare an owned structured investigation handoff

`GET /api/v1/intelligence/runs/{runId}/handoff`

## Request

- Base URL: `https://propraven.com`
- URL: `https://propraven.com/api/v1/intelligence/runs/{runId}/handoff`
- Auth: HTTP bearer

Requires API-key or first-party session authentication and a current account in the default-off server cohort. Valid current membership does not require a new paid subscription. Existing API quotas still apply. Responses are private, no-store. Unknown and repeated query parameters are rejected. This contract does not indicate source activation, deployment or an SDK release. Retained objects are scoped to the current account and their creator; no caller-supplied account/user grant is accepted. Current source rights are checked for every read/use, independently of archived grants. Returns the same retained calculations, evidence and optional saved scenario, with observations separated from user assumptions. The scenario must belong to the same run/creator. Delivery is structured_only_not_sent; no agent/model is started.

## Path parameters

- `runId` string, required

## Query parameters

- `use` 'display' | 'export' | 'ai'
- `scenario_id` string

## Response `200`

Authorized result; unavailable/partial/stale states are explicit within the response. No live coverage is implied by this contract.

- IntelligenceHandoff: Authorized retained results and optional user scenario; structured_only_not_sent. No model call, external delivery or duplicate arithmetic.
  - `version` 'investigation-handoff@1', required
  - `canonical_id` string, required
  - `run_id` string, required
  - `query` object, required
    - `as_of` string, required
    - `knowledge_cutoff` string, required
  - `observations` object[], required
    - `evidence_id` string, required
    - `source_product` string, required
    - `source_version` string, required
    - `vintage` string, required
    - `source_as_of` string, nullable, required
    - `observed_at` string, nullable, required
    - `captured_at` string, required
    - `knowledge_basis` string, required
    - `effective_time_basis` string, required
    - `source_url` string, nullable, required
  - `computed_results` object, required
    - `market` object[], required
      - `definition` string, required
      - `status` 'available' | 'partial' | 'insufficient_data' | 'unavailable' | 'stale' | 'error', required
      - `reasons` string[], required
      - `metrics` object, required
      - `counts` object, required
      - `exclusions` object, required
      - `evidence_ids` string[], required
      - `context` object, required
        - `input_kind` 'observed' | 'user_assumptions' | 'unavailable', required
        - `requested_scope` object, nullable, required
          - `geography` string, required
          - `property_type` string, required
          - `currency` string, required
        - `actual_scope` object, nullable, required
          - `geography` string, required
          - `property_type` string, required
          - `currency` string, required
        - `query` object, nullable, required
          - `as_of` string, required
          - `knowledge_cutoff` string, required
        - `period` union, required
          - object
            - `kind` 'window', required
            - `window` object, required
              - …
          - object
            - `kind` 'snapshot', required
            - `at` string, required
          - object
            - `kind` 'comparison', required
            - `current` object, required
              - …
            - `previous` object, required
              - …
          - object
            - `kind` 'stock_flow', required
            - `snapshot_at` string, required
            - `flow` object, required
              - …
        - `metric_periods` object, required
        - `latest_observation_at` string, nullable, required
        - `source_as_of` string, nullable, required
        - `source_vintage` string, nullable, required
        - `history_complete` boolean, nullable, required
    - `seller` object[], required
      - `definition` string, required
      - `status` 'available' | 'partial' | 'insufficient_data' | 'unavailable' | 'stale' | 'error', required
      - `reasons` string[], required
      - `metrics` object, required
      - `counts` object, required
      - `exclusions` object, required
      - `evidence_ids` string[], required
      - `context` object, required
        - `input_kind` 'observed' | 'user_assumptions' | 'unavailable', required
        - `requested_scope` object, nullable, required
          - `geography` string, required
          - `property_type` string, required
          - `currency` string, required
        - `actual_scope` object, nullable, required
          - `geography` string, required
          - `property_type` string, required
          - `currency` string, required
        - `query` object, nullable, required
          - `as_of` string, required
          - `knowledge_cutoff` string, required
        - `period` union, required
          - object
            - `kind` 'window', required
            - `window` object, required
              - …
          - object
            - `kind` 'snapshot', required
            - `at` string, required
          - object
            - `kind` 'comparison', required
            - `current` object, required
              - …
            - `previous` object, required
              - …
          - object
            - `kind` 'stock_flow', required
            - `snapshot_at` string, required
            - `flow` object, required
              - …
        - `metric_periods` object, required
        - `latest_observation_at` string, nullable, required
        - `source_as_of` string, nullable, required
        - `source_vintage` string, nullable, required
        - `history_complete` boolean, nullable, required
    - `owner` object[], required
      - `definition` string, required
      - `status` 'available' | 'partial' | 'insufficient_data' | 'unavailable' | 'stale' | 'error', required
      - `reasons` string[], required
      - `metrics` object, required
      - `counts` object, required
      - `exclusions` object, required
      - `evidence_ids` string[], required
      - `context` object, required
        - `input_kind` 'observed' | 'user_assumptions' | 'unavailable', required
        - `requested_scope` object, nullable, required
          - `geography` string, required
          - `property_type` string, required
          - `currency` string, required
        - `actual_scope` object, nullable, required
          - `geography` string, required
          - `property_type` string, required
          - `currency` string, required
        - `query` object, nullable, required
          - `as_of` string, required
          - `knowledge_cutoff` string, required
        - `period` union, required
          - object
            - `kind` 'window', required
            - `window` object, required
              - …
          - object
            - `kind` 'snapshot', required
            - `at` string, required
          - object
            - `kind` 'comparison', required
            - `current` object, required
              - …
            - `previous` object, required
              - …
          - object
            - `kind` 'stock_flow', required
            - `snapshot_at` string, required
            - `flow` object, required
              - …
        - `metric_periods` object, required
        - `latest_observation_at` string, nullable, required
        - `source_as_of` string, nullable, required
        - `source_vintage` string, nullable, required
        - `history_complete` boolean, nullable, required
    - `redevelopment` object[], required
      - `definition` string, required
      - `status` 'available' | 'partial' | 'insufficient_data' | 'unavailable' | 'stale' | 'error', required
      - `reasons` string[], required
      - `metrics` object, required
      - `counts` object, required
      - `exclusions` object, required
      - `evidence_ids` string[], required
      - `context` object, required
        - `input_kind` 'observed' | 'user_assumptions' | 'unavailable', required
        - `requested_scope` object, nullable, required
          - `geography` string, required
          - `property_type` string, required
          - `currency` string, required
        - `actual_scope` object, nullable, required
          - `geography` string, required
          - `property_type` string, required
          - `currency` string, required
        - `query` object, nullable, required
          - `as_of` string, required
          - `knowledge_cutoff` string, required
        - `period` union, required
          - object
            - `kind` 'window', required
            - `window` object, required
              - …
          - object
            - `kind` 'snapshot', required
            - `at` string, required
          - object
            - `kind` 'comparison', required
            - `current` object, required
              - …
            - `previous` object, required
              - …
          - object
            - `kind` 'stock_flow', required
            - `snapshot_at` string, required
            - `flow` object, required
              - …
        - `metric_periods` object, required
        - `latest_observation_at` string, nullable, required
        - `source_as_of` string, nullable, required
        - `source_vintage` string, nullable, required
        - `history_complete` boolean, nullable, required
  - `user_assumptions` object, nullable, required
    - `id` string, required
    - `run_id` string, required
    - `parent_revision_id` string, nullable, required
    - `label` 'base' | 'downside' | 'upside', required
    - `created_at` string, required
    - `assumptions` object, required
    - `result` object, required
      - `definition` string, required
      - `status` 'available' | 'partial' | 'insufficient_data' | 'unavailable' | 'stale' | 'error', required
      - `reasons` string[], required
      - `metrics` object, required
      - `counts` object, required
      - `exclusions` object, required
      - `evidence_ids` string[], required
      - `context` object, required
        - `input_kind` 'observed' | 'user_assumptions' | 'unavailable', required
        - `requested_scope` object, nullable, required
          - `geography` string, required
          - `property_type` string, required
          - `currency` string, required
        - `actual_scope` object, nullable, required
          - `geography` string, required
          - `property_type` string, required
          - `currency` string, required
        - `query` object, nullable, required
          - `as_of` string, required
          - `knowledge_cutoff` string, required
        - `period` union, required
          - object
            - `kind` 'window', required
            - `window` object, required
              - …
          - object
            - `kind` 'snapshot', required
            - `at` string, required
          - object
            - `kind` 'comparison', required
            - `current` object, required
              - …
            - `previous` object, required
              - …
          - object
            - `kind` 'stock_flow', required
            - `snapshot_at` string, required
            - `flow` object, required
              - …
        - `metric_periods` object, required
        - `latest_observation_at` string, nullable, required
        - `source_as_of` string, nullable, required
        - `source_vintage` string, nullable, required
        - `history_complete` boolean, nullable, required
  - `interpretations` string[], required
  - `next_diligence` string[], required
  - `delivery` 'structured_only_not_sent', required

## Other responses

- `400`: Invalid, unknown or duplicate parameters; invalid time, source key or scenario assumptions.
- `401`: Authentication required, or supplied credential invalid. A rejected bearer does not fall back to a session.
- `402`: Existing API-key monthly quota exceeded; this feature adds no paid SKU.
- `403`: Current source rights do not permit the requested retained Intelligence use.
- `404`: Feature disabled, current account outside cohort, or requested retained object/parcel unavailable. Other creators' objects are not disclosed.
- `429`: Existing API or concurrent-request limit exceeded.
- `500`: Unexpected service failure; internal details are withheld.
- `504`: Database query timeout.

---

[API](https://skmtc.dev/propraven/apis/propraven-api.md) · [All operations](https://skmtc.dev/propraven/apis/propraven-api/llms.txt) · [OpenAPI document](https://skmtc.dev/propraven/apis/propraven-api/revisions/37f8158c4eda?raw)