# Metric methods: define, query, watch

URL: /code/sdk/metric/verbs · Id: `page:code/sdk/metric/verbs`

> The Metric Verbs define, query, watch as typed SDK methods, with inputs, result, refusals and an example.

Reference for [Metric](/business/nouns/metric), one group of [Metric methods](/code/sdk/metric).

### Metric.define
Define compiles a Metric’s query against the Startup’s Events and Entries and lists every Event it reads. [Verb page](/business/nouns/metric/define?interface=sdk).

```ts
interface MetricVerbs {
  define(input: MetricDefineInput, options?: SB.CallOptions): SB.Call<Metric>
}
```

Emits [`Metric.defined`](/business/events/Metric.defined).

**Inputs**

| Input | Type | Required | Description |
| --- | --- | --- | --- |
| `name` | `string` | Yes | The Metric’s name. |
| `query` | `text` | Yes | The query, over Events and Entries. |
| `unit` | `string` | Yes | What one unit of it is. |

**Returns**

| Output | Type | Required | Description |
| --- | --- | --- | --- |
| `metric` | [Metric](/business/nouns/metric) | Yes | The defined Metric. |

**Refuses when**

| Check | Error | Fix | Then call |
| --- | --- | --- | --- |
| The key is valid, but its scopes do not allow this operation. | [`forbidden`](/code/api/errors/forbidden) | Use a key whose scopes cover the operation, or ask an owner of the namespace to grant them. | None. |

**Example**

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

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

### Metric.query
Query reads Metrics or Events as a trend, funnel, retention curve, path or lifecycle, broken down by any property. [Verb page](/business/nouns/metric/query?interface=sdk).

```ts
interface MetricVerbs {
  query(input: MetricQueryInput, options?: SB.CallOptions): SB.Call<MetricQueryOutput>
}
```

Emits [`Metric.queried`](/business/events/Metric.queried).

**Inputs**

| Input | Type | Required | Description |
| --- | --- | --- | --- |
| `metric` | [Metric](/business/nouns/metric) | No | The Metric to read; omitted, the query names Events directly. |
| `shape` | `string` | Yes | The analysis to run. |
| `breakdown` | `string` | No | The property to split by, such as an Organization or a Motion. |
| `window` | `string` | No | The time range, such as `30d`. |

**Returns**

| Output | Type | Required | Description |
| --- | --- | --- | --- |
| `rows` | `json` | Yes | The result rows, each number with its readability. |
| `metric` | [Metric](/business/nouns/metric) | Yes | The Metric read. |

**Refuses when**

| Check | Error | Fix | Then call |
| --- | --- | --- | --- |
| The key is valid, but its scopes do not allow this operation. | [`forbidden`](/code/api/errors/forbidden) | Use a key whose scopes cover the operation, or ask an owner of the namespace to grant them. | None. |

**Example**

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

const { rows, metric } = await $.Metric.query({ shape: 'trend' })
```

### Metric.watch
Watch alerts the owner of a Metric when it crosses a threshold, by a Task or a Message. [Verb page](/business/nouns/metric/watch?interface=sdk).

```ts
interface MetricVerbs {
  watch(input: MetricWatchInput, options?: SB.CallOptions): SB.Call<MetricWatchOutput>
}
```

Emits [`Metric.watched`](/business/events/Metric.watched).

**Inputs**

| Input | Type | Required | Description |
| --- | --- | --- | --- |
| `metric` | [Metric](/business/nouns/metric) | Yes | The Metric to watch. |
| `threshold` | `number` | Yes | The value that trips it. |
| `direction` | `string` | Yes | Trip when the Metric goes above or below the threshold. |

**Returns**

| Output | Type | Required | Description |
| --- | --- | --- | --- |
| `watch` | [Watch](/business/nouns/watch) | Yes | The Watch that checks it. |
| `metric` | [Metric](/business/nouns/metric) | Yes | The Metric now watched. |

**Refuses when**

| Check | Error | Fix | Then call |
| --- | --- | --- | --- |
| The key is valid, but its scopes do not allow this operation. | [`forbidden`](/code/api/errors/forbidden) | Use a key whose scopes cover the operation, or ask an owner of the namespace to grant them. | None. |

**Example**

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

const { watch, metric } = await $.Metric.watch({ metric: 'metric_GXFHAlK100', threshold: 1, direction: 'above' })
```