# Cost

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

> A Cost is an Entry against a cost account that an Action causes, posted to the Startup the Action ran in.

A Cost is an [Entry](/business/nouns/entry) against a cost account that an [Action](/business/nouns/action) causes, posted to the [Startup](/business/nouns/startup) the Action ran in.

## Properties
| Property | Type | Required | Description |
| --- | --- | --- | --- |
| `action` | [Action](/business/nouns/action) | Yes | The Action that caused it. |
| `startup` | [Startup](/business/nouns/startup) | Yes | The Startup it is posted to. |
| `kind` | `string` | Yes | One of `model`, `upstream`, `human`, `platform` or `shared`. |
| `allocation` | `text` | No | For shared Cost, the stated rule that splits it across Startups. |
| `attempt` | `integer` | No | Which outside attempt this Cost paid for when one call tried several upstreams in rank. |
| `overrun` | `money` | No | How far the settled amount exceeded the Action’s reservation; an overrun past a Limit opens an Approval. |

<details>
<summary>Inherited from [Entry](/business/nouns/entry): 4 properties</summary>

| Property | Type | Required | Description |
| --- | --- | --- | --- |
| `account` | `string` | Yes | The code of the account in the chart of accounts, such as revenue or cash. |
| `amount` | `money` | Yes | The amount and currency. |
| `direction` | `string` | Yes | One of `debit` or `credit`. |
| `counterparty` | [Startup](/business/nouns/startup) | No | The sibling Startup on the other side of an intercompany Entry; empty for outside parties. |

</details>

## Object
```json
{
  "$id": "https://api.sb/patentpad.com/costs/cost_1",
  "$type": "Cost",
  "account": "cash",
  "amount": {
    "amount": 499,
    "currency": "USD"
  },
  "direction": "debit",
  "counterparty": "startup_1",
  "action": "action_1",
  "startup": "startup_1",
  "kind": "model",
  "allocation": "Split by each Startup’s share of API calls",
  "attempt": 1,
  "overrun": {
    "amount": 499,
    "currency": "USD"
  }
}
```

## Relationships
- <a id="rel-posted-by"></a>A Cost **is posted by** one [Action](/business/nouns/action): every Cost an [Action](/business/nouns/action) causes posts to the [Startup](/business/nouns/startup) it ran in, so each Startup’s P&L is complete. `postedBy`, inverse [`posts`](/business/nouns/action#rel-posts).

## Verbs
| Verb | Description | Subject | Event | Class |
| --- | --- | --- | --- | --- |
| <a id="get"></a>[Cost.get](/business/nouns/cost/get) | Returns one Cost by id. Inherited from [Noun](/business/nouns/noun). | None. | None. | Read: `try`, `do` |
| <a id="list"></a>[Cost.list](/business/nouns/cost/list) | Returns Costs, newest first, one page at a time. Inherited from [Noun](/business/nouns/noun). | None. | None. | Read: `try`, `do` |

A Cost is kept forever and never edited: it has no `update` or `delete`.

## Permissions
Which Access level may call each Verb. One-way Verbs wait their delay window.

| Operation | `owner` | `admin` | `member` | `viewer` |
| --- | --- | --- | --- | --- |
| `Cost.get` | Yes | Yes | Yes | Yes |
| `Cost.list` | Yes | Yes | Yes | Yes |

## Call it

**Ask**

```text
Show me the latest cost.
```

**API**

```bash
curl https://api.sb/shiftnote.app/costs/cost_1 \
  -H "Authorization: Bearer $STARTUP_BUILDER_API_KEY"
```

```json
{
  "api": "https://api.sb/shiftnote.app",
  "$type": "Cost",
  "$id": "https://api.sb/shiftnote.app/costs/cost_1",
  "cost": {
    "$id": "https://api.sb/shiftnote.app/costs/cost_1",
    "$type": "Cost",
    "account": "cash",
    "amount": {
      "amount": 79,
      "currency": "USD"
    },
    "direction": "debit",
    "action": "action_1"
  },
  "links": {
    "self": "https://api.sb/shiftnote.app/costs/cost_1",
    "up": "https://api.sb/shiftnote.app/costs"
  }
}
```

**SDK**

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

const cost = await $.Cost.get({ id: 'cost_1' })
```

**CLI**

```bash
npx startup-builder do Cost.get --json '{"id":"cost_1"}'
```

**MCP**

```json
{
  "name": "do",
  "arguments": {
    "code": "return await $.Cost.get({ id: 'cost_1' })"
  }
}
```

## Example
A permit-status API pays $0.40 for each county records request. Each one is a Cost on the lookup Action, so the margin on a $1 lookup reads $0.60.