Build

Index Observations

List candidate observations — the per-document extractions behind a canonical deal fact — in the Lev API.

Updated September 2026

POST/api/external/v2/deals/{deal_id}/index/observations

List per-document candidate values behind a deal fact

Each canonical fact returned by Search Index may be backed by multiple observations — one per document our extractors pulled the value from. Use this endpoint to enumerate those observations after a search, then either:

show the user where a value came from (file, page range, confidence), or
pick an observation_id to promote via Update Index Fact so the canonical value keeps its document provenance.

Provide either sot_id (preferred — scopes to the exact fact behind a single search result) or metric_id (broader — returns observations for that metric across entities, optionally scoped by entity_ref). At least one is required.

Path parameters

deal_idintegerrequired

The deal ID

Request body

sot_idstring

Prefixed SOT id from a search result (e.g. d:5362, a:123:property:690). At least one of sot_id or metric_id is required.

metric_idinteger

Numeric metric definition id (> 0). Use when fetching every observation for a metric across entities.

entity_refstring

Optional entity scoping (e.g. property:690). Intended for use with metric_id; combining with sot_id has no additional effect.

pageinteger

1-based page number. Defaults to 1.

limitinteger

Observations per page. Defaults to 20 and is clamped to 1-200.

include_signed_urlsboolean

When true, document-backed source records may include short-lived signed URLs for inspection or download.

curl -X POST "https://api.lev.com/api/external/v2/deals/101/index/observations" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "sot_id": "d:5362",
    "limit": 20,
    "include_signed_urls": false
  }'

Response (200):

{
  "request_id": "d4e5f6a7-b8c9-0123-defa-234567890123",
  "timestamp": "2026-05-12T17:45:30Z",
  "data": [
    {
      "id": 9012,
      "metric_key": "deal_financials.in_place_noi",
      "metric_id": 42,
      "value_text": "$1,250,000",
      "value_type": "currency",
      "original_text": "In-place NOI of $1,250,000 as of T-12",
      "context": "Page 3 of the appraisal reports trailing twelve month NOI.",
      "summary": "In-place NOI is $1.25M based on the appraisal.",
      "period_type": "point_in_time",
      "period_value": null,
      "entity_type": "deal",
      "entity_id": null,
      "entity_ref": "deal:101",
      "group_ref": null,
      "category_id": 5,
      "confidence": 0.91,
      "weight": 10,
      "source": {
        "type": "document",
        "document_id": 99,
        "document_type": "appraisal",
        "file_name": "appraisal.pdf",
        "file_extension": ".pdf",
        "pages": [3],
        "observation_count": 1,
        "signed_url": null
      }
    }
  ],
  "pagination": {
    "total": 3,
    "limit": 20,
    "offset": 0,
    "has_more": false
  }
}

When include_signed_urls=true, document-backed results may include source.signed_url. Signing failures are non-fatal and follow the same source.signed_url_error convention as Search Index.

422validation_error

Provide at least one of sot_id or metric_id— The request body omits both sot_id and metric_id

401unauthorized

Authentication required— Missing or invalid Authorization header

404not_found

Deal not found— The deal_id doesn't exist or isn't accessible to the authenticated user

503service_unavailable

Deal observations are temporarily unavailable. Please try again shortly.— The indexed-data service is unavailable