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

# read\_counters

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

A script calls this action over HTTPS at `POST https://tzcloud.turnzero.ai/v1/read_counters`, 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 `tzcloud_read_counters`.

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 your deployed app's counters by name per environment, summed hourly or daily over a window\. These include your Logging package counters and `email_sent`, `email_failed`, `push_delivered` and `push_failed` delivery totals\. A window with no writes returns no bucket\. For platform usage, including backend actions and transferred bytes, use `read_usage`\.

## More about this action

The `since` argument: the inclusive start of the time window\. Write the date as YYYY\-MM\-DD, then T, then the time as HH:mm, with optional :ss and an optional fraction of 1 to 9 digits after the seconds, then Z or a signed HH:mm offset\. The T and the Z may be lowercase\. The date must exist on the calendar\. Hours run 00 to 23, minutes and seconds 00 to 59, and an offset's hours and minutes 00 to 23 and 00 to 59\. A leap second and 24:00 are not accepted\. The platform converts the value to UTC at millisecond precision\.

Without `since`, the start of the window is open\. The action refuses a null, an empty string, a value of the wrong type, or a malformed value with 400 `invalid_request`, and the detail gives the member\. Over MCP, the tool's argument check rejects a value of the wrong type before the action runs\.

The `until` argument: the inclusive end of the time window\. It takes the same form as `since`, and is checked, converted, and refused in the same way\. Without it, the end of the window is open\.

`logging.refused_capacity` increases by one for each whole batch refused as `log_capacity_reached` at the source's retained\-log capacity in the application environment\. To make room, you can erase the stream with `purge_logs` now or let entries expire after 30 days\. The client writes a refused batch to its fallback output and does not resend it\.

## Access and action metadata

```json
{
  "name": "read_counters",
  "resource": "environment",
  "tier": "observe",
  "surface": "tzcloud",
  "addresses": [
    "tzcloud"
  ],
  "product": "cloud",
  "summary": "The environment's counter totals by name over a window, at the hour or day grain (the logging service).",
  "annotations": {
    "readOnlyHint": true,
    "destructiveHint": false,
    "openWorldHint": false,
    "idempotentHint": true
  }
}
```

## MCP catalog entry

```json
{
  "name": "read_counters",
  "title": "Read app counters",
  "tier": "observe",
  "scenario": "CHI-L0-09",
  "summary": "Read your deployed app's counters by name per environment, summed hourly or daily over a window. These include your Logging package counters and `email_sent`, `email_failed`, `push_delivered` and `push_failed` delivery totals. A window with no writes returns no bucket. For platform usage, including backend actions and transferred bytes, use `read_usage`.",
  "owners": [
    "PLD-L0-40",
    "LGS-L0-15"
  ]
}
```

## request

| JSON pointer | Description and constraints |
|---|---|
| "" \(root\) | Type: object<br>Required fields: \["application","environment"\] |
| /<wbr>properties/<wbr>application | Your account's application `id` from `list_applications`, not its name or label\.<br><br>Type: string |
| /<wbr>properties/<wbr>environment | The stream to read: `development` or `production`, or `local` for the stream from your own computer\.<br><br>Type: string |
| /<wbr>properties/<wbr>name | One counter's name; omit it for every counter\.<br><br>Type: string |
| /<wbr>properties/<wbr>grain | `hour` or `day`; `day` where none is given\.<br><br>Type: string |
| /<wbr>properties/<wbr>since | Inclusive start of the time window: YYYY\-MM\-DD, T, HH:mm, optional :ss and a fraction of 1–9 digits, then Z or a signed HH:mm offset; T and Z may be lower case\. Leave it out and the bound is open\. A malformed, empty, or null value is refused `invalid_request`\.<br><br>Type: string |
| /<wbr>properties/<wbr>until | Inclusive end of the time window: YYYY\-MM\-DD, T, HH:mm, optional :ss and a fraction of 1–9 digits, then Z or a signed HH:mm offset; T and Z may be lower case\. Leave it out and the bound is open\. A malformed, empty, or null value is refused `invalid_request`\.<br><br>Type: string |
| /<wbr>properties/<wbr>limit | The most bucket rows returned, in bucket order; clamped to 1,000, the read ceiling, and the ceiling where omitted\. A malformed value is ignored\.<br><br>Type: integer<br>Minimum: 1 |

