# Metric routes: define, query, watch

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

> The Metric Verbs define, query, watch as api.sb routes, with inputs, result, refusals and an example.

Reference for [Metric](/business/nouns/metric), one group of [Metric routes](/code/api/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=api).

```text
POST /{namespace}/metrics/define
```

Body, as JSON: the inputs. 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**

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

```json
{
  "api": "https://api.sb/leaseline.app",
  "metric": {
    "$id": "https://api.sb/leaseline.app/metrics/metric_GXFHAlK100",
    "$type": "Metric",
    "query": "Example query",
    "status": "draft"
  },
  "action": {
    "$id": "https://api.sb/leaseline.app/actions/act_br07HsG8MG",
    "operation": "Metric.define",
    "status": "done"
  },
  "links": {
    "self": "https://api.sb/leaseline.app/actions/act_br07HsG8MG"
  }
}
```

### 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=api).

```text
POST /{namespace}/metrics/query
```

Body, as JSON: the inputs. 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**

```bash
curl -X POST https://api.sb/leaseline.app/metrics/query \
  -H "Authorization: Bearer $STARTUP_BUILDER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"shape":"trend"}'
```

```json
{
  "api": "https://api.sb/leaseline.app",
  "rows": {},
  "metric": {
    "$id": "https://api.sb/leaseline.app/metrics/metric_GXFHAlK100",
    "$type": "Metric",
    "query": "Example query",
    "status": "draft"
  },
  "action": {
    "$id": "https://api.sb/leaseline.app/actions/act_br07HsG8MG",
    "operation": "Metric.query",
    "status": "done"
  },
  "links": {
    "self": "https://api.sb/leaseline.app/actions/act_br07HsG8MG"
  }
}
```

### 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=api).

```text
POST /{namespace}/metrics/{metric}/watch
```

Path: `metric`. Body, as JSON: the other inputs. 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**

```bash
curl -X POST https://api.sb/leaseline.app/metrics/metric_GXFHAlK100/watch \
  -H "Authorization: Bearer $STARTUP_BUILDER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"threshold":1,"direction":"above"}'
```

```json
{
  "api": "https://api.sb/leaseline.app",
  "watch": {
    "$id": "https://api.sb/leaseline.app/watches/watch_9o4vCuR17L",
    "$type": "Watch",
    "selector": "Example selector",
    "url": "https://leaseline.app"
  },
  "metric": {
    "$id": "https://api.sb/leaseline.app/metrics/metric_GXFHAlK100",
    "$type": "Metric",
    "query": "Example query",
    "status": "draft"
  },
  "action": {
    "$id": "https://api.sb/leaseline.app/actions/act_br07HsG8MG",
    "operation": "Metric.watch",
    "status": "done"
  },
  "links": {
    "self": "https://api.sb/leaseline.app/actions/act_br07HsG8MG"
  }
}
```