# Index Observations

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

Source: https://www.lev.com/docs/build/index/observations

Last updated: 2026-09-16

---
### `POST /api/external/v2/deals/{deal_id}/index/observations`

List per-document candidate values behind a deal fact

#### Path Parameters

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `deal_id` | `integer` | Yes | The deal ID |

#### Request Body

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `sot_id` | `string` | No | 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_id` | `integer` | No | Numeric metric definition id (> 0). Use when fetching every observation for a metric across entities. |
| `entity_ref` | `string` | No | Optional entity scoping (e.g. property:690). Intended for use with metric_id; combining with sot_id has no additional effect. |
| `page` | `integer` | No | 1-based page number. Defaults to 1. |
| `limit` | `integer` | No | Observations per page. Defaults to 20 and is clamped to 1-200. |
| `include_signed_urls` | `boolean` | No | When true, document-backed source records may include short-lived signed URLs for inspection or download. |

Response: `200`

#### Error Responses

- **422** (validation_error): Provide at least one of sot_id or metric_id
- **401** (unauthorized): Authentication required
- **404** (not_found): Deal not found
- **503** (service_unavailable): Deal observations are temporarily unavailable. Please try again shortly.