# Habits

> A client's habits and their progress against the goal, day by day or week by week.

Source: https://hubfit.com/developers/api/habits


A habit is something a coach asked a client to do each day or week, like 10,000 steps a day or meditating 3 times a week, with a goal the client logs against. A habit's progress is one row per day or week it ran, with what the client logged and whether it met the goal in force then. To compare clients' habits over a period, use `GET /client-summaries` with `include=habits`.

Endpoints:

- `GET /v1/clients/{clientId}/habits`: [List a client's habits](https://hubfit.com/developers/api/habits#list-client-habits)
- `GET /v1/habits/{habitId}/progress`: [List a habit's progress](https://hubfit.com/developers/api/habits#list-habit-progress)

## Habit object

### Attributes

- `id` (string): Its unique ID.
- `name` (string)
- `emoji` (string)
- `description` (string)
- `goal` (object)
  - `type` (enum): `numeric` when the client logs an amount (steps, litres), `completion` when they tick it off. Known values `numeric`, `completion`.
  - `value` (number, nullable): The amount to reach each period. For a `completion` habit, how many ticks (1 a day, or 1 to 7 a week).
  - `unit` (string, nullable): The unit the coach picked, like `steps`, `km` or `cups`. `null` for a `completion` habit.
  - `period` (enum): Whether the goal is for each day, each Monday-to-Sunday week, or each month. Known values `day`, `week`, `month`.
- `startDate` (date)
- `endDate` (date, nullable)
- `status` (enum): Against today in the client's timezone. Known values `upcoming`, `active`, `ended`.
- `createdAt` (timestamp): When it was created.

### Example

```json
{
  "id": "6ad6af3f8234ff3e82336c41",
  "name": "10,000 steps a day",
  "emoji": "🚶",
  "description": "Walk at least 10,000 steps every day.",
  "goal": {
    "type": "numeric",
    "value": 10000,
    "unit": "steps",
    "period": "day"
  },
  "startDate": "2026-03-02",
  "endDate": null,
  "status": "active",
  "createdAt": "2026-03-02T15:04:11.000Z"
}
```

## Habit progress object

### Attributes

- `startDate` (date): The period's first day; a week starts on a Monday.
- `endDate` (date): The period's last day. The same as `startDate` for a daily habit.
- `loggedValue` (number): What the client logged in the period. For a `completion` habit, how many days they ticked it.
- `goalValue` (number, nullable): The goal in force in the period, which may differ from the habit's current goal if the coach changed it since.
- `completed` (boolean): Whether the period met its goal, as the app records it.

### Example

```json
{
  "startDate": "2026-10-26",
  "endDate": "2026-10-26",
  "loggedValue": 9412,
  "goalValue": 10000,
  "completed": true
}
```

## List a client's habits

`GET https://api.hubfit.com/v1/clients/{clientId}/habits`

The habits the coach gave the client, newest first, each with its current goal and whether it's upcoming, active or ended. A client has no more than 25 (`MAX_HABITS_PER_CLIENT`), so they all come in one response, without paging; a client given more before that limit still gets every one. Empty if the coach turned habits off for the client. Requires `clients:read`.

### Path parameters

- `clientId` (string, required): The client's `id`.

### Returns

Every habit the client has.

### Example request

cURL:

```bash
curl https://api.hubfit.com/v1/clients/6ad6af41d3199442d31b2743/habits \
  -H "Authorization: Bearer $HUBFIT_API_KEY"
```

Node.js:

```javascript
const response = await fetch("https://api.hubfit.com/v1/clients/6ad6af41d3199442d31b2743/habits", {
  headers: {
    Authorization: `Bearer ${process.env.HUBFIT_API_KEY}`,
  },
});

const { data } = await response.json();
```

Python:

```python
import os
import requests

response = requests.get(
    "https://api.hubfit.com/v1/clients/6ad6af41d3199442d31b2743/habits",
    headers={"Authorization": f"Bearer {os.environ['HUBFIT_API_KEY']}"},
)

data = response.json()["data"]
```

### Example response (200 OK)

```json
{
  "data": [
    {
      "id": "6ad6af3f8234ff3e82336c41",
      "name": "10,000 steps a day",
      "emoji": "🚶",
      "description": "Walk at least 10,000 steps every day.",
      "goal": {
        "type": "numeric",
        "value": 10000,
        "unit": "steps",
        "period": "day"
      },
      "startDate": "2026-03-02",
      "endDate": null,
      "status": "active",
      "createdAt": "2026-03-02T15:04:11.000Z"
    }
  ]
}
```

## List a habit's progress

`GET https://api.hubfit.com/v1/habits/{habitId}/progress`

One row for each day (or Monday-to-Sunday week, or month, as the habit's goal is set) the habit was running, up to today, most recent first. Each has what the client logged in it, the goal in force then, and whether it was completed. Days or weeks the client logged nothing in are listed too. 404 if the coach turned habits off for the client. Requires `clients:read`.

### Path parameters

- `habitId` (string, required): A habit `id` from `GET /clients/{clientId}/habits`.

### Query parameters

- `startDate` (date): Only periods from the one this day falls in, as `YYYY-MM-DD`. Days are the client's own calendar days.
- `endDate` (date): Only periods up to the one this day falls in, as `YYYY-MM-DD`.
- `limit` (integer): How many results to return, from 1 to 100. Default `25`.
- `cursor` (string): The `nextCursor` from the previous page.

### Returns

A page of the habit's periods.

### Example request

cURL:

```bash
curl -G https://api.hubfit.com/v1/habits/6ad6af3f8234ff3e82336c41/progress \
  -H "Authorization: Bearer $HUBFIT_API_KEY" \
  -d startDate=2026-10-20 \
  -d endDate=2026-10-26
```

Node.js:

```javascript
const response = await fetch("https://api.hubfit.com/v1/habits/6ad6af3f8234ff3e82336c41/progress?startDate=2026-10-20&endDate=2026-10-26", {
  headers: {
    Authorization: `Bearer ${process.env.HUBFIT_API_KEY}`,
  },
});

const { data, nextCursor } = await response.json();
```

Python:

```python
import os
import requests

response = requests.get(
    "https://api.hubfit.com/v1/habits/6ad6af3f8234ff3e82336c41/progress",
    headers={"Authorization": f"Bearer {os.environ['HUBFIT_API_KEY']}"},
    params={
        "startDate": "2026-10-20",
        "endDate": "2026-10-26",
    },
)

page = response.json()
data, next_cursor = page["data"], page["nextCursor"]
```

### Example response (200 OK)

```json
{
  "data": [
    {
      "startDate": "2026-10-26",
      "endDate": "2026-10-26",
      "loggedValue": 9412,
      "goalValue": 10000,
      "completed": true
    }
  ],
  "nextCursor": "eyJpZCI6IjZhZDZhZjNmMjljNTk3ZjE1In0",
  "totalCount": 48
}
```