User Profilesのenforcement_statusで制限・BANを確かめる手順
User Profilesのenforcement_statusとenforcement_actionsで、エンドユーザーが制限・BANされたかを調べる手順。一覧フィルタ、ベータヘッダーの落とし穴、webhookとの併用までまとめます。
User Profilesのenforcement_statusで制限・BANを確かめる手順
自社サービスの利用者がClaudeの利用制限やBANを受けたかどうかは、User Profilesの enforcement_status と enforcement_actions の2項目で分かります。プロファイルを1件取得して読むか、一覧を enforcement_status[]=restricted と enforcement_status[]=banned で絞れば、制限中の利用者だけを洗い出せます。
ただし、ここには落とし穴が1つあります。既存コードに user-profiles- 系のベータヘッダーが残っていると、この2項目はレスポンスに出てきません。最初に確かめるのはそこです。
2項目はどのリクエストにも付いてくる
enforcement_status と enforcement_actions は、プロファイルを返す全レスポンスに含まれます。作成、取得、更新、そして一覧の各プロファイルです。
ここでいうenforcement actionは、Anthropicが利用者に対して開く「制限(restriction)」か「BAN(ban)」を指します。プロファイル単位で付くので、プロファイルIDをヘッダーに載せてリクエストしている限り、制限の影響は該当の利用者にとどまり、組織全体の他のトラフィックには及びません。
プロファイルの作り方とヘッダーの付け方は、Claude APIのUser Profilesでエンドユーザーを識別する手順にまとめています。この記事は、その後の「制限されたかを確かめる」段階を扱います。
ベータヘッダーにuser-profilesの値が残っていないか
落とし穴
user-profiles-2026-09-04 以前のヘッダーでは項目が返らない
anthropic-beta ヘッダーに user-profiles-2026-09-04 かそれ以前の user-profiles- 系の値を載せていると、レスポンスから enforcement_status と enforcement_actions が抜けます。一覧のフィルタ enforcement_status[] も 400 を返します。項目を受け取るには、リクエストからその値を外します。
external_user_details を使うために user-profiles-2026-09-04 を付けている場合、そのままではこの2項目が見えません。ヘッダーを外すときは、external_user_details を含む既存の項目がレスポンスにどう出るかを、手元のプロファイル1件で見比べてから本番に入れると安全です。ベータヘッダーの書式そのものはClaude APIでanthropic-betaヘッダーを使う方法で説明しています。
enforcement_statusの3つの値
enforcement_status は、いま開いている制限をまとめた1つの値です。
| 値 | 意味 |
|---|---|
unrestricted | 意味開いている措置がない |
restricted | 意味措置が1つ以上開いていて、BANは含まれない |
banned | 意味BANが開いている |
措置が開いている間、AnthropicはそのプロファイルのIDを載せた推論リクエストの一部または全部を拒否します。restricted でも、すべてのリクエストが止まるとは限りません。
enforcement_actions は、開いている措置の配列です。何も開いていなければ空になり、終わった措置は配列から消えます。履歴は残らないので、過去に制限されたかどうかを後から調べる用途には向きません。履歴が必要なら、webhookのイベントや一覧の取得結果を自社側で保存しておきます。
措置1件に入っている6項目
enforcement_actions の各要素には、次の6項目があります。
| 項目 | 内容 |
|---|---|
type | 内容restriction か ban |
id | 内容措置のID。enac_ で始まる |
reason | 内容開いた理由 |
action | 内容利用者が解除のためにできること。なければ null |
opened_at | 内容開いた日時 |
expires_at | 内容自動で終わる日時。期限がなければ null |
reason に入る値は6種類です。
unsupported_regionfraud_or_abusehigh_harmusage_policy_violationaccount_compromiseunspecified
ドキュメントの例では、restricted のプロファイルに reason が fraud_or_abuse、action と expires_at がどちらも null の restriction が1件載っています。解除のために利用者ができることがなく、期限もない措置です。この組み合わせが出たら、利用者に案内できる手順は無い、と読むことになります。
action が文字列で入っている場合は、利用者がやるべきことの説明です。サービスの画面やメールに転記して案内する材料になります。
1件を調べる: プロファイルを取得する
特定の利用者の状態を見るには、保存してあるプロファイルIDで取得します。
curl https://api.anthropic.com/v1/user_profiles/uprof_011CZkZCu8hGbp5mYRQgUmz9 \
-H 'anthropic-version: 2023-06-01' \
-H "X-Api-Key: $ANTHROPIC_API_KEY"この例では anthropic-beta ヘッダーを送りません。user-profiles- の値を載せないことで2項目が返る形にしています。レスポンスの該当部分は、例に沿うと次の形になります。
{
"type": "user_profile",
"id": "uprof_011CZkZCu8hGbp5mYRQgUmz9",
"enforcement_status": "restricted",
"enforcement_actions": [
{
"type": "restriction",
"id": "enac_011CZkZEq4TnWb7xLfRgPm2v",
"reason": "fraud_or_abuse",
"action": null,
"opened_at": "2026-10-02T19:30:00Z",
"expires_at": null
}
]
}制限中のプロファイルをまとめて一覧する
利用者が多いサービスでは、1件ずつ取得するより、制限中だけを一覧で引くほうが現実的です。一覧エンドポイントに enforcement_status[] を2回指定します。
curl -g 'https://api.anthropic.com/v1/user_profiles?enforcement_status[]=restricted&enforcement_status[]=banned' \
-H 'anthropic-version: 2023-06-01' \
-H "X-Api-Key: $ANTHROPIC_API_KEY"restricted と banned の両方を指定するのがポイントです。片方だけでは、もう片方の利用者が漏れます。-g は、curlが角括弧を範囲指定として解釈しないようにするためのオプションです。
ページ送りには注意点があります。絞り込み後の一覧は、limit より少ない件数、あるいは0件のページが返っても、まだ終わりとは限りません。next_page が null になるまでリクエストを続けます。1ページ目が空だからといって「制限中の利用者はいない」と判断しないでください。
webhookの通知だけでは足りない理由
制限が開いた、あるいは終わったときにイベントを受け取るには、Organization webhooksを使います。対象のイベントは2種類です。
| イベント | 発火する場面 |
|---|---|
user_profile.enforcement_action_opened | 発火する場面Anthropicが措置を開いた |
user_profile.enforcement_action_resolved | 発火する場面措置が終わった(Anthropicが解決、または expires_at が過ぎた) |
ただし、webhookだけに頼ると取りこぼしが出ます。ドキュメントに書かれている穴は次の4つです。
- 組織でイベント配信が有効になる前、またはエンドポイントを登録する前に開いた措置のイベントは届きません。措置自体はプロファイルに残ります。
- 配信に失敗すると、Anthropicは数分のあいだ数回再送します。それでも全部失敗するとイベントは破棄されます。
- イベントは遅れたり、順序が入れ替わったりすることがあります。
- プロファイルを削除すると、開いていた措置は
resolvedのイベントなしで終わります。
最初の2つは、先ほどの一覧フィルタで補えます。見逃した措置を探す手段としても、同じ一覧の使い方が挙げられています。運用としては、webhookで即時に気づき、定期的な一覧で取りこぼしを拾う構成にします。
イベントの本文には、措置の内容そのものは入っていません。data.id にプロファイルのID、data.enforcement_action_id に措置のIDが入るだけです。何が起きたかを知るには、受け取ったIDでプロファイルを取得し直します。到着順より、取得したプロファイルの現在の状態を信頼する、という方針です。取得が 404 なら、そのプロファイルは削除されています。
なお、webhooks-2026-10-07 というベータヘッダーが付いたベータ機能です。エンドポイントの登録手順はOrganization webhooksのページにあります。
書き込めない項目と、account_statusとの違い
この2項目はAnthropicだけが設定します。作成や更新のリクエストに含めると 400 が返ります。自社側の判断を記録したいなら、external_user_details.account_status(active / suspended / blocked)を使います。こちらは自社の決定を残す項目で、enforcement_status とは別物です。
つまり、利用者を自社で止めたときは account_status を更新し、Anthropicに止められたかどうかは enforcement_status で見る、という使い分けになります。両方が食い違うこともあるので、画面や管理ツールには別々の列で出すと混乱しません。
変化の検知にupdated_atは使えない
イベントを使わず自前で監視する場合、updated_at の変化を見ても検知できません。措置の変化で updated_at が確実に動くとは限らないためです。enforcement_status と enforcement_actions の両方を、前回保存した値と比べます。
比較する値は次の2つです。
enforcement_statusの文字列enforcement_actionsの各要素のid
IDまで比べると、同じ restricted のまま措置が入れ替わったケースも拾えます。
想定外の値が来たときの扱い
値は今後増えることがあります。知らない値が来たときの読み替えは決まっています。
| フィールド | 知らない値が来たら |
|---|---|
enforcement_status | 知らない値が来たらrestricted として扱う |
type | 知らない値が来たらrestriction として扱う |
reason | 知らない値が来たらunspecified として扱う |
action | 知らない値が来たらnull として扱う |
コードでは、switch文の既定の分岐にこの読み替えを書いておけば足ります。未知の enforcement_status を unrestricted として扱うと、制限中の利用者を見逃すからです。いずれも「より厳しい側に倒す」方向で揃っています。
環境によって意味が変わる
使うプラットフォームによって、この2項目の意味が変わります。
- Claude Platform on AWS:
enforcement_statusは常にunrestricted、enforcement_actionsは常に空です。Anthropicは、開いている措置を理由にそこでリクエストを拒否しません。値が空でも「制限されていない」証拠にはなりません。 - Claude in Amazon BedrockとClaude Models on Google Cloud:
/v1/user_profilesのエンドポイント自体がありません。プロファイルはClaude APIの組織かClaude Platform on AWSで作ります。さらにこの2つは、プロファイルIDの形式を検査するだけで、実在を照合しません。形式が正しければどんなIDでも受け付けるため、リクエストが成功してもIDが正しいプロファイルに結びついたとは言えません。
IDを付け忘れたリクエストは、どの環境でも自組織全体の利用として扱われます。そこで措置が開くと、組織全体に適用されます。Bedrock/Google Cloudではさらに、形式が正しい誤IDも通ってしまいます。エンドユーザーのトラフィックには、必ず正しいIDを付けます。
点検の流れをまとめる
導入済みのサービスで制限状況を確かめるなら、次の順で進めます。
制限状況を確かめる5段階
- 1
ベータヘッダーを見直す
リクエストから
user-profiles-系の値を外します。 - 2
一覧で全体像をつかむ
enforcement_status[]にrestrictedとbannedを指定し、next_pageがnullになるまで取得します。 - 3
該当の利用者を個別に確認する
プロファイルを取得し、
reason、action、expires_atを読みます。 - 4
webhookを登録する
以後の変化は
opened/resolvedのイベントで受け取ります。 - 5
定期的に一覧で突き合わせる
通知の取りこぼしを、保存済みの値との比較で拾います。
まとめ
enforcement_status を見る前に、ベータヘッダーの user-profiles- 系の値を外すことが前提です。そのうえで、一覧の絞り込みは restricted と banned の2値で漏れなく引き、ページ送りは next_page が null になるまで続けます。通知はwebhookで受けつつ、定期的な一覧との突き合わせで取りこぼしを埋めると、制限状況を取り違えにくくなります。Claude Platform on AWSでは常に unrestricted が返るので、その環境ではこの値を安全の根拠にできず、利用者の管理は別の仕組みで持つ必要があります。