> ## Documentation Index
> Fetch the complete documentation index at: https://docs.weflayr.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Set key metrics

> Book key-metric values per user and month.

Key metrics belong to an [internal project](/product/organizations-and-projects#internal-projects). On a revenue-linked project, use the [Revenue API](/api/management/set-revenue) instead.

A user can have several lines of the same metric in the same month (they add up):

## Parameters

<ParamField body="rows" type="array of row objects" required>
  The key-metric lines to book, described below. Up to 1,000 per call.
</ParamField>

<ParamField body="upsert" type="boolean" default="false">
  If a row's `metric_id` already exists (c.f. `rows` parameters below), overwrite it instead of throwing an error.
</ParamField>

Each object inside `rows` accepts:

<ParamField body="user_name" type="string" required>
  The user the value belongs to.
</ParamField>

<ParamField body="metric_name" type="string" required>
  Name of the key metric. The first time you post a new one, it's automatically added to the project's key metrics.
</ParamField>

<ParamField body="amount" type="number" required>
  The value to book.
</ParamField>

<ParamField body="month" type="&#x22;YYYY-MM&#x22;">
  The calendar month the value belongs to. Required unless you set `month_start` and `month_end` instead.
</ParamField>

<ParamField body="month_start, month_end" type="&#x22;YYYY-MM&#x22;">
  Bill over a multi-month period (e.g. quarterly) instead of a single `month`. `amount` is split evenly over the period. Set either `month`, or both `month_start` and `month_end`, never both forms on the same row.
</ParamField>

<ParamField body="metric_id" type="string">
  An id for the key-metric row over which uniqueness is checked, typically from your own tracking system.
</ParamField>

<Note>
  API values are their own key-metric source, alongside CSV uploads. Sources add up: if you post a value for a user-month that also has a CSV upload, Weflayr assumes it is the sum. We recommend using one source only to avoid double counting.
</Note>

<RequestExample>
  ```python Python theme={null}
  import weflayr
  from weflayr.openapi.models import SetKeyMetricsInput

  client = weflayr.client()  # reads WEFLAYR_API_KEY

  client.set_key_metrics(body=SetKeyMetricsInput.from_dict({
      "rows": [
          {"user_name": "u_123", "metric_name": "Meetings booked", "amount": 3, "month": "2026-06"},
          {"user_name": "u_456", "metric_name": "Meetings booked", "amount": 7, "month": "2026-06"},
      ]
  }))
  ```

  ```js Node.js theme={null}
  const weflayr = require('weflayr');

  const client = weflayr.client(); // reads WEFLAYR_API_KEY

  await weflayr.api.setKeyMetrics({
    client,
    throwOnError: true,
    body: {
      rows: [
        { userName: 'u_123', metricName: 'Meetings booked', amount: 3, month: '2026-06' },
        { userName: 'u_456', metricName: 'Meetings booked', amount: 7, month: '2026-06' },
      ],
    },
  });
  ```

  ```bash cURL theme={null}
  curl -X POST https://app.weflayr.com/api/key-metrics/ \
    -H "Authorization: Bearer $WEFLAYR_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "rows": [
        {"user_name": "u_123", "metric_name": "Meetings booked", "amount": 3, "month": "2026-06"},
        {"user_name": "u_456", "metric_name": "Meetings booked", "amount": 7, "month": "2026-06"}
      ]
    }'
  ```
</RequestExample>

<ResponseExample>
  ```json 200 theme={null}
  {"ok": true, "rows_inserted": 2}
  ```
</ResponseExample>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.