URL: /code/apps/analytics-and-experiments · Id: `page:/code/apps/analytics-and-experiments`

# Analytics and experiments

> Every visit and Event as Metrics you query, watch and test against, so each Play is read by its number and not by a hunch.

Every visit and [Event](https://startupbuilder.dev/business/nouns/event) as [Metrics](https://startupbuilder.dev/business/nouns/metric) you query, watch and test against, so each [Play](https://startupbuilder.dev/business/nouns/play) is read by its number and not by a hunch.

- **System:** [Analytics and experiments](https://startupbuilder.dev/systems/product-analytics)
- **Nouns:** 5
- **Verbs:** 9
- **Events:** 8

```text title="Run it · Ask"
Which of the three LinkedIn test ads brought a lead in its first week?
```

```ts title="Run it · SDK"
import { $ } from 'startup-builder'

const result = await $.try.Metric.query({ metric: 'new-leads', shape: 'trend', breakdown: 'ad', window: '7d' })
```

```json title="Run it · Response"
{
  "api": "https://api.sb/leaseline.app",
  "metric": {
    "$id": "https://api.sb/leaseline.app/metrics/new-leads",
    "$type": "Metric",
    "unit": "count"
  },
  "from": "2026-10-28",
  "rows": [
    {
      "ad": "late-rent",
      "value": 1,
      "series": [
        0,
        0,
        1,
        0,
        0,
        0,
        0
      ],
      "readable": false
    },
    {
      "ad": "owner-statement",
      "value": 0,
      "series": [
        0,
        0,
        0,
        0,
        0,
        0,
        0
      ],
      "readable": false
    },
    {
      "ad": "renewal-notice",
      "value": 0,
      "series": [
        0,
        0,
        0,
        0,
        0,
        0,
        0
      ],
      "readable": false
    }
  ],
  "action": {
    "operation": "Metric.query",
    "mode": "try",
    "status": "done"
  }
}
```

## Nouns
| Noun | What it is |
| --- | --- |
| [Visit](https://startupbuilder.dev/business/nouns/visit) | A Visit is one span of a Visitor’s Events on a startup’s Sites and Apps. |
| [Metric](https://startupbuilder.dev/business/nouns/metric) | A Metric is a named measure computed from Events or Entries, always derived and never typed in. |
| [Experiment](https://startupbuilder.dev/business/nouns/experiment) | An Experiment is a test of a Hypothesis that varies copy or behavior through Flags and judges the variants by a primary Metric. |
| [Hypothesis](https://startupbuilder.dev/business/nouns/hypothesis) | A Hypothesis is a belief about a startup stated so it can be proved wrong, with the Metric and threshold that settle it. |
| [Dashboard](https://startupbuilder.dev/business/nouns/dashboard) | A Dashboard is one unified view of a scope, rendered as Markdown for Agents, screens for Humans, and JSON for native clients. |

## Properties
The hub defines each Noun’s core Properties; Analytics and experiments adds the ones a sale needs.

### Visit
| Property | Type | What it holds | Defined by |
| --- | --- | --- | --- |
| `startedAt` | `datetime` | When it began. | The hub |
| `acquisition` | `string` | How the Visitor arrived: search, AI answer, agent, referral, ad, or direct. | The hub |

### Metric
| Property | Type | What it holds | Defined by |
| --- | --- | --- | --- |
| `query` | `text` | How it is computed. An agent never varies the Metrics it is judged by. | The hub |
| `unit` | `string` | The unit, such as dollars or percent. | The hub |
| `status` | `string` | One of `draft` or `defined`. | The hub |
| `play` | `Play \| null` | The Play it judges, so each Play is read by its own number. | Analytics and experiments |

### Experiment
| Property | Type | What it holds | Defined by |
| --- | --- | --- | --- |
| `variants` | `json` | The variants and their split. | The hub |
| `decision` | `string` | One of `ship`, `kill`, or `iterate`. | The hub |
| `winnerRule` | `string` | Declared before the first visit, so the winner is a rule, not a reading. | Analytics and experiments |
| `spend` | [`Money`](/code/data/types#money) | Ad money on your account, kept apart from the budget for the work. | Analytics and experiments |

### Hypothesis
| Property | Type | What it holds | Defined by |
| --- | --- | --- | --- |
| `statement` | `text` | The belief, in one sentence. | The hub |
| `kind` | `string` | One of `founding`, the five slots (`customer`, `problem`, `approach`, `switch`, `differentiation`), or `loop`. | The hub |
| `parent` | `hypothesis` | The Founding Hypothesis a slot Hypothesis belongs to. | The hub |
| `verdict` | `string` | One of `Open`, `Testing`, `Supported`, or `Refuted`. | The hub |
| `metric` | `metric` | The Metric that settles it. | The hub |
| `threshold` | `string` | The Metric value that settles it. | The hub |
| `grade` | `string` | Computed: the strongest grade of its outside Evidence, `None` without any. | The hub |
| `version` | `integer` | Each merged Change adds one; outputs cite it in their lineage. | The hub |

### Dashboard
| Property | Type | What it holds | Defined by |
| --- | --- | --- | --- |
| `scope` | `string` | What it views, such as a Studio, a startup, a Team, or a Role. | The hub |

## Lifecycle
Every move names the Verb that makes it, or the Event it waits on.

### Metric
| State | What it means | Moves to |
| --- | --- | --- |
| `draft` (first) | Its query is written and not compiled, so nothing reads it. | `defined` by [`Metric.define`](https://startupbuilder.dev/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. |

### Experiment
| State | What it means | Moves to |
| --- | --- | --- |
| `draft` (first) | Its variants and Metrics are set, and no traffic is split yet. | `running` by [`Experiment.start`](https://startupbuilder.dev/business/nouns/experiment/start) |
| `running` | Traffic is split across its variants while its Metrics are measured. | `concluded` by [`Experiment.conclude`](https://startupbuilder.dev/business/nouns/experiment/conclude) |
| `concluded` | It ended with a Decision to ship, kill, or iterate. | None: it ends here. |

### Hypothesis
| State | What it means | Moves to |
| --- | --- | --- |
| `open` (first) | Stated with its Metric and threshold, and bound to no Experiment. | `testing` by [`Hypothesis.test`](https://startupbuilder.dev/business/nouns/hypothesis/test); `dropped` by [`Hypothesis.drop`](https://startupbuilder.dev/business/nouns/hypothesis/drop) |
| `testing` | An Experiment that decides it is running. | `supported` on `Experiment.concluded`; `refuted` on `Experiment.concluded`; `dropped` by [`Hypothesis.drop`](https://startupbuilder.dev/business/nouns/hypothesis/drop) |
| `supported` | Its Experiment met the threshold; its outside Evidence grades how far that holds. | `testing` by [`Hypothesis.test`](https://startupbuilder.dev/business/nouns/hypothesis/test); `dropped` by [`Hypothesis.drop`](https://startupbuilder.dev/business/nouns/hypothesis/drop) |
| `refuted` | Its Experiment missed the threshold; a merged Change can restate it and test it again. | `testing` by [`Hypothesis.test`](https://startupbuilder.dev/business/nouns/hypothesis/test); `dropped` by [`Hypothesis.drop`](https://startupbuilder.dev/business/nouns/hypothesis/drop) |
| `dropped` | Retired from active work and kept on record with its Evidence. | None: it ends here. |

## Verbs
| Verb | What it does | Approval | On each site |
| --- | --- | --- | --- |
| [`Metric.query`](/code/apps/analytics-and-experiments/query) | Reads a number from your Events as a trend, funnel, retention curve or path, split by any property. | Runs on its own | Bing, Facebook, Google Search, Google Display, YouTube, Google Business Profile, Instagram, LinkedIn, Reddit, TikTok, X |
| [`Metric.watch`](https://startupbuilder.dev/business/nouns/metric/watch) | Opens a Task, or sends you a Message, the day a number crosses the line you set. | Runs on its own | None. |
| [`Experiment.start`](https://startupbuilder.dev/business/nouns/experiment/start) | Splits traffic across your variants and starts measuring the primary and guardrail numbers. | Runs on its own | None. |
| [`Experiment.conclude`](https://startupbuilder.dev/business/nouns/experiment/conclude) | Ends an Experiment with ship, kill or iterate, recorded as a Decision with its reason. | Runs on its own | None. |
| [`Dashboard.ask`](https://startupbuilder.dev/business/nouns/dashboard/ask) | Answers a plain question with a query over your records, the query shown beside the answer. | Runs on its own | None. |
| [`Metric.define`](https://startupbuilder.dev/business/nouns/metric/define) | Compiles a number from your Events and lists every Event it reads, so no one types it in. | Runs on its own | None. |
| [`Event.capture`](https://startupbuilder.dev/business/nouns/event/capture) | Records one Event from your Site or product, such as a signup, so every number above can read it. | Runs on its own | None. |
| [`Hypothesis.test`](https://startupbuilder.dev/business/nouns/hypothesis/test) | Ties a Hypothesis to the Experiment that decides it, and marks it testing. | Runs on its own | None. |
| [`Dashboard.schedule`](https://startupbuilder.dev/business/nouns/dashboard/schedule) | Sends a Dashboard on a schedule to a Mailbox, a Channel or an agent’s context. | Runs on its own | None. |

## Events
| Event | Emitted by |
| --- | --- |
| `Metric.queried` | [`Metric.query`](/code/apps/analytics-and-experiments/query) |
| `Metric.watched` | [`Metric.watch`](https://startupbuilder.dev/business/nouns/metric/watch) |
| `Metric.defined` | [`Metric.define`](https://startupbuilder.dev/business/nouns/metric/define) |
| `Experiment.started` | [`Experiment.start`](https://startupbuilder.dev/business/nouns/experiment/start) |
| `Experiment.concluded` | [`Experiment.conclude`](https://startupbuilder.dev/business/nouns/experiment/conclude) |
| `Hypothesis.tested` | [`Hypothesis.test`](https://startupbuilder.dev/business/nouns/hypothesis/test) |
| `Dashboard.asked` | [`Dashboard.ask`](https://startupbuilder.dev/business/nouns/dashboard/ask) |
| `Event.captured` | [`Event.capture`](https://startupbuilder.dev/business/nouns/event/capture) |

A [Trigger](https://startupbuilder.dev/business/nouns/trigger) can start a Workflow on any of them, and a Watch delivers each to your endpoint, signed ([Events and webhooks](/code/events)).

## Who operates it
| Part | Analytics and experiments |
| --- | --- |
| Accountable | [Marketing lead](https://startupbuilder.dev/agents/marketing/marketing-lead) |
| Also calls its Verbs | [Customer lead](https://startupbuilder.dev/agents/customer/customer-lead), [Founder](https://startupbuilder.dev/agents/founding/founder) |
| Seat | An agent holds each seat until you seat a person in it. |
| Asks you first | None of its Verbs: each runs within its seat’s Limits |

## Integrations
[Google Analytics](/code/integrations/google-analytics) · [Google Search Console](/code/integrations/google-search-console)

## Import and export
| Direction | What | How |
| --- | --- | --- |
| Import | Your analytics history | `Integration.connect` for [Google Analytics](/code/integrations/google-analytics); sessions come in as Visits |
| Export | Any number, as a series | `Metric.query`, or `Collection.export` to your warehouse |

## Example
**One number per Play, read every week.**

1. `Event.capture` records each signup from the site.
2. `Metric.define` compiles “trials a week from cold email” from those Events.
3. `Metric.watch` opens a Task the week it drops under 3.