---
title: "Connection & freshness status"
method: GET
path: "/v1/users/{user_id}/status"
tags: ["Integrations"]
---

# Connection & freshness status

`GET /v1/users/{user_id}/status`

## Request

- Base URL: `http://0.0.0.0:3000`
- URL: `http://0.0.0.0:3000/v1/users/{user_id}/status`
- Auth: none declared

Returns one rollup read on whether the user's connected sources are current: `fresh`, `catching_up`, `needs_you`, or `not_connected`.

`needs_you` means *connection health* requires a human (reconnect or grant a missing permission) — it is unrelated to the dashboard's "Needs you" panel, which tracks goal catches, not integration freshness.

## Path parameters

- `user_id` string, uuid, required

## Response `200`

Default Response

- object
  - `success` boolean, required
  - `error` object
    - `code` string, required
    - `message` string, required
    - `details` unknown
  - `data` object
    - `state` 'fresh' | 'catching_up' | 'needs_you' | 'not_connected', required
    - `summary` string, required
    - `as_of` string, date-time, required
    - `needs_action` object[], required
      - `provider` string, required
      - `integration_id` string, required
      - `reason` 'reconnect' | 'scope_missing', required
      - `connect_url` string, required
    - `sources` object[], required
      - `provider` string, required
      - `integration_id` string, required
      - `identity` string, nullable
      - `access` string[], required
      - `state` 'fresh' | 'delayed' | 'stale' | 'rate_limited' | 'syncing' | 'connecting' | 'needs_reconnect' | 'scope_missing', required
      - `state_reason` 'auth_expired' | 'scope_missing' | 'rate_limited' | 'initial_backfill' | 'sync_delayed' | 'sync_stale' | 'provider_unavailable', nullable
      - `sync_mode` 'webhook' | 'polling', required
      - `cadence` object, required
        - `fresh_within_seconds` integer
        - `stale_after_seconds` integer
      - `last_successful_sync_at` string, nullable
      - `last_failed_sync_at` string, nullable
      - `last_error_code` string, nullable
      - `last_item_at` string, nullable
      - `coverage` object, required
        - `messages` integer
        - `meetings` integer
        - `events` integer
        - `since` string, nullable
      - `caveats` string[], required

## Other responses

- `403`: Default Response
- `500`: Default Response

---

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