# Cohort

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

> A Cohort is a set of Startups that receives one Version of a shared definition, or one step of a Play, at the same time.

A Cohort is a set of [Startups](/business/nouns/startup) that receives one [Version](/business/nouns/version) of a shared definition, or one step of a [Play](/business/nouns/play), at the same time.

## Properties
| Property | Type | Required | Description |
| --- | --- | --- | --- |
| `query` | `json` | Yes | The Portfolio query that selects its Startups. |
| `control` | `boolean` | No | True when the Cohort stays on the prior Version as the control. |

## Object
```json
{
  "$id": "https://api.sb/patentpad.com/cohorts/cohort_1",
  "$type": "Cohort",
  "query": {},
  "control": true
}
```

## Relationships
- <a id="rel-drawn-from"></a>A Cohort **is drawn from** one [Portfolio](/business/nouns/portfolio): a Cohort selects its [Startups](/business/nouns/startup) from one [Portfolio](/business/nouns/portfolio) by a saved query. `drawnFrom`, inverse [`cohorts`](/business/nouns/portfolio#rel-cohorts).
- <a id="rel-pinned-to"></a>A Cohort **is pinned to** one [Version](/business/nouns/version): every [Startup](/business/nouns/startup) in a Cohort runs the same [Version](/business/nouns/version) of a shared definition; a control Cohort keeps the prior one. `pinnedTo`, inverse [`pinnedCohorts`](/business/nouns/version#rel-pinned-cohorts).

## Verbs
| Verb | Description | Subject | Event | Class |
| --- | --- | --- | --- | --- |
| <a id="create"></a>[Cohort.create](/business/nouns/cohort/create) | Creates a Cohort. Inherited from [Noun](/business/nouns/noun). | None. | `Cohort.created` | Two-way: `try`, `send`, `do` |
| <a id="get"></a>[Cohort.get](/business/nouns/cohort/get) | Returns one Cohort by id. Inherited from [Noun](/business/nouns/noun). | None. | None. | Read: `try`, `do` |
| <a id="list"></a>[Cohort.list](/business/nouns/cohort/list) | Returns Cohorts, newest first, one page at a time. Inherited from [Noun](/business/nouns/noun). | None. | None. | Read: `try`, `do` |
| <a id="update"></a>[Cohort.update](/business/nouns/cohort/update) | Changes the given properties of a Cohort. Inherited from [Noun](/business/nouns/noun). | None. | `Cohort.updated` | Two-way: `try`, `send`, `do` |
| <a id="delete"></a>[Cohort.delete](/business/nouns/cohort/delete) | Deletes a Cohort; its history is kept. Inherited from [Noun](/business/nouns/noun). | None. | `Cohort.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` |
| --- | --- | --- | --- | --- |
| `Cohort.create` | Yes | Yes | Yes | No |
| `Cohort.get` | Yes | Yes | Yes | Yes |
| `Cohort.list` | Yes | Yes | Yes | Yes |
| `Cohort.update` | Yes | Yes | Yes | No |
| `Cohort.delete` | Yes | Yes | Yes | No |

## Call it

**Ask**

```text
Add a cohort to ShiftNote.
```

**API**

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

```json
{
  "api": "https://api.sb/shiftnote.app",
  "cohort": {
    "$id": "https://api.sb/shiftnote.app/cohorts/cohort_1",
    "$type": "Cohort",
    "query": {}
  },
  "action": {
    "$id": "https://api.sb/shiftnote.app/actions/action_1",
    "operation": "Cohort.create",
    "status": "done"
  },
  "links": {
    "self": "https://api.sb/shiftnote.app/actions/action_1"
  }
}
```

**SDK**

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

const cohort = await $.Cohort.create({ query: {} })
```

**CLI**

```bash
npx startup-builder do Cohort.create --json '{"query":{}}'
```

**MCP**

```json
{
  "name": "do",
  "arguments": {
    "code": "return await $.Cohort.create({ query: {} })"
  }
}
```

## Example
A [Studio](/business/nouns/studio) rolls Keyless signup out to a first Cohort: 1% of its Startups with a priced API. A control Cohort of the same size stays on the prior Version.