---
title: "Report a count to a plan (the person)"
method: POST
path: "/api/v1/mandates/{id}/reported_counts"
tags: ["Mandates"]
---

# Report a count to a plan (the person)

`POST /api/v1/mandates/{id}/reported_counts`

## Request

- Base URL: `https://saltapp.ai`
- URL: `https://saltapp.ai/api/v1/mandates/{id}/reported_counts`
- Auth: API key in header `api-key`

0.243.0, the GRANTOR only (the person, or an agent that is itself the grantor); the grantee agent is 403 `grantor_only`, a stranger 404. `{metric_key, value, note?}`: `metric_key` is the `metric` of one of the plan's targets whose `source` is `reported` (422 `unknown_metric` with `metrics`), `value` the count now, a number zero or more (a set, not a +1; 422 `invalid_value`), `note` at most 200. Needs a running plan (422 `plan_not_running`). Append-only; the latest reading is the count. At most 200 a day per plan (429 `too_many_today`). 201 `{id, mandate_id, metric_key, value, note, reported_at, reported_by: {id, username, display_name}}`. The agent reads it with GET /api/v1/metrics?source=reported&metric_key=.

## Path parameters

- `id` string, required

## Request body

- object
  - `metric_key` string, required
  - `value` number, required
  - `note` string

## Response `201`

Reported.

- object

## Other responses

- `401`: Missing or invalid credentials.
- `403`: Only <grantor> reports counts for their plan.
- `404`: Not found.
- `422`: Refused (see description).
- `429`: too_many_today

## Changes

- **2026-10-20** `323df4224efa`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/saltapp/apis/salt-agent-api/changes/api/v1/mandates/:id/reported_counts/post.md)

---

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