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

# read\_push

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_push`, 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_push`.

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 application's push configuration, registered devices and delivery counts for one environment\. The manifest must declare push, or the call is refused `push_not_declared`\. Last\-hour delivery outcomes cover that environment\. `pending` counts every delivery waiting now, of any age\. The month's accepted total covers both environments, beside the size's quantity, the same for both sizes\. A null quota refuses every send\. Devices read zero without an accounts service, as well as before registration\. For failed\-delivery reasons, read `push_failed` lines with `read_logs`\.

## More about this action

The configuration gives provider identifiers and secret names, never values\. Device counts are by platform; `invalid` counts those marked gone\.

## Access and action metadata

```json
{
  "name": "read_push",
  "resource": "push",
  "tier": "observe",
  "surface": "tzcloud",
  "addresses": [
    "tzcloud"
  ],
  "product": "cloud",
  "summary": "An application environment's push configuration with secret names only, its device counts by platform, the last hour's delivery outcomes, and the month's accepted deliveries beside the size's quantity, the same for both sizes.",
  "annotations": {
    "readOnlyHint": true,
    "destructiveHint": false,
    "openWorldHint": false,
    "idempotentHint": true
  }
}
```

## MCP catalog entry

```json
{
  "name": "read_push",
  "title": "Read push notification settings",
  "tier": "observe",
  "summary": "Read your application's push configuration, registered devices and delivery counts for one environment. The manifest must declare push, or the call is refused `push_not_declared`. Last-hour delivery outcomes cover that environment. `pending` counts every delivery waiting now, of any age. The month's accepted total covers both environments, beside the size's quantity, the same for both sizes. A null quota refuses every send. Devices read zero without an accounts service, as well as before registration. For failed-delivery reasons, read `push_failed` lines with `read_logs`.",
  "owners": [
    "PSH-L0-01",
    "PSH-L0-02",
    "PSH-L0-04",
    "PLD-L0-40"
  ],
  "scenario": "PSH-L0-01"
}
```

## request

| JSON pointer | Description and constraints |
|---|---|
| "" \(root\) | Type: object<br>Required fields: \["application"\]<br>Additional properties: false |
| /<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 | Optional\. The environment you address, `development` or `production`; `production` if you leave it out\.<br><br>Type: string<br>Pattern: ^\(development\|production\)$ |

## response

| JSON pointer | Description and constraints |
|---|---|
| "" \(root\) | Type: object<br>Required fields: \["contract\_version","push"\]<br>Additional properties: false |
| /<wbr>properties/<wbr>contract\_version | Required value: 1 |
| /<wbr>properties/<wbr>push | Type: object<br>Required fields: \["application","environment","apns","fcm","configured","devices","last\_hour","accepted\_this\_month","quota"\]<br>Additional properties: false |
| /<wbr>properties/<wbr>push/<wbr>properties/<wbr>application | Type: string |
| /<wbr>properties/<wbr>push/<wbr>properties/<wbr>environment | Type: string<br>Allowed values: \["development","production"\] |
| /<wbr>properties/<wbr>push/<wbr>properties/<wbr>apns | Type: \["object","null"\]<br>Required fields: \["team\_id","key\_id","bundle\_id","key\_secret\_name","environment"\]<br>Additional properties: false |
| /<wbr>properties/<wbr>push/<wbr>properties/<wbr>apns/<wbr>properties/<wbr>team\_id | The ten\-character Apple team identifier\.<br><br>Type: string |
| /<wbr>properties/<wbr>push/<wbr>properties/<wbr>apns/<wbr>properties/<wbr>key\_id | The ten\-character identifier of the APNs signing key\.<br><br>Type: string |
| /<wbr>properties/<wbr>push/<wbr>properties/<wbr>apns/<wbr>properties/<wbr>bundle\_id | The app's bundle identifier, the notification's topic\.<br><br>Type: string |
| /<wbr>properties/<wbr>push/<wbr>properties/<wbr>apns/<wbr>properties/<wbr>key\_secret\_name | The custody NAME of the stored \.p8 signing key at this environment scope; never a value\.<br><br>Type: string |
| /<wbr>properties/<wbr>push/<wbr>properties/<wbr>apns/<wbr>properties/<wbr>environment | Which of Apple's two gateways this environment's pushes go to\.<br><br>Type: string<br>Allowed values: \["production","sandbox"\] |
| /<wbr>properties/<wbr>push/<wbr>properties/<wbr>fcm | Type: \["object","null"\]<br>Required fields: \["project\_id","service\_account\_secret\_name"\]<br>Additional properties: false |
| /<wbr>properties/<wbr>push/<wbr>properties/<wbr>fcm/<wbr>properties/<wbr>project\_id | The Firebase project identifier\.<br><br>Type: string |
| /<wbr>properties/<wbr>push/<wbr>properties/<wbr>fcm/<wbr>properties/<wbr>service\_account\_secret\_name | The custody NAME of the stored service\-account JSON file at this environment scope; never a value\.<br><br>Type: string |
| /<wbr>properties/<wbr>push/<wbr>properties/<wbr>configured | True where at least one provider is configured\.<br><br>Type: boolean |
| /<wbr>properties/<wbr>push/<wbr>properties/<wbr>devices | Type: object<br>Required fields: \["ios","android","invalid"\]<br>Additional properties: false |
| /<wbr>properties/<wbr>push/<wbr>properties/<wbr>devices/<wbr>properties/<wbr>ios | Type: integer |
| /<wbr>properties/<wbr>push/<wbr>properties/<wbr>devices/<wbr>properties/<wbr>android | Type: integer |
| /<wbr>properties/<wbr>push/<wbr>properties/<wbr>devices/<wbr>properties/<wbr>invalid | Registrations a provider reported gone, skipped until the app registers again\.<br><br>Type: integer |
| /<wbr>properties/<wbr>push/<wbr>properties/<wbr>last\_hour | Type: object<br>Required fields: \["delivered","invalid","dead","pending"\]<br>Additional properties: false |
| /<wbr>properties/<wbr>push/<wbr>properties/<wbr>last\_hour/<wbr>properties/<wbr>delivered | Type: integer |
| /<wbr>properties/<wbr>push/<wbr>properties/<wbr>last\_hour/<wbr>properties/<wbr>invalid | Type: integer |
| /<wbr>properties/<wbr>push/<wbr>properties/<wbr>last\_hour/<wbr>properties/<wbr>dead | Type: integer |
| /<wbr>properties/<wbr>push/<wbr>properties/<wbr>last\_hour/<wbr>properties/<wbr>pending | Rows queued or in flight now, whatever their age\.<br><br>Type: integer |
| /<wbr>properties/<wbr>push/<wbr>properties/<wbr>accepted\_this\_month | The deliveries accepted this UTC month, the figure the send compares with the cell\.<br><br>Type: integer |
| /<wbr>properties/<wbr>push/<wbr>properties/<wbr>quota | The size's served `push-messages-capacity` quantity, or null for an Unset cell\.<br><br>Type: \["integer","null"\] |

