---
title: "Get complete user state"
method: GET
path: "/api/user/state"
---

# Get complete user state

`GET /api/user/state`

## Request

- Base URL: `https://app.rightmoney.com`
- URL: `https://app.rightmoney.com/api/user/state`
- Auth: API key in header `X-RM-Agent-Key`

Returns the canonical, complete picture of a user's Right Money system — financial breakdown, health score, classification status, account info, and next action. Replaces the need for multiple API calls.

## Query parameters

- `userId` string, uuid, required

## Response `200`

Complete user state

- UserStateResponse
  - `userId` string, uuid, required
  - `generatedAt` string, date-time, required
  - `financial` object, required
    - `income` object
      - `monthly_total` number
      - `sources` object[]
      - `confidence` number
    - `bills` object
      - `monthly_total` number
      - `percent_of_income` integer
      - `groups` object[]
        - `name` string
        - `monthly_amount` number
        - `items` string[]
      - `confidence` number
    - `lifestyle` object
      - `monthly_total` number
      - `percent_of_income` integer
      - `top_merchants` string[]
      - `confidence` number
    - `freedom` object
      - `monthly_total` number
      - `percent_of_income` integer
      - `total_savings` number
    - `months_of_freedom` object
      - `current` number
      - `trend` object[]
        - `month` string
        - `value` number
      - `target` number, nullable
  - `health` object, required
    - `score` integer
    - `label` string
    - `breakdown` object
    - `what_would_improve` object[]
      - `action` string
      - `score_gain` integer
  - `classification` object, required
    - `overall_confidence` number
    - `unconfirmed_count` integer
    - `db_coverage` number
    - `flagged_count` integer
    - `last_run` string, date-time, nullable
  - `account` object, required
    - `status` 'free' | 'trialing' | 'paid' | 'expired'
    - `source` string
    - `last_sync` string, date-time, nullable
    - `data_age_days` integer, nullable
    - `sync_enabled` boolean
    - `plaid_connections` integer
  - `next_action` object, required
    - `type` string
    - `label` string
    - `subtitle` string
    - `url` string, uri
    - `priority` integer
  - `snapshot_url` string, uri

## Other responses

- `400`: Invalid request
- `401`: Invalid or missing API key
- `503`: Database not configured

---

[API](https://skmtc.dev/rightmoney/apis/right-money-agent-api.md) · [All operations](https://skmtc.dev/rightmoney/apis/right-money-agent-api/llms.txt) · [OpenAPI document](https://skmtc.dev/rightmoney/apis/right-money-agent-api/revisions/244b5180a5ff?raw)