---
title: "One household, one picture"
method: GET
path: "/api/v1/households/{id}/picture"
tags: ["households"]
---

# One household, one picture

`GET /api/v1/households/{id}/picture`

## Request

- Base URL: `https://worthune.com`
- URL: `https://worthune.com/api/v1/households/{id}/picture`
- Auth: one of:
  - HTTP bearer
  - API key in header `X-Api-Key`

Balance sheet by wrapper and owner, income and spending this year, currency against the engine's spec, decision history and a data-quality report. A read: no meter stamp, sums only.

## Response `200`

The picture.

- HouseholdPicture
  - `ok` unknown, required
  - `pictureVersion` '0.1.0', required
  - `asOf` string, date-time, required
  - `household` object, required
    - `id` integer, required
    - `label` string, nullable, required
    - `advisorRef` string, nullable, required
    - `schemaVersion` string, required
    - `version` integer, required
    - `status` 'active' | 'archived', required
    - `createdAt` string, date-time, required
    - `updatedAt` string, date-time, required
  - `summary` HouseholdSummary, required: Sums only — no projection is computed by the picture.
    - `filingStatus` 'single' | 'married_joint', required
    - `state` string, nullable, required
    - `members` object[], required
      - `id` string, required
      - `relationship` string, required
      - `ageAtAsOf` integer, required
      - `sex` string, nullable, required
    - `balanceSheet` object, required
      - `assets` number, required
      - `assetsByWrapper` object, required
      - `assetsByOwner` object, required
      - `liabilities` number, required
      - `liabilitiesByKind` object, required
      - `netWorth` number, required
    - `income` object, required: Streams active in the asOf year, at their entered annual amounts (no growth applied).
      - `annualTotal` number, required
      - `byKind` object, required
      - `computedSocialSecurityStreams` integer, required
    - `expenses` object, required
      - `annualTotal` number, required
      - `byKind` object, required
    - `counts` object, required
      - `accounts` integer, required
      - `liabilities` integer, required
      - `incomes` integer, required
      - `expenses` integer, required
  - `currency` object, required
    - `lastComputedAt` string, date-time, nullable, required
    - `lastComputedSpecVersion` string, nullable, required
    - `currentProjectionSpecVersion` string, required
    - `drift` DriftReason[], required: Empty when the last computation is fresh and current.
      - `kind` 'never-computed' | 'stale' | 'spec-changed', required
      - `detail` string, required
  - `decisions` object, required
    - `count` integer, required
    - `latest` object[], required: Newest first.
      - `id` integer, required
      - `strategy` string, required
      - `strategySpecVersion` string, required
      - `householdVersion` integer, required
      - `recordSha256` string, required
      - `createdAt` string, date-time, required
  - `dataQuality` object, required
    - `score` integer, required
    - `checks` object[], required
      - `id` string, required
      - `level` 'ok' | 'warn' | 'info', required
      - `message` string, required
      - `path` string
      - `penalty` number, required
      - `unlocks` string
  - `links` object, required
    - `self` string, required
    - `document` string, required
    - `project` string, required
    - `decisions` string, required

## Other responses

- `400`: asOf is not a date.
- `401`: No key presented (Authorization: Bearer wk_… or X-Api-Key).
- `402`: Unrecognized or revoked API key.
- `403`: The key predates organization support (contact support for a free rotation).
- `404`: No household with this id in the key's organization (PUT, PATCH, POST project and POST decisions also answer 404 for archived rows; GET, the decision list and the picture still serve them).
- `429`: Hourly per-org stateful quota, a per-route durable limit, or the 120 requests/minute per-IP burst backstop.
- `503`: Billing is not configured on this deployment; household resources are disabled rather than served without tenancy (production fail-closed).

---

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