# Record numbers

record_readings sends numbers for metrics already defined, such as a day's revenue or signups.

## record_readings

`record_readings` records numbers for metrics that are already defined: a day's revenue, signups, or anything else a decision is measured by.

- Sending the same reading again is safe.
- To send numbers from a script instead of an AI tool, see [Send numbers to hosted ZeroWidth](https://zerowidth.ai/docs/hosted/send-numbers).
- A metric that isn't defined is refused, never created by `record_readings`. Define it first with `define_metric`: give a name and say which way is good, higher or lower. A name that already exists is left as it is. An admin can also define metrics in the console; self-hosted, metrics are defined from files or the command line. [Metrics](https://zerowidth.ai/docs/self-hosting/metrics)
- On hosted ZeroWidth, only admins' agents get `define_metric` and `record_readings`.
- If any reading in a call is wrong, none of the readings are kept.

| Input | What to send |
|---|---|
| `readings` | A list of readings. Required. |

Each reading:

| Field | What to send |
|---|---|
| `metric` | The id of a defined metric. Required. |
| `value` | The number. Required. |
| `date` | The day the number is for, such as 2026-10-29 |
| `at` | A full timestamp, in place of `date` |
| `labels` | Which part of the metric the number is for, such as `{"plan": "pro"}`. Works on any metric. |
| `key` | Makes sending again safe when a metric has more than one reading a day |