Key metrics

Manage the key-metric values of an internal project programmatically instead of uploading CSVs. On a revenue-linked project, use the Revenue API instead.

import weflayr

client = weflayr.client(api_key="wf-...")

const weflayr = require('weflayr');

const client = weflayr.client({ apiKey: 'wf-...' });

# Passed as a Bearer token on every request
export WEFLAYR_API_KEY="wf-..."

Set key metrics

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

from weflayr.openapi.models import SetKeyMetricsInput

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"},
    ]
}))

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' },
    ],
  },
});

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"}
    ]
  }'

Output:

{"ok": true, "rows_inserted": 2}

Input params:

Field	Accepts	Behaviour
`rows` Required	array of row objects	The key-metric lines to book, described in the table below. Up to 1,000 per call.
`upsert` Optional	boolean (default `false`)	If a row’s `metric_id` already exists (c.f. `rows` parameters below), overwrite it instead of throwing an error.

Each object inside rows accepts:

Row field	Accepts	Behaviour
`user_name` Required	string	The user the value belongs to.
`metric_name` Required	string	Name of the key metric. The first time you post a new one, it’s automatically added to the project’s key metrics.
`amount` Required	number	The value to book.
`month` Required*	`"YYYY-MM"`	The calendar month the value belongs to.
`month_start`, `month_end` Required*	`"YYYY-MM"`	Bill over a multi-month period (e.g. quarterly) instead of a single `month`. `amount` is split evenly over the period.
`metric_id` Optional	String	An id for the key-metric row over which uniqueness is checked, typically from your own tracking system.

* Set either month, or both month_start and month_end, never both forms on the same row.

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.

Get key metrics

client.get_key_metrics(user_names=["u_123", "u_456"])

await weflayr.api.getKeyMetrics({
  client,
  throwOnError: true,
  query: { userNames: ['u_123', 'u_456'] },
});

curl "https://app.weflayr.com/api/key-metrics/?user_names=u_123&user_names=u_456" \
  -H "Authorization: Bearer $WEFLAYR_API_KEY"

Output:

{
  "rows": [
    {"metric_id": "b3f2b160-6e12-4f1a-9c3d-0a2e7c9b5d41", "user_name": "u_123", "metric_name": "Meetings booked", "month": "2026-06", "amount": 3.0, "source": "api"}
  ],
  "next_cursor": null,
  "has_more": false
}

Input params: passed in the query string.

Field	Accepts	Behaviour
`user_names` Optional	list[string]	Specify the names of the users whose key metrics should be fetched. Not setting it means “all users”.
`limit` Optional	integer (default `100`, max `1000`)	Numbers of rows to fetch.
`cursor` Optional	string	The route is paginated: pass the previous page’s `next_cursor` to fetch the next page. PS: `has_more` from the output says whether another page exists.

Delete key metrics

client.delete_key_metrics(user_names=["u_123", "u_456"])

await weflayr.api.deleteKeyMetrics({
  client,
  throwOnError: true,
  query: { userNames: ['u_123', 'u_456'] },
});

curl -X DELETE "https://app.weflayr.com/api/key-metrics/?user_names=u_123&user_names=u_456" \
  -H "Authorization: Bearer $WEFLAYR_API_KEY"

Output:

{"ok": true, "rows_deleted": 2}

Input params: passed in the query string.

Field	Accepts	Behaviour
`user_names` Required	list[string]	Delete all these users’ API-booked key metrics.
`month_start`, `month_end` Optional	`"YYYY-MM"`	Narrow the delete to this inclusive month range. Omit both to delete every API-booked value of the named users.

PS: CSV uploads are managed by their own source and cannot be deleted via this route