---
title: "Create a gRPC monitor"
method: POST
path: "/v1/checks/grpc"
tags: ["Monitors"]
---

# Create a gRPC monitor

`POST /v1/checks/grpc`

## Request

- Base URL: `https://api.checklyhq.com`
- URL: `https://api.checklyhq.com/v1/checks/grpc`
- Auth: HTTP bearer
- TypeScript: <https://skmtc.dev/checklyhq/apis/checkly-public-api/docs/v1/checks/grpc/post.ts> (a function with typed inputs; its response is checked against the schema)

Creates a new gRPC monitor. Will return a `402` when you are over the limit of your plan.
    When using the `globalAlertSetting`, the `alertSetting` can be `null`

## Query parameters

- `autoAssignAlerts` boolean: Determines whether a new check will automatically be added as a subscriber to all existing alert channels when it gets created.

## Headers

- `x-checkly-account` string, uuid: Your Checkly account ID, you can find it at https://app.checklyhq.com/settings/account/general

## Request body

- ChecksV1GrpcMonitorCreate
  - `name` string, required
  - `activated` boolean
  - `muted` boolean
  - `doubleCheck` boolean
  - `shouldFail` boolean
  - `locations` string[], nullable
  - `tags` string[]
  - `alertSettings` ChecksV1AlertSettingsCreate
    - `escalationType` 'RUN_BASED' | 'TIME_BASED'
    - `reminders` object
      - `amount` 0 | 1 | 2 | 3 | 4 | 5 | 100000
      - `interval` 1 | 2 | 3 | 4 | 5 | 10 | 15 | 30
    - `sslCertificates` object
      - `enabled` boolean
      - `alertThreshold` integer
    - `runBasedEscalation` ChecksV1AlertSettingsRunBasedEscalation
      - `failedRunThreshold` 1 | 2 | 3 | 4 | 5
    - `timeBasedEscalation` ChecksV1AlertSettingsTimeBasedEscalation
      - `minutesFailingThreshold` 5 | 10 | 15 | 30
    - `parallelRunFailureThreshold` object
      - `enabled` boolean
      - `percentage` 10 | 20 | 30 | 40 | 50 | 60 | 70 | 80 | 90 | 100
  - `useGlobalAlertSettings` boolean
  - `groupId` number, nullable
  - `groupOrder` number, nullable
  - `runtimeId` '2026.04' | '2025.04' | '2024.09' | '2024.02' | '2023.09' | '2023.02' | '2022.10' | 'null', nullable
  - `alertChannelSubscriptions` ChecksV1AlertChannelSubscription[]
    - `alertChannelId` number, required
    - `activated` boolean, required
  - `retryStrategy` ChecksV1RetryStrategy, nullable
    - `type` 'FIXED' | 'LINEAR' | 'EXPONENTIAL' | 'SINGLE_RETRY', required
    - `baseBackoffSeconds` number
    - `sameRegion` boolean
    - `maxRetries` number
    - `maxDurationSeconds` number
    - `onlyOn` string[]
  - `triggerIncident` ChecksV1TriggerIncident, nullable
    - `serviceId` string, uuid, required
    - `severity` 'CRITICAL' | 'MAJOR' | 'MEDIUM' | 'MINOR', required
    - `name` string, required
    - `description` string, required
    - `notifySubscribers` boolean, required
  - `runParallel` boolean
  - `description` string, nullable
  - `intent` object, nullable
    - `goal` string, required: The user or system outcome this check protects.
    - `requiredOutcomes` string[]: Observable outcomes the check must continue to prove.
    - `mustPreserve` string[]: Guardrails an AI repair must not weaken or bypass.
  - `aiAutoRepairEnabled` boolean, nullable
  - `checkType` 'GRPC'
  - `frequency` 0 | 1 | 2 | 5 | 10 | 15 | 30 | 60 | 120 | 180 | 360 | 720 | 1440
  - `frequencyOffset` integer
  - `heartbeat` object, nullable
  - `script` string, nullable
  - `scriptPath` string, nullable
  - `sslCheckDomain` string, nullable
  - `environmentVariables` ChecksV1EnvironmentVariable[], nullable
    - `key` string, required
    - `value` string, nullable, required
    - `locked` boolean
    - `secret` boolean
  - `setupSnippetId` number, nullable
  - `tearDownSnippetId` number, nullable
  - `localSetupScript` string, nullable
  - `localTearDownScript` string, nullable
  - `request` ChecksV1GrpcRequest, required
    - `url` string, required
    - `port` integer, required
    - `ipFamily` 'IPv4' | 'IPv6' | 'null', nullable
    - `skipSSL` boolean
    - `timeout` integer, nullable
    - `grpcConfig` ChecksV1GrpcConfig, required
      - `mode` 'BEHAVIOR' | 'HEALTH'
      - `tls` boolean
      - `metadata` ChecksV1GrpcMetadataItem[]
        - `key` string, required
        - `value` string, required
      - `service` unknown
      - `encoding` unknown
      - `serviceDefinition` unknown
      - `method` unknown
      - `protoContent` unknown
      - `bfbsContent` unknown
      - `message` unknown
    - `assertions` ChecksV1GrpcAssertion[]
      - `source` 'RESPONSE_TIME' | 'GRPC_RESPONSE' | 'TEXT_BODY' | 'GRPC_METADATA' | 'GRPC_HEALTHCHECK_STATUS' | 'GRPC_STATUS_CODE', required
      - `comparison` 'EQUALS' | 'NOT_EQUALS' | 'HAS_KEY' | 'NOT_HAS_KEY' | 'HAS_VALUE' | 'NOT_HAS_VALUE' | 'IS_EMPTY' | 'NOT_EMPTY' | 'GREATER_THAN' | 'LESS_THAN' | 'CONTAINS' | 'NOT_CONTAINS' | 'IS_NULL' | 'NOT_NULL', required
      - `property` string
      - `target` string
      - `regex` string, nullable
  - `degradedResponseTime` number, nullable
  - `maxResponseTime` number, nullable
  - `privateLocations` string[], nullable

