# Play

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

> A Play is a named, repeatable strategy with the Metric it moves and its cost, run by a Startup as a Process.

A Play is a named, repeatable strategy with the [Metric](/business/nouns/metric) it moves and its cost, run by a [Startup](/business/nouns/startup) as a [Process](/business/nouns/process). A seed Play finds the first [Customers](/business/nouns/customer); a compound Play builds an engine that keeps growing.

## Properties
| Property | Type | Required | Description |
| --- | --- | --- | --- |
| `family` | `string` | Yes | The job it does, such as `demand`, `retention`, or `pricing`. |
| `cost` | `money` | No | What one run costs. |
| `cohort` | `json` | No | The Portfolio query a Studio rolls it out to. |
| `from` | `string` | No | Lineage: the slot it compiles from, as `Hypothesis#<slot>@v<version>`. |
| `spend` | `money` | No | Media, data and creative spend posted against the Play. |
| `workerCost` | `money` | No | What the Workers running it cost: model tokens, compute, upstream calls and human minutes. |
| `customersAcquired` | `integer` | No | Outside Customers whose Acquisition names the Play. |
| `outsideRevenue` | `money` | No | Revenue collected from those Customers, net of refunds. |
| `margin` | `money` | No | Outside revenue less spend, Worker cost and the cost to serve those Customers. |
| `paybackDays` | `integer` | No | Days from the first spend until margin covers spend and Worker cost; empty until it does. |

## Object
```json
{
  "$id": "https://api.sb/tutorloop.com/plays/play_1",
  "$type": "Play",
  "family": "demand",
  "cost": {
    "amount": 60,
    "currency": "USD"
  },
  "cohort": {},
  "from": "Hypothesis#approach@v1",
  "spend": {
    "amount": 60,
    "currency": "USD"
  },
  "workerCost": {
    "amount": 60,
    "currency": "USD"
  },
  "customersAcquired": 1,
  "outsideRevenue": {
    "amount": 60,
    "currency": "USD"
  },
  "margin": {
    "amount": 60,
    "currency": "USD"
  },
  "paybackDays": 1
}
```

## Relationships
- <a id="rel-carried-out-by"></a>A Play **is carried out by** many [Processes](/business/nouns/process): a [Process](/business/nouns/process) runs the steps of a Play each time the [Startup](/business/nouns/startup) runs it. `carriedOutBy`, inverse [`carriesOut`](/business/nouns/process#rel-carries-out).
- <a id="rel-included-in"></a>A Play **is included in** many [Play Mixes](/business/nouns/play-mix): a [Play Mix](/business/nouns/play-mix) names each Play the [Startup](/business/nouns/startup) runs this week, with its state, budget and stop rule. `includedIn`, inverse [`runs`](/business/nouns/play-mix#rel-runs).
- <a id="rel-moves"></a>A Play **moves** many [Metrics](/business/nouns/metric): a Play exists to move named [Metrics](/business/nouns/metric), read before and after every run. `moves`, inverse [`movedBy`](/business/nouns/metric#rel-moved-by).
- <a id="rel-paid-by"></a>A Play **is paid by** many [Demand Budgets](/business/nouns/demand-budget): a [Demand Budget](/business/nouns/demand-budget)’s spend buys demand Plays. `paidBy`, inverse [`pays`](/business/nouns/demand-budget#rel-pays).
- <a id="rel-targets"></a>A Play **targets** many [Portfolios](/business/nouns/portfolio): a [Studio](/business/nouns/studio) rolls a Play out across a [Portfolio](/business/nouns/portfolio) one cohort wave at a time, measured as an [Experiment](/business/nouns/experiment). `targets`, inverse [`plays`](/business/nouns/portfolio#rel-plays).

## Verbs
| Verb | Description | Subject | Event | Class |
| --- | --- | --- | --- | --- |
| [Play.apply](/business/nouns/play/apply) | Apply runs a Play across a Portfolio cohort, one wave at a time, measured as an Experiment. | [Marketing Lead](/agents/marketing/marketing-lead) | [`Play.applied`](/business/events/Play.applied) | None. |
| <a id="create"></a>[Play.create](/business/nouns/play/create) | Creates a Play. Inherited from [Noun](/business/nouns/noun). | None. | `Play.created` | Two-way: `try`, `send`, `do` |
| <a id="get"></a>[Play.get](/business/nouns/play/get) | Returns one Play by id. Inherited from [Noun](/business/nouns/noun). | None. | None. | Read: `try`, `do` |
| <a id="list"></a>[Play.list](/business/nouns/play/list) | Returns Plays, newest first, one page at a time. Inherited from [Noun](/business/nouns/noun). | None. | None. | Read: `try`, `do` |
| <a id="update"></a>[Play.update](/business/nouns/play/update) | Changes the given properties of a Play. Inherited from [Noun](/business/nouns/noun). | None. | `Play.updated` | Two-way: `try`, `send`, `do` |
| <a id="delete"></a>[Play.delete](/business/nouns/play/delete) | Deletes a Play; its history is kept. Inherited from [Noun](/business/nouns/noun). | None. | `Play.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` |
| --- | --- | --- | --- | --- |
| `Play.create` | Yes | Yes | Yes | No |
| `Play.get` | Yes | Yes | Yes | Yes |
| `Play.list` | Yes | Yes | Yes | Yes |
| `Play.update` | Yes | Yes | Yes | No |
| `Play.delete` | Yes | Yes | Yes | No |
| `Play.apply` | Yes | Yes | Yes | No |

## Call it

**Ask**

```text
Apply the latest play.
```

**API**

```bash
curl -X POST https://api.sb/kilnbakery.com/plays/play_1/apply \
  -H "Authorization: Bearer $STARTUP_BUILDER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"cohort":"Example cohort"}'
```

```json
{
  "api": "https://api.sb/kilnbakery.com",
  "experiment": {
    "$id": "https://api.sb/kilnbakery.com/experiments/experiment_1",
    "$type": "Experiment",
    "variants": {}
  },
  "play": {
    "$id": "https://api.sb/kilnbakery.com/plays/play_1",
    "$type": "Play",
    "family": "demand"
  },
  "action": {
    "$id": "https://api.sb/kilnbakery.com/actions/action_1",
    "operation": "Play.apply",
    "status": "done"
  },
  "links": {
    "self": "https://api.sb/kilnbakery.com/actions/action_1"
  }
}
```

**SDK**

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

const { experiment, play } = await $.Play.apply({ play: 'play_1', cohort: 'Example cohort' })
```

**CLI**

```bash
npx startup-builder do Play.apply --json '{"play":"play_1","cohort":"Example cohort"}'
```

**MCP**

```json
{
  "name": "do",
  "arguments": {
    "code": "return await $.Play.apply({ play: 'play_1', cohort: 'Example cohort' })"
  }
}
```

## Example
A creator-partnership Play gives a cooking creator 15% of the revenue her followers bring to a meal-planning [App](/business/nouns/app). It moves paid signups, costs nothing until a sale, and runs as a seed Play. After 60 days its ledger shows 23 Customers acquired, $1,840 in `outsideRevenue` and a `paybackDays` of 9.