Stay organized with collections
Save and categorize content based on your preferences.
Monitor reCAPTCHA metrics
This document describes the reCAPTCHA metrics that your
Identity Platform emits as a result of the Identity Platform integration with the reCAPTCHA Enterprise API and how to
view them with Cloud Monitoring.
If you've enabled reCAPTCHA bot protection or reCAPTCHA SMS defense in
audit mode, monitoring the reCAPTCHA metrics will help you
determine if you can enable enforcement. You should consider the following
before enabling enforcement:
If the majority of recent requests have valid tokens and the ratio of PASSED
to FAILED_AUDIT or FAILED_ENFORCE verdicts is acceptable for your business
case, consider enabling enforcement.
If a majority of the recent requests are likely from outdated clients,
consider waiting for more users to update their app before enabling
enforcement. Enforcing Identity Platform integration with the reCAPTCHA Enterprise API breaks prior app versions
that are not integrated with reCAPTCHA.
To ensure that the integration features are working as intended, you can examine
the following metrics your project emits to Cloud Monitoring.
This metric tracks the different verdicts returned by reCAPTCHA. A
verdict is generated if a token is present. You can filter on the following
verdicts:
PASSED: Indicates that a given request is allowed when enforcement is enabled.
FAILED_AUDIT: Indicates that a given request is denied when
reCAPTCHA audit mode is enabled.
FAILED_ENFORCE: Indicates that a given request is denied when
reCAPTCHA enforcement mode is enabled.
CLIENT_TYPE_MISSING: Indicates that a given request has a missing client
type when reCAPTCHA enforcement is enabled. This error
typically occurs if a request was sent using an outdated client SDK
version that does not have reCAPTCHA support.
KEYS_MISSING: Indicates that a given request can't be verified because
Identity Platform can't retrieve valid reCAPTCHA keys when
reCAPTCHA enforcement is enabled.
This metric tracks the number and status of reCAPTCHA tokens received
by the Identity Platform backend. You can filter on the following statuses:
VALID: Indicates that the reCAPTCHA token passed in is valid.
EXPIRED: Indicates that the reCAPTCHA token passed in has
expired. An expired token might indicate client network issues or abuse.
DUPLICATE: Indicates that the reCAPTCHA token passed in is a
duplicate. A duplicate token might indicate client network issues or abuse.
INVALID: Indicates that the reCAPTCHA token passed in is
invalid. An invalid token might indicate abuse.
MISSING: Indicates that the reCAPTCHA token doesn't exist in
the given request. Missing tokens might indicate an outdated client app.
UNCHECKED: Indicates that the reCAPTCHA token was not checked
due to CLIENT_TYPE_MISSING or KEYS_MISSING verdicts.
If your app rolled out successfully to users, you will see traffic with valid
tokens. The number of valid tokens is likely proportional to the number of users
who are using your updated app.
This metric tracks the reCAPTCHA SMS defense risk score
distribution for a particular Identity Platform project. This can help you define the optimal score ranges for your reCAPTCHA SMS defense configuration.
View reCAPTCHA metrics
To view the reCAPTCHA metrics with Cloud Monitoring, do the
following:
In the Google Cloud console, go to the Metrics explorer page.
From Select a metric, enter Identity Toolkit Tenant. If you are
using multi-tenancy, you can view metrics for each tenant, as well as the
parent project, by leaving tenant_name empty.
[[["Easy to understand","easyToUnderstand","thumb-up"],["Solved my problem","solvedMyProblem","thumb-up"],["Other","otherUp","thumb-up"]],[["Hard to understand","hardToUnderstand","thumb-down"],["Incorrect information or sample code","incorrectInformationOrSampleCode","thumb-down"],["Missing the information/samples I need","missingTheInformationSamplesINeed","thumb-down"],["Other","otherDown","thumb-down"]],["Last updated 2025-08-29 UTC."],[[["\u003cp\u003eThis document details how to monitor reCAPTCHA metrics emitted by Identity Platform after integrating with the reCAPTCHA Enterprise API, including optional SMS toll fraud protection.\u003c/p\u003e\n"],["\u003cp\u003eThe \u003ccode\u003eidentitytoolkit.googleapis.com/recaptcha/verdict_count\u003c/code\u003e metric tracks verdicts like \u003ccode\u003ePASSED\u003c/code\u003e, \u003ccode\u003eFAILED_AUDIT\u003c/code\u003e, \u003ccode\u003eFAILED_ENFORCE\u003c/code\u003e, \u003ccode\u003eCLIENT_TYPE_MISSING\u003c/code\u003e, and \u003ccode\u003eKEYS_MISSING\u003c/code\u003e, which indicate the success or failure of reCAPTCHA checks.\u003c/p\u003e\n"],["\u003cp\u003eThe \u003ccode\u003eidentitytoolkit.googleapis.com/recaptcha/token_count\u003c/code\u003e metric tracks the status of reCAPTCHA tokens received, including \u003ccode\u003eVALID\u003c/code\u003e, \u003ccode\u003eEXPIRED\u003c/code\u003e, \u003ccode\u003eDUPLICATE\u003c/code\u003e, \u003ccode\u003eINVALID\u003c/code\u003e, \u003ccode\u003eMISSING\u003c/code\u003e, and \u003ccode\u003eUNCHECKED\u003c/code\u003e statuses.\u003c/p\u003e\n"],["\u003cp\u003eMonitoring \u003ccode\u003eidentitytoolkit.googleapis.com/recaptcha/risk_scores\u003c/code\u003e and \u003ccode\u003eidentitytoolkit.googleapis.com/recaptcha/sms_tf_risk_scores\u003c/code\u003e helps define optimal score ranges for bot and SMS toll fraud protection configurations.\u003c/p\u003e\n"],["\u003cp\u003eTo view these metrics, you can access the Metrics Explorer in the Google Cloud console and search for "Identity Toolkit Tenant".\u003c/p\u003e\n"]]],[],null,["# Monitor reCAPTCHA metrics\n=========================\n\nThis document describes the reCAPTCHA metrics that your\nIdentity Platform emits as a result of the Identity Platform integration with the reCAPTCHA Enterprise API and how to\nview them with Cloud Monitoring.\n\nreCAPTCHA metrics\n-----------------\n\nAfter you [set up the\nIdentity Platform integration with the reCAPTCHA Enterprise API](/identity-platform/docs/recaptcha-enterprise), and\noptionally, [enable\nreCAPTCHA SMS defense](/identity-platform/docs/recaptcha-tfp), you\ncan monitor the reCAPTCHA metrics your project emits to ensure\nthat your authentication flows are protected. If reCAPTCHA\nkey provisioning fails or if required service accounts weren't created,\nreCAPTCHA authentication fails open.\n\nIf you've enabled reCAPTCHA bot protection or reCAPTCHA SMS defense in\naudit mode, monitoring the reCAPTCHA metrics will help you\ndetermine if you can enable enforcement. You should consider the following\nbefore enabling enforcement:\n\n- If the majority of recent requests have valid tokens and the ratio of `PASSED` to `FAILED_AUDIT` or `FAILED_ENFORCE` verdicts is acceptable for your business case, consider enabling enforcement.\n- If a majority of the recent requests are likely from outdated clients, consider waiting for more users to update their app before enabling enforcement. Enforcing Identity Platform integration with the reCAPTCHA Enterprise API breaks prior app versions that are not integrated with reCAPTCHA.\n\nTo ensure that the integration features are working as intended, you can examine\nthe following metrics your project emits to Cloud Monitoring.\n\n### `identitytoolkit.googleapis.com/recaptcha/verdict_count`\n\nThis metric tracks the different verdicts returned by reCAPTCHA. A\nverdict is generated if a token is present. You can filter on the following\nverdicts:\n\n- `PASSED`: Indicates that a given request is allowed when enforcement is enabled.\n- `FAILED_AUDIT`: Indicates that a given request is denied when reCAPTCHA audit mode is enabled.\n- `FAILED_ENFORCE`: Indicates that a given request is denied when reCAPTCHA enforcement mode is enabled.\n- `CLIENT_TYPE_MISSING`: Indicates that a given request has a missing client type when reCAPTCHA enforcement is enabled. This error typically occurs if a request was sent using an outdated client SDK version that does not have reCAPTCHA support.\n- `KEYS_MISSING`: Indicates that a given request can't be verified because Identity Platform can't retrieve valid reCAPTCHA keys when reCAPTCHA enforcement is enabled.\n\nTo modify your score ranges to change the ratio of passed-to-failed verdicts,\nsee [Enable reCAPTCHA bot protection](/identity-platform/docs/recaptcha-enterprise#enable).\n\n### `identitytoolkit.googleapis.com/recaptcha/token_count`\n\nThis metric tracks the number and status of reCAPTCHA tokens received\nby the Identity Platform backend. You can filter on the following statuses:\n\n- `VALID`: Indicates that the reCAPTCHA token passed in is valid.\n- `EXPIRED`: Indicates that the reCAPTCHA token passed in has expired. An expired token might indicate client network issues or abuse.\n- `DUPLICATE`: Indicates that the reCAPTCHA token passed in is a duplicate. A duplicate token might indicate client network issues or abuse.\n- `INVALID`: Indicates that the reCAPTCHA token passed in is invalid. An invalid token might indicate abuse.\n- `MISSING`: Indicates that the reCAPTCHA token doesn't exist in the given request. Missing tokens might indicate an outdated client app.\n- `UNCHECKED`: Indicates that the reCAPTCHA token was not checked due to `CLIENT_TYPE_MISSING` or `KEYS_MISSING` verdicts.\n\nIf your app rolled out successfully to users, you will see traffic with valid\ntokens. The number of valid tokens is likely proportional to the number of users\nwho are using your updated app.\n\n### `identitytoolkit.googleapis.com/recaptcha/risk_scores`\n\nThis metric tracks the reCAPTCHA score distribution. This can\nhelp you define the optimal score ranges for your bot protection configuration.\n\n### `identitytoolkit.googleapis.com/recaptcha/sms_tf_risk_scores`\n\nThis metric tracks the reCAPTCHA SMS defense risk score\ndistribution for a particular Identity Platform project. This can help you define the optimal score ranges for your reCAPTCHA SMS defense configuration.\n\nView reCAPTCHA metrics\n----------------------\n\nTo view the reCAPTCHA metrics with Cloud Monitoring, do the\nfollowing:\n\n1. In the Google Cloud console, go to the **Metrics explorer** page.\n\n [Go to Metrics explorer](https://console.cloud.google.com/monitoring/metrics-explorer)\n2. From **Select a metric** , enter **Identity Toolkit Tenant** . If you are\n using multi-tenancy, you can view metrics for each tenant, as well as the\n parent project, by leaving `tenant_name` empty.\n\nWhat's next\n-----------\n\n- Learn how to [troubleshoot common\n issues](/identity-platform/docs/recaptcha-troubleshooting) with the reCAPTCHA integration."]]
