---
title: "List observations"
method: POST
path: "/v1/tools/betteroff_list_observations"
tags: ["tools"]
---

# List observations

`POST /v1/tools/betteroff_list_observations`

## Request

- Base URL: `https://api.betteroff.finance`
- URL: `https://api.betteroff.finance/v1/tools/betteroff_list_observations`
- Auth: one of:
  - OpenID Connect (`https://app.betteroff.finance/api/auth/.well-known/openid-configuration`, scopes: `accounts:read`, `networth:read`, `transactions:read`, `cashflow:read`, `investments:read`, `debts:read`)
  - HTTP bearer

Use this when the user asks about recorded financial findings and their status. Read recorded household financial findings and their status. Excludes insurance checklist findings. Does not refresh or dismiss findings.

## Request body

- object
  - `status` 'open' | 'snoozed' | 'dismissed' | 'resolved', nullable, required
  - `limit` integer, nullable, required
  - `before` object, nullable, required
    - `timestamp` string, date-time, required
    - `id` string, uuid, required

## Response `200`

Tool result

- union
  - object
    - `ok` false, required
    - `requestId` string
    - `error` string, required
    - `code` string, required
    - `retryable` boolean, required
    - `nextStep` string, required
    - `field` string
    - `missingInputs` object[]
      - `id` string, required
      - `name` string, required
      - `balanceMissing` boolean, required
      - `interestRateMissing` boolean, required
      - `minimumPaymentMissing` boolean, required
  - object
    - `ok` true, required
    - `requestId` string
    - `schemaVersion` '4', required
    - `data` object, required
      - `items` object[], required
        - `id` string, uuid, required
        - `source` string, required
        - `headline` string, required
        - `detail` string, required
        - `status` string, required
        - `statusReason` string, nullable, required
        - `method` string, required
        - `timesSeen` integer, required
        - `firstSeenAt` string, date-time, required
        - `lastSeenAt` string, date-time, required
        - `dismissedAt` string, date-time, nullable, required
        - `resolvedAt` string, date-time, nullable, required
        - `evidence` object[], required
          - `id` string
          - `label` string, required
          - `observedAt` string, required
      - `page` object, required
      - `warnings` string[], required
    - `currency` string, nullable, required
    - `timezone` string, required
    - `asOf` string, nullable, required
    - `revision` integer, required
    - `householdRevision` integer, required
    - `quality` object, required
      - `state` 'complete' | 'partial' | 'unavailable', required
      - `reasons` string[], required
    - `evidence` object[], required
      - `source` string, required
      - `id` string
      - `observedAt` string, nullable, required
    - `page` object, required
      - `returnedCount` integer, required
      - `totalCount` integer, nullable, required
      - `truncated` boolean, required
      - `nextCursor` Schema1, required (unresolved $ref)
    - `warnings` string[], required
    - `notes` string

## Other responses

- `400`: INVALID_INPUT (a missing, unknown, or invalid argument, named in `fields`), TOOL_CALL_REJECTED, or a body that is not JSON.
- `401`: AGENT_TOKEN_INVALID: the token is missing, expired, or revoked.
- `402`: AGENT_SUBSCRIPTION_INACTIVE or FEATURE_NOT_INCLUDED: needs BetterOff Core.
- `403`: INSUFFICIENT_SCOPE, ACCESS_DENIED, or AGENT_GRANT_REVOKED.
- `404`: TOOL_NOT_FOUND, or NOT_FOUND for a record the org does not have.
- `409`: CONFLICT: the record's state rules this call out. Read it again.
- `422`: INCOMPLETE_DATA or RESULT_TOO_LARGE. Narrow the request; don't retry as is.
- `429`: RATE_LIMITED. Retry after Retry-After seconds.
- `503`: DATA_UNAVAILABLE, DEPENDENCY_UNAVAILABLE (including the 25-second tool deadline), or AGENT_AUTHZ_UNAVAILABLE. Retryable.
- `default`: Problem details

---

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