## Complete payload contract

```json
{
  "request": {
    "type": "object",
    "required": [
      "application"
    ],
    "properties": {
      "application": {
        "type": "string",
        "description": "Your account's application `id` from `list_applications`, not its name or label."
      },
      "environment": {
        "type": "string",
        "pattern": "^(development|production)$",
        "description": "Optional. The environment you address, `development` or `production`; `production` if you leave it out."
      }
    },
    "additionalProperties": false
  },
  "response": {
    "type": "object",
    "required": [
      "contract_version",
      "push"
    ],
    "properties": {
      "contract_version": {
        "const": 1
      },
      "push": {
        "type": "object",
        "required": [
          "application",
          "environment",
          "apns",
          "fcm",
          "configured",
          "devices",
          "last_hour",
          "accepted_this_month",
          "quota"
        ],
        "properties": {
          "application": {
            "type": "string"
          },
          "environment": {
            "type": "string",
            "enum": [
              "development",
              "production"
            ]
          },
          "apns": {
            "type": [
              "object",
              "null"
            ],
            "required": [
              "team_id",
              "key_id",
              "bundle_id",
              "key_secret_name",
              "environment"
            ],
            "properties": {
              "team_id": {
                "type": "string",
                "description": "The ten-character Apple team identifier."
              },
              "key_id": {
                "type": "string",
                "description": "The ten-character identifier of the APNs signing key."
              },
              "bundle_id": {
                "type": "string",
                "description": "The app's bundle identifier, the notification's topic."
              },
              "key_secret_name": {
                "type": "string",
                "description": "The custody NAME of the stored .p8 signing key at this environment scope; never a value."
              },
              "environment": {
                "type": "string",
                "enum": [
                  "production",
                  "sandbox"
                ],
                "description": "Which of Apple's two gateways this environment's pushes go to."
              }
            },
            "additionalProperties": false
          },
          "fcm": {
            "type": [
              "object",
              "null"
            ],
            "required": [
              "project_id",
              "service_account_secret_name"
            ],
            "properties": {
              "project_id": {
                "type": "string",
                "description": "The Firebase project identifier."
              },
              "service_account_secret_name": {
                "type": "string",
                "description": "The custody NAME of the stored service-account JSON file at this environment scope; never a value."
              }
            },
            "additionalProperties": false
          },
          "configured": {
            "type": "boolean",
            "description": "True where at least one provider is configured."
          },
          "devices": {
            "type": "object",
            "required": [
              "ios",
              "android",
              "invalid"
            ],
            "properties": {
              "ios": {
                "type": "integer"
              },
              "android": {
                "type": "integer"
              },
              "invalid": {
                "type": "integer",
                "description": "Registrations a provider reported gone, skipped until the app registers again."
              }
            },
            "additionalProperties": false
          },
          "last_hour": {
            "type": "object",
            "required": [
              "delivered",
              "invalid",
              "dead",
              "pending"
            ],
            "properties": {
              "delivered": {
                "type": "integer"
              },
              "invalid": {
                "type": "integer"
              },
              "dead": {
                "type": "integer"
              },
              "pending": {
                "type": "integer",
                "description": "Rows queued or in flight now, whatever their age."
              }
            },
            "additionalProperties": false
          },
          "accepted_this_month": {
            "type": "integer",
            "description": "The deliveries accepted this UTC month, the figure the send compares with the cell."
          },
          "quota": {
            "type": [
              "integer",
              "null"
            ],
            "description": "The size's served `push-messages-capacity` quantity, or null for an Unset cell."
          }
        },
        "additionalProperties": false
      }
    },
    "additionalProperties": false
  }
}
```

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