> For the complete documentation index, see [llms.txt](https://docs.january.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.january.ai/rest-api/water-logs.md).

# Water logs

Record an end user's water intake and read it back as daily totals.

Each operation acts on one end user ([End-user identity](/rest-api/api-overview.md#end-user-identity)). Client-token scopes: `water_logs:write` to create or delete; `water_logs:read` to list.

## Units and limits

Send each amount as `{ "value": …, "unit": … }` in one of these units:

| Unit                    | Accepted value per log |
| ----------------------- | ---------------------- |
| `fl_oz`                 | 1–811.5                |
| `ml`                    | 30–24,000              |
| `cup` (US cup, 8 fl oz) | 0.1–101.4              |

* The minimums don't convert exactly into one another (1 fl oz is about 29.6 ml, below the 30 ml minimum), so send the unit the user entered.
* An end user's total is capped at 24 L (about 811 fl oz) per UTC calendar day of `created_at`, whatever offset you send. A log that would pass the cap fails with `400 daily_water_limit_exceeded`.
* `created_at` is when the water was consumed ([Days and timezones](/rest-api/api-overview.md#days-and-timezones)). Omit it to log the water now.
* A created log comes back in the unit it was sent in. Save its `id` to delete it later.
* The list returns one total per local calendar day between `start_date` and `end_date` (both inclusive, in `timezone`), oldest first, in the `unit` you ask for (required), rounded to one decimal place. Days with nothing logged are absent, and an empty list is a valid result.
* The list returns at most 100 days; when more match, you get the most recent 100, so move `end_date` back to read older days. `start_date` can be at most five years before today in `timezone`; an earlier date fails with `400 date_range_too_large`.
* Creating a log is not idempotent. Before you retry a create that timed out, list the day to check whether it was recorded, because a retry records the water twice and counts it twice toward the cap.
* Deleting is idempotent: an unknown or already-deleted log also returns `204`. A deleted amount no longer counts toward its day's cap.

{% openapi src="<https://partners.january.ai/v1.2/openapi.json>" path="/v1.2/water-logs" method="post" %}
<https://partners.january.ai/v1.2/openapi.json>
{% endopenapi %}

{% openapi src="<https://partners.january.ai/v1.2/openapi.json>" path="/v1.2/water-logs" method="get" %}
<https://partners.january.ai/v1.2/openapi.json>
{% endopenapi %}

{% openapi src="<https://partners.january.ai/v1.2/openapi.json>" path="/v1.2/water-logs/{log\_id}" method="delete" %}
<https://partners.january.ai/v1.2/openapi.json>
{% endopenapi %}