## Response `201`

Created

- ChecksV1GrpcMonitor
  - `name` string, required
  - `activated` boolean
  - `muted` boolean
  - `doubleCheck` boolean
  - `shouldFail` boolean
  - `locations` string[], nullable
  - `tags` string[]
  - `alertSettings` ChecksV1AlertSettings, nullable
    - `escalationType` 'RUN_BASED' | 'TIME_BASED'
    - `reminders` object
      - `amount` 0 | 1 | 2 | 3 | 4 | 5 | 100000
      - `interval` 1 | 2 | 3 | 4 | 5 | 10 | 15 | 30
    - `sslCertificates` object
      - `enabled` boolean
      - `alertThreshold` integer
    - `runBasedEscalation` ChecksV1AlertSettingsRunBasedEscalation
      - `failedRunThreshold` 1 | 2 | 3 | 4 | 5
    - `timeBasedEscalation` ChecksV1AlertSettingsTimeBasedEscalation
      - `minutesFailingThreshold` 5 | 10 | 15 | 30
    - `parallelRunFailureThreshold` object
      - `enabled` boolean
      - `percentage` 10 | 20 | 30 | 40 | 50 | 60 | 70 | 80 | 90 | 100
  - `useGlobalAlertSettings` boolean
  - `groupId` number, nullable
  - `groupOrder` number, nullable
  - `runtimeId` '2026.04' | '2025.04' | '2024.09' | '2024.02' | '2023.09' | '2023.02' | '2022.10' | 'null', nullable
  - `alertChannelSubscriptions` ChecksV1AlertChannelSubscription[]
    - `alertChannelId` number, required
    - `activated` boolean, required
  - `retryStrategy` ChecksV1RetryStrategy, nullable
    - `type` 'FIXED' | 'LINEAR' | 'EXPONENTIAL' | 'SINGLE_RETRY', required
    - `baseBackoffSeconds` number
    - `sameRegion` boolean
    - `maxRetries` number
    - `maxDurationSeconds` number
    - `onlyOn` string[]
  - `triggerIncident` ChecksV1TriggerIncident, nullable
    - `serviceId` string, uuid, required
    - `severity` 'CRITICAL' | 'MAJOR' | 'MEDIUM' | 'MINOR', required
    - `name` string, required
    - `description` string, required
    - `notifySubscribers` boolean, required
  - `runParallel` boolean
  - `description` string, nullable
  - `intent` object, nullable
    - `goal` string, required: The user or system outcome this check protects.
    - `requiredOutcomes` string[]: Observable outcomes the check must continue to prove.
    - `mustPreserve` string[]: Guardrails an AI repair must not weaken or bypass.
  - `aiAutoRepairEnabled` boolean, nullable
  - `id` string
  - `created_at` string, date-time
  - `updated_at` string, date-time, nullable
  - `alertChannels` ChecksV1AlertChannels, nullable
    - `email` ChecksV1AlertEmail[]
      - `address` string
    - `webhook` ChecksV1AlertWebhook[]
      - `name` string
      - `url` string
      - `method` string, nullable
      - `headers` ChecksV1KeyValue[]
        - `key` string, required
        - `value` string, required
        - `locked` boolean
      - `queryParameters` ChecksV1KeyValue[]
        - `key` string, required
        - `value` string, required
        - `locked` boolean
    - `slack` ChecksV1AlertSlack[]
      - `url` string
    - `sms` ChecksV1AlertSms[]
      - `number` string
      - `name` string, required
  - `project` ChecksV1CheckProject, nullable: The project that manages this check, or null when the check is not managed by code. When a check has more than one binding, this reports the preferred one.
    - `id` string: The ID of the project that manages this check.
    - `logicalId` string: The logical ID of the managing project, as declared in code.
    - `name` string: The name of the managing project.
  - `logicalId` string, nullable: The check's logical ID within the managing project, or null when it is not managed by code.
  - `member` boolean, nullable: True when the project owns this check, false when it merely references a check owned outside the project. Null when not managed by code. The same relationship appears structurally in `projectBindings`: an owning project under `projectBindings.owner`, a referencing one under `projectBindings.references`.
  - `pending` boolean, nullable: True when the binding is reserved by an import plan that has not been deployed yet. Null when not managed by code.
  - `projectBindings` ProjectBindingsV1: The Checkly CLI projects that manage this resource. `owner` is null and `references` empty when the resource is not managed by code.
    - `owner` ProjectBindingOwnerV1, nullable, required: The project that owns this resource — the one whose deploy can delete it. Null when no project owns it, including when other projects merely reference it. In the rare case that several projects hold an ownership record for one resource, this reports the preferred one and the rest are omitted.
      - `project` BindingProjectV1, required: The project this binding is to.
        - `id` string, required: The ID of the project.
        - `logicalId` string, required: The logical ID of the project, as declared in code.
        - `name` string, required: The name of the project.
      - `binding` ProjectBindingDetailsV1, required: The resource's side of this binding.
        - `logicalId` string, required: The resource's logical ID within this project, as declared in code.
        - `pending` boolean, required: True when the binding is reserved by an import plan that has not been deployed yet.
        - `sourceFile` string, nullable: The file in the project's repository that declares this resource, or null when not recorded.
    - `references` ProjectBindingV1[], required: Projects that use this resource without owning it; their deploys leave it alone. Empty when there are none.
      - `project` BindingProjectV1, required: The project this binding is to.
        - `id` string, required: The ID of the project.
        - `logicalId` string, required: The logical ID of the project, as declared in code.
        - `name` string, required: The name of the project.
      - `binding` ProjectBindingDetailsV1, required: The resource's side of this binding.
        - `logicalId` string, required: The resource's logical ID within this project, as declared in code.
        - `pending` boolean, required: True when the binding is reserved by an import plan that has not been deployed yet.
        - `sourceFile` string, nullable: The file in the project's repository that declares this resource, or null when not recorded.
  - `privateLocations` string[], nullable
  - `frequency` 0 | 1 | 2 | 5 | 10 | 15 | 30 | 60 | 120 | 180 | 360 | 720 | 1440
  - `frequencyOffset` integer
  - `degradedResponseTime` number, nullable
  - `maxResponseTime` number, nullable
  - `checkType` 'GRPC'
  - `request` ChecksV1GrpcRequestRead
    - `url` string
    - `port` union
      - integer
      - string
    - `ipFamily` 'IPv4' | 'IPv6' | 'null', nullable
    - `skipSSL` boolean
    - `timeout` integer, nullable
    - `grpcConfig` ChecksV1GrpcConfigRead
      - `mode` 'BEHAVIOR' | 'HEALTH'
      - `tls` boolean
      - `metadata` ChecksV1GrpcMetadataItem[]
        - `key` string, required
        - `value` string, required
      - `service` string, nullable
      - `encoding` union
        - 'PROTOBUF' | 'FLATBUFFERS'
        - ''
        - unknown
      - `bfbsContent` string, nullable
      - `serviceDefinition` union
        - 'REFLECTION' | 'PROTO_FILE'
        - ''
        - unknown
      - `method` string, nullable
      - `protoContent` string, nullable
      - `message` string, nullable
    - `assertions` ChecksV1GrpcAssertionRead[]
      - `source` 'RESPONSE_TIME' | 'GRPC_RESPONSE' | 'TEXT_BODY' | 'GRPC_METADATA' | 'GRPC_HEALTHCHECK_STATUS' | 'GRPC_STATUS_CODE'
      - `comparison` 'EQUALS' | 'NOT_EQUALS' | 'HAS_KEY' | 'NOT_HAS_KEY' | 'HAS_VALUE' | 'NOT_HAS_VALUE' | 'IS_EMPTY' | 'NOT_EMPTY' | 'GREATER_THAN' | 'LESS_THAN' | 'CONTAINS' | 'NOT_CONTAINS' | 'IS_NULL' | 'NOT_NULL'
      - `property` string
      - `target` string
      - `regex` string, nullable

## Other responses

- `400`: Bad Request
- `401`: Unauthorized
- `402`: Payment Required
- `403`: Forbidden
- `429`: Too Many Requests

## Changes

- **2026-10-31** `bc90d1bfa738`: 5 info
  - added the optional property `errorCode` to the response with the `400` status
  - added the optional property `errorCode` to the response with the `401` status
  - added the optional property `errorCode` to the response with the `402` status
  - added the optional property `errorCode` to the response with the `403` status
  - …1 more
- **2026-10-07** `aba5d34c749b`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/checklyhq/apis/checkly-public-api/changes/v1/checks/grpc/post.md)

---

[API](https://skmtc.dev/checklyhq/apis/checkly-public-api.md) - [All operations](https://skmtc.dev/checklyhq/apis/checkly-public-api/llms.txt) - [OpenAPI document](https://skmtc.dev/checklyhq/apis/checkly-public-api/revisions/bc90d1bfa738?raw)