## response

| JSON pointer | Description and constraints |
|---|---|
| "" \(root\) | Type: object<br>Required fields: \["contract\_version","environment","grain","buckets"\] |
| /<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>environment | Type: string |
| /<wbr>properties/<wbr>grain | Type: string |
| /<wbr>properties/<wbr>detail | Present on an empty answer alone, saying why: the counters are the ones your application's own code writes with the Logging package's count call, so a request writes none, and you read the platform's usage, backend actions among them, with `read_usage`\. It also says a count reaches the store within a few seconds of its writing\.<br><br>Type: string |
| /<wbr>properties/<wbr>buckets | Type: array |
| /<wbr>properties/<wbr>buckets/<wbr>items | Type: object<br>Required fields: \["name","bucket\_start","total"\] |
| /<wbr>properties/<wbr>buckets/<wbr>items/<wbr>properties/<wbr>name | Type: string |
| /<wbr>properties/<wbr>buckets/<wbr>items/<wbr>properties/<wbr>bucket\_start | Type: string |
| /<wbr>properties/<wbr>buckets/<wbr>items/<wbr>properties/<wbr>total | Type: integer |

## Complete payload contract

```json
{
  "request": {
    "type": "object",
    "required": [
      "application",
      "environment"
    ],
    "properties": {
      "application": {
        "type": "string",
        "description": "Your account's application `id` from `list_applications`, not its name or label."
      },
      "environment": {
        "type": "string",
        "description": "The stream to read: `development` or `production`, or `local` for the stream from your own computer."
      },
      "name": {
        "type": "string",
        "description": "One counter's name; omit it for every counter."
      },
      "grain": {
        "type": "string",
        "description": "`hour` or `day`; `day` where none is given."
      },
      "since": {
        "type": "string",
        "description": "Inclusive start of the time window: YYYY-MM-DD, T, HH:mm, optional :ss and a fraction of 1–9 digits, then Z or a signed HH:mm offset; T and Z may be lower case. Leave it out and the bound is open. A malformed, empty, or null value is refused `invalid_request`."
      },
      "until": {
        "type": "string",
        "description": "Inclusive end of the time window: YYYY-MM-DD, T, HH:mm, optional :ss and a fraction of 1–9 digits, then Z or a signed HH:mm offset; T and Z may be lower case. Leave it out and the bound is open. A malformed, empty, or null value is refused `invalid_request`."
      },
      "limit": {
        "type": "integer",
        "minimum": 1,
        "description": "The most bucket rows returned, in bucket order; clamped to 1,000, the read ceiling, and the ceiling where omitted. A malformed value is ignored."
      }
    }
  },
  "response": {
    "type": "object",
    "required": [
      "contract_version",
      "environment",
      "grain",
      "buckets"
    ],
    "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."
      },
      "environment": {
        "type": "string"
      },
      "grain": {
        "type": "string"
      },
      "detail": {
        "type": "string",
        "description": "Present on an empty answer alone, saying why: the counters are the ones your application's own code writes with the Logging package's count call, so a request writes none, and you read the platform's usage, backend actions among them, with `read_usage`. It also says a count reaches the store within a few seconds of its writing."
      },
      "buckets": {
        "type": "array",
        "items": {
          "type": "object",
          "required": [
            "name",
            "bucket_start",
            "total"
          ],
          "properties": {
            "name": {
              "type": "string"
            },
            "bucket_start": {
              "type": "string"
            },
            "total": {
              "type": "integer"
            }
          }
        }
      }
    }
  }
}
```

## 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/)
