read_counters #
On this page
Generated automatically from the published 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).
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 #
{
"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 #
{
"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 Required fields: ["application","environment"] |
| / |
Your account's application id from list_applications, not its name or label.Type: string |
| / |
The stream to read: development or production, or local for the stream from your own computer.Type: string |
| / |
One counter's name; omit it for every counter. Type: string |
| / |
hour or day; day where none is given.Type: string |
| / |
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.Type: string |
| / |
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.Type: string |
| / |
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. Type: integer Minimum: 1 |
response #
| JSON pointer | Description and constraints |
|---|---|
| "" (root) | Type: object Required fields: ["contract_version","environment","grain","buckets"] |
| / |
Required value: 1 |
| / |
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. Type: string Pattern: ^[0-9a-f]{10}$ |
| / |
Type: string |
| / |
Type: string |
| / |
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.Type: string |
| / |
Type: array |
| / |
Type: object Required fields: ["name","bucket_start","total"] |
| / |
Type: string |
| / |
Type: string |
| / |
Type: integer |
Complete payload contract #
{
"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: every refusal, by surface, with its cause and its remedy
- schemas/wire_error.schema.json
- schemas/wire_errors.json
- schemas/action_payloads.json (includes shared shapes)
- management_api_contract.md