# Metric

URL: /business/nouns/metric · Id: `noun:metric`

> A Metric is a named measure computed from Events or Entries, always derived and never typed in.

A Metric is a named measure computed from [Events](/business/nouns/event) or [Entries](/business/nouns/entry), always derived and never typed in. [Key Results](/business/nouns/key-result), [Experiments](/business/nouns/experiment) and [Dashboards](/business/nouns/dashboard) read the same Metric, so one number means one thing.

## Properties
| Property | Type | Required | Description |
| --- | --- | --- | --- |
| `query` | `text` | Yes | How it is computed. An agent never varies the Metrics it is judged by. Never randomized. |
| `unit` | `string` | No | The unit, such as dollars or percent. |
| `status` | `string` | Yes | One of `draft` or `defined`. |

## Object
```json
{
  "$id": "https://api.sb/kilnbakery.com/metrics/metric_1",
  "$type": "Metric",
  "query": "Example query",
  "unit": "Example unit",
  "status": "draft"
}
```

## Relationships
- <a id="rel-computed-from"></a>A Metric **is computed from** many [Events](/business/nouns/event): a Metric derives from [Events](/business/nouns/event) and is never typed in. `computedFrom`, inverse [`feeds`](/business/nouns/event#rel-feeds).
- <a id="rel-computed-under"></a>A Metric **is computed under** many [Policies](/business/nouns/policy): a [Policy](/business/nouns/policy) rules how Metrics are computed, such as revenue under revenue recognition. `computedUnder`, inverse [`computes`](/business/nouns/policy#rel-computes).
- <a id="rel-informed-by"></a>A Metric **is informed by** many [Surveys](/business/nouns/survey): [Survey](/business/nouns/survey) answers compute Metrics, such as a satisfaction score. `informedBy`, inverse [`informs`](/business/nouns/survey#rel-informs).
- <a id="rel-measured-by"></a>A Metric **is measured by** many [Experiments](/business/nouns/experiment): one primary Metric judges an [Experiment](/business/nouns/experiment)’s [Variants](/business/nouns/variant); guardrail Metrics stop it. `measuredBy`, inverse [`measures`](/business/nouns/experiment#rel-measures).
- <a id="rel-moved-by"></a>A Metric **is moved by** many [Plays](/business/nouns/play): a [Play](/business/nouns/play) exists to move named Metrics, read before and after every run. `movedBy`, inverse [`moves`](/business/nouns/play#rel-moves).
- <a id="rel-read-by"></a>A Metric **read by** many [Key Results](/business/nouns/key-result): a [Key Result](/business/nouns/key-result) compares one Metric’s value against its baseline and target. `readBy`, inverse [`reads`](/business/nouns/key-result#rel-reads).
- <a id="rel-shown-on"></a>A Metric **is shown on** many [Dashboards](/business/nouns/dashboard): a [Dashboard](/business/nouns/dashboard) reads out Metrics, each computed from [Events](/business/nouns/event) and never typed in. `shownOn`, inverse [`shows`](/business/nouns/dashboard#rel-shows).

## Lifecycle

| State | Meaning | Moves to |
| --- | --- | --- |
| `draft` (first) | Its query is written and not compiled, so nothing reads it. | `defined` by [Metric.define](/business/nouns/metric/define) |
| `defined` | Its query compiles against the Startup’s Events and Entries; defining it again recompiles an edited query. | None: it ends here. |

## Verbs
| Verb | Description | Subject | Event | Class |
| --- | --- | --- | --- | --- |
| [Metric.define](/business/nouns/metric/define) | Define compiles a Metric’s query against the Startup’s Events and Entries and lists every Event it reads. | [Analyst](/agents/marketing/analyst) | [`Metric.defined`](/business/events/Metric.defined) | Two-way: `try`, `send`, `do` |
| [Metric.query](/business/nouns/metric/query) | Query reads Metrics or Events as a trend, funnel, retention curve, path or lifecycle, broken down by any property. | [Analyst](/agents/marketing/analyst) | [`Metric.queried`](/business/events/Metric.queried) | Two-way: `try`, `send`, `do` |
| [Metric.watch](/business/nouns/metric/watch) | Watch alerts the owner of a Metric when it crosses a threshold, by a Task or a Message. | [Analyst](/agents/marketing/analyst) | [`Metric.watched`](/business/events/Metric.watched) | Two-way: `try`, `send`, `do` |
| <a id="create"></a>[Metric.create](/business/nouns/metric/create) | Creates a Metric. Inherited from [Noun](/business/nouns/noun). | None. | `Metric.created` | Two-way: `try`, `send`, `do` |
| <a id="get"></a>[Metric.get](/business/nouns/metric/get) | Returns one Metric by id. Inherited from [Noun](/business/nouns/noun). | None. | None. | Read: `try`, `do` |
| <a id="list"></a>[Metric.list](/business/nouns/metric/list) | Returns Metrics, newest first, one page at a time. Inherited from [Noun](/business/nouns/noun). | None. | None. | Read: `try`, `do` |
| <a id="update"></a>[Metric.update](/business/nouns/metric/update) | Changes the given properties of a Metric. Inherited from [Noun](/business/nouns/noun). | None. | `Metric.updated` | Two-way: `try`, `send`, `do` |
| <a id="delete"></a>[Metric.delete](/business/nouns/metric/delete) | Deletes a Metric; its history is kept. Inherited from [Noun](/business/nouns/noun). | None. | `Metric.deleted` | One-way: `send`, `do` |

## Permissions
Which Access level may call each Verb. One-way Verbs wait their delay window.

| Operation | `owner` | `admin` | `member` | `viewer` |
| --- | --- | --- | --- | --- |
| `Metric.create` | Yes | Yes | Yes | No |
| `Metric.get` | Yes | Yes | Yes | Yes |
| `Metric.list` | Yes | Yes | Yes | Yes |
| `Metric.update` | Yes | Yes | Yes | No |
| `Metric.delete` | Yes | Yes | Yes | No |
| `Metric.define` | Yes | Yes | Yes | No |
| `Metric.query` | Yes | Yes | Yes | No |
| `Metric.watch` | Yes | Yes | Yes | No |

## Call it

**Ask**

```text
Define the latest metric.
```

**API**

```bash
curl -X POST https://api.sb/ledgerlark.com/metrics/define \
  -H "Authorization: Bearer $STARTUP_BUILDER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name":"LedgerLark","query":"Example query","unit":"Example unit"}'
```

```json
{
  "api": "https://api.sb/ledgerlark.com",
  "metric": {
    "$id": "https://api.sb/ledgerlark.com/metrics/metric_1",
    "$type": "Metric",
    "query": "Example query",
    "status": "draft"
  },
  "action": {
    "$id": "https://api.sb/ledgerlark.com/actions/action_1",
    "operation": "Metric.define",
    "status": "done"
  },
  "links": {
    "self": "https://api.sb/ledgerlark.com/actions/action_1"
  }
}
```

**SDK**

```ts
import { $ } from 'startup-builder'

const metric = await $.Metric.define({ name: 'LedgerLark', query: 'Example query', unit: 'Example unit' })
```

**CLI**

```bash
npx startup-builder do Metric.define --json '{"name":"LedgerLark","query":"Example query","unit":"Example unit"}'
```

**MCP**

```json
{
  "name": "do",
  "arguments": {
    "code": "return await $.Metric.define({ name: 'LedgerLark', query: 'Example query', unit: 'Example unit' })"
  }
}
```

## Example
Monthly recurring revenue is a Metric whose `query` sums active [Subscription](/business/nouns/subscription) Entries, with `unit: USD`. A pricing Experiment, the revenue Dashboard and the annual Key Result all read that one value.