---
title: "read_rate_card"
description: "Generated reference for the management action read_rate_card: its description, access metadata, payload contract, and registration status."
slug: /reference/actions/read-rate-card
order: 6
visibility: public
redirects_from: []
---

# read\_rate\_card

Generated automatically from the [published contract sources](/cloud/reference/about/#contract-sources).

A script calls this action over HTTPS at `POST https://turnzero.ai/api/v1/read_rate_card`, with a bearer credential and the action's payload as the JSON body. It also accepts `GET`. An MCP connection lists this action as the tool `read_rate_card`.

OAuth access tokens and minted tokens, including the turnzero command's computer token, are bearer credentials. The action determines which kinds, scopes and grants it accepts ([Sign-in, sessions, and tokens](/cloud/concepts/sign-in-sessions-and-tokens/)).

**Build metadata:** Registered in this build. Registration describes the default dispatcher in this build. It does not guarantee that a caller has the required credential or grant, that a tool is listed for that connection, or that the required service is configured.

## Contract description

Read the current price and unit for each rate key\. The read takes no arguments, writes nothing and returns one item per key in registry order\.

A price is in its key's unit\. `effective_from` is the UTC day it took effect, in YYYY\-MM\-DD form\. With no row in effect, `unset` is true and both `price` and `effective_from` are null, never zero or free\. The unit then comes from a future row if one exists, and is null otherwise\.

It serves once the estate's pricing reads usage\. Before then it refuses `invalid_request` without reading the rate table\. It returns no reason, stamp or author\. Read it before quoting a price or estimating a cost\.

## More about this action

The row in effect is each key's newest row whose effective day is no later than the call's UTC day\. The returned price is in that row's unit, at its stored precision; effective\_from is its effective UTC day\.

Where no row is in effect, unset is true and price and effective\_from are null\. That is no price, never zero, free or a default\. The unit comes from a future row if the table holds one, and is null otherwise\. Every registry key still has an item, in registry order\.

The read takes no arguments\. An unexpected request member is refused invalid\_request by that member's name\. Before pricing reads usage, the action refuses invalid\_request before reading the rate table\.

The read returns no reason, stamp or author\. This read supplies the current rates for a price quote or cost estimate\.

## Access and action metadata

```json
{
  "name": "read_rate_card",
  "resource": "account",
  "tier": "observe",
  "surface": "account",
  "addresses": [
    "tzcloud",
    "tztools"
  ],
  "summary": "Read the current rate card with no arguments. It returns one item per registry key: its unit, price, effective UTC day and `unset`, whether no rate is in effect. A missing rate is null, never zero. This read serves once pricing reads usage; before then it refuses `invalid_request`. It returns no reason, stamp or author.",
  "annotations": {
    "readOnlyHint": true,
    "destructiveHint": false,
    "openWorldHint": false,
    "idempotentHint": true
  }
}
```

## MCP catalog entry

```json
{
  "name": "read_rate_card",
  "title": "Read the current rate card",
  "tier": "observe",
  "scenario": "CHI-L0-09",
  "summary": "Read the current price and unit for each rate key. The read takes no arguments, writes nothing and returns one item per key in registry order.\n\nA price is in its key's unit. `effective_from` is the UTC day it took effect, in YYYY-MM-DD form. With no row in effect, `unset` is true and both `price` and `effective_from` are null, never zero or free. The unit then comes from a future row if one exists, and is null otherwise.\n\nIt serves once the estate's pricing reads usage. Before then it refuses `invalid_request` without reading the rate table. It returns no reason, stamp or author. Read it before quoting a price or estimating a cost.",
  "owners": [
    "PRC-L0-16",
    "PRC-L0-02"
  ]
}
```

## request

| JSON pointer | Description and constraints |
|---|---|
| "" \(root\) | Type: object<br>Additional properties: false |

## response

| JSON pointer | Description and constraints |
|---|---|
| "" \(root\) | Type: object<br>Required fields: \["contract\_version","rates","detail"\] |
| /<wbr>properties/<wbr>contract\_version | Required value: 1 |
| /<wbr>properties/<wbr>reference | The short reference the platform recorded your call under: ten lowercase hexadecimal characters, the value in the call’s record row\. Quote it when you report the call\.<br><br>Type: string<br>Pattern: ^\[0\-9a\-f\]\{10\}$ |
| /<wbr>properties/<wbr>rates | One item for every rate key, in registry order, including keys with no rate in effect\.<br><br>Type: array |
| /<wbr>properties/<wbr>rates/<wbr>items | Type: object<br>Required fields: \["key","unit","price","effective\_from","unset"\]<br>Additional properties: false |
| /<wbr>properties/<wbr>rates/<wbr>items/<wbr>properties/<wbr>key | The rate key whose price and unit this item describes\.<br><br>Type: string<br>Allowed values: \["monthly\-free\-usage","launch\-bonus","server\-shared\-0\.5gb","server\-shared\-1gb","server\-dedicated\-4gb","server\-dedicated\-8gb","server\-dedicated\-16gb","database\-shared","database\-dedicated\-2gb","database\-dedicated\-4gb","database\-dedicated\-8gb","database\-storage","file\-storage","data\-transfer","function\-calls","email","signin\-users","custom\-domain","logs\-extended","ai\-markup","chat\-image\-standard\-1k","chat\-image\-standard\-2k","chat\-image\-standard\-4k","chat\-image\-pro\-2k","chat\-image\-pro\-4k","tztrack\-ai\-passes","tzteam\-addition"\] |
| /<wbr>properties/<wbr>rates/<wbr>items/<wbr>properties/<wbr>unit | The unit of the row in effect\. If none is in effect, the unit of a future row where one exists, or null where the table holds no row for this key\.<br><br>Type: \["string","null"\] |
| /<wbr>properties/<wbr>rates/<wbr>items/<wbr>properties/<wbr>price | The price in this key's unit, as stored\. Null where no row is in effect; null is never zero, free or a default\.<br><br>Type: \["number","null"\]<br>Minimum: 0 |
| /<wbr>properties/<wbr>rates/<wbr>items/<wbr>properties/<wbr>effective\_from | The UTC day the current price took effect, in YYYY\-MM\-DD form, or null where no row is in effect\.<br><br>Type: \["string","null"\]<br>Pattern: ^\\d\{4\}\-\\d\{2\}\-\\d\{2\}$ |
| /<wbr>properties/<wbr>rates/<wbr>items/<wbr>properties/<wbr>unset | True where this key has no row in effect at the call; price and effective\_from are then null\. False where a row is in effect\.<br><br>Type: boolean |
| /<wbr>properties/<wbr>detail | What the rate items describe, how an unset key is represented, and how server time, a shared database and other usage make up an application's monthly total\.<br><br>Type: string |

## Complete payload contract

```json
{
  "request": {
    "type": "object",
    "properties": {},
    "additionalProperties": false
  },
  "response": {
    "type": "object",
    "required": [
      "contract_version",
      "rates",
      "detail"
    ],
    "properties": {
      "contract_version": {
        "const": 1
      },
      "reference": {
        "type": "string",
        "pattern": "^[0-9a-f]{10}$",
        "description": "The short reference the platform recorded your call under: ten lowercase hexadecimal characters, the value in the call’s record row. Quote it when you report the call."
      },
      "rates": {
        "type": "array",
        "description": "One item for every rate key, in registry order, including keys with no rate in effect.",
        "items": {
          "type": "object",
          "required": [
            "key",
            "unit",
            "price",
            "effective_from",
            "unset"
          ],
          "properties": {
            "key": {
              "type": "string",
              "enum": [
                "monthly-free-usage",
                "launch-bonus",
                "server-shared-0.5gb",
                "server-shared-1gb",
                "server-dedicated-4gb",
                "server-dedicated-8gb",
                "server-dedicated-16gb",
                "database-shared",
                "database-dedicated-2gb",
                "database-dedicated-4gb",
                "database-dedicated-8gb",
                "database-storage",
                "file-storage",
                "data-transfer",
                "function-calls",
                "email",
                "signin-users",
                "custom-domain",
                "logs-extended",
                "ai-markup",
                "chat-image-standard-1k",
                "chat-image-standard-2k",
                "chat-image-standard-4k",
                "chat-image-pro-2k",
                "chat-image-pro-4k",
                "tztrack-ai-passes",
                "tzteam-addition"
              ],
              "description": "The rate key whose price and unit this item describes."
            },
            "unit": {
              "type": [
                "string",
                "null"
              ],
              "description": "The unit of the row in effect. If none is in effect, the unit of a future row where one exists, or null where the table holds no row for this key."
            },
            "price": {
              "type": [
                "number",
                "null"
              ],
              "minimum": 0,
              "description": "The price in this key's unit, as stored. Null where no row is in effect; null is never zero, free or a default."
            },
            "effective_from": {
              "type": [
                "string",
                "null"
              ],
              "pattern": "^\\d{4}-\\d{2}-\\d{2}$",
              "description": "The UTC day the current price took effect, in YYYY-MM-DD form, or null where no row is in effect."
            },
            "unset": {
              "type": "boolean",
              "description": "True where this key has no row in effect at the call; price and effective_from are then null. False where a row is in effect."
            }
          },
          "additionalProperties": false
        }
      },
      "detail": {
        "type": "string",
        "description": "What the rate items describe, how an unset key is represented, and how server time, a shared database and other usage make up an application's monthly total."
      }
    }
  }
}
```

## Shared contracts

- [Refusals](/cloud/reference/refusals/): every refusal, by surface, with its cause and its remedy
- [schemas/wire\_error\.schema\.json](/cloud/reference/sources/schemas/wire-error-schema/)
- [schemas/wire\_errors\.json](/cloud/reference/sources/schemas/wire-errors/)
- [schemas/action\_payloads\.json](/cloud/reference/sources/schemas/action-payloads/) (includes shared shapes)
- [management\_api\_contract\.md](/cloud/reference/sources/management-api-contract/)
