ZendeskのSLA違反をClaudeで月次分析する手順 — 超過要因の切り分け
sla_policiesの目標値とticket_metric_eventsの違反イベントを突き合わせ、曜日・時間帯・担当グループ別にSLA超過の要因をClaude Codeで月次に切り分ける手順です。
ZendeskのSLA違反を月次で振り返るには、目標値を持つsla_policiesと、違反が起きた事実を持つticket_metric_eventsの2つを突き合わせます。そこにチケット側の優先度・担当グループ・作成時刻を足してCSVにまとめれば、曜日・時間帯・グループ別の超過をClaude Codeに集計させられます。
この記事では、データの取り方、突き合わせの注意点、Claudeへの指示、結果の読み方を順に説明します。
SLA違反の分析に必要なデータは3種類ある
「どの優先度のどの目標を、いつ、どのグループが落としたか」を自由な軸で切るには、APIから行単位で取り、手元で切り直すのが確実です。必要なのは次の3種類です。
月次分析に使う3つのデータ
SLAポリシー(目標値)
GET /api/v2/slas/policiesで取ります。優先度ごとの目標を分単位で持ちます。メトリックイベント(違反の事実)
GET /api/v2/incremental/ticket_metric_eventsで取ります。breachなど、いつ何が起きたかの履歴です。チケット本体(切り口)
GET /api/v2/incremental/tickets/cursorで取ります。優先度・グループ・担当・作成時刻など、集計の軸になります。
SLAポリシー系のAPIは、Support ProfessionalまたはSuite Growth以上のプランで、管理者だけが呼べます。権限が足りないと取得の段階で止まるため、先に確認しておくと手戻りがありません。
目標値はポリシーの中に入っている
SLAポリシーは、適用条件(filter)と、優先度ごとの目標(policy_metrics)の組です。目標は1件ごとにpriority・metric・target(分単位)・business_hoursを持ちます。
{
"priority": "low",
"metric": "first_reply_time",
"target": 60,
"business_hours": false
}business_hoursがtrueなら営業時間で、falseなら暦時間(24時間365日)で測ります。ここを取り違えると、夜間や休日の扱いが分析全体でずれます。ポリシーが複数あるときは、positionで決まる順に照合されます。
指標名がAPIによって違う
分析で最初につまずくのが指標名です。ポリシー側とイベント側で、同じ種類の指標が別の名前で出てきます。
| 測りたいもの | ポリシー側(metric) | イベント側(metric) |
|---|---|---|
| 初回応答 | ポリシー側(metric)first_reply_time | イベント側(metric)reply_time |
| 完全解決 | ポリシー側(metric)total_resolution_time | イベント側(metric)resolution_time |
| 依頼者の待ち時間 | ポリシー側(metric)requester_wait_time | イベント側(metric)requester_wait_time |
| 担当者の作業時間 | ポリシー側(metric)agent_work_time | イベント側(metric)agent_work_time |
ポリシー側の指標は他にnext_reply_time・pausable_update_time・periodic_update_timeがあります。両APIの指標一覧には対応関係の記載が無いため、表は名前と定義から対応させています。突き合わせの前にClaudeへ対応表を渡しておけば、名前の不一致で結合が空振りするのを防げます。
違反の事実はticket_metric_eventsに入っている
メトリックイベントは、チケットごとの指標の動きを時系列で記録したものです。種類にはactivate・fulfill・pause・apply_sla・apply_group_sla・breach・update_statusなどがあり、SLA分析で使うのは主に次の3つです。
apply_sla: SLAポリシーと目標が適用された。slaオブジェクトに目標分数・営業時間か暦時間か・ポリシーのID/タイトルが入るbreach: 目標を超過したfulfill: 目標内に満たされた(初回返信、解決など)
breachのtimeは「超過した瞬間」で、チケットの作成時刻ではありません。ここが分析設計の分かれ目です。「いつ起票されたチケットが落ちやすいか」を見たいなら、breachのチケットIDでチケット本体のcreated_atを引き直します。「いつ違反が表に出るか」(運用上の山)を見たいなら、breachのtimeをそのまま使います。2つは別の問いなので、月次報告では両方並べるのが無難です。
イベントのtimeはZ付きのUTC表記で返ります。日本の曜日・時間帯で切るなら、集計の前にJSTへ変換する指示を忘れずに入れます。deletedがtrueのイベントは無視してよいとされているため、除外も指示に含めます。
月次エクスポートの取り方
増分エクスポートは、start_time(Unixエポック秒)を指定して取り始めます。start_timeは1分以上前でなければならず、直近1分のデータは返りません。
- イベント:
GET /api/v2/incremental/ticket_metric_events?start_time=...。カーソルページネーションで1ページ最大100件 - チケット:
GET /api/v2/incremental/tickets/cursor?start_time=...。1ページ最大1,000件(per_pageで減らせる)。2回目以降はcursorを使う - レート制限: 増分エクスポート系は1分あたり10リクエストまで
月次運用では、前月1日0時(JST)をエポック秒にしてstart_timeに入れ、翌月1日で打ち切ります。次は取得の骨組みの例です。実環境のレスポンスは自分のアカウントで確かめてください。
# 前月1日0時(JST)のエポック秒を計算(macOSのdate。GNU dateなら
# START=$(TZ=Asia/Tokyo date -d "2026-09-01 00:00:00" +%s))
START=$(TZ=Asia/Tokyo date -j -f "%Y-%m-%d %H:%M:%S" \
"2026-09-01 00:00:00" +%s)
# メトリックイベントの1ページ目
curl -s "https://$ZD_SUBDOMAIN.zendesk.com/api/v2/incremental/ticket_metric_events?start_time=$START" \
-H "Authorization: Bearer $ZD_ACCESS_TOKEN" \
-o events_page1.jsonレスポンスにはcount・end_time・next_page・ticket_metric_eventsが入ります。next_pageをたどって取り続け、各ページを1つのCSVに追記する短いスクリプトをClaude Codeに書かせると手数が減ります。
チケット側は、指標の実績をまとめて持つmetric_setsをサイドロードする手があります(include=metric_sets)。初回応答までの分(reply_time_in_minutes)や完全解決までの分(full_resolution_time_in_minutes)が、暦時間と営業時間の両方で付くため、違反の「超過幅」を出したいときに役立ちます。
個人情報を落としてからClaudeに渡す
チケットの件名や本文には、顧客の氏名・連絡先・注文番号が入ります。SLA分析に必要なのは、IDと時刻と属性だけです。取得したデータは、次の列だけを残したCSVにしてから渡します。
| 残す列 | 用途 |
|---|---|
ticket_id | 用途イベントとの結合キー |
priority | 用途優先度別の目標との対応 |
group_id / assignee_id | 用途担当別の切り口(IDのまま。氏名は渡さない) |
created_at | 用途起票の曜日・時間帯 |
breach_time / metric | 用途違反の時刻と指標 |
target_minutes / business_hours | 用途適用されていた目標 |
| カテゴリ(チケットフォームやカスタムフィールドの値) | 用途カテゴリ別の切り口 |
件名や本文を使ってカテゴリを自動で振り分けたい場合は、社内のデータ取り扱いルールに沿って、別の工程で行います。月次のSLA分析だけなら、既存のカテゴリ項目で足ります。
Claude Codeに集計させる
CSVができたら、作業フォルダでClaude Codeを起動し、集計の前提をCLAUDE.mdに書いておきます。月ごとに同じ前提を貼り直さずに済みます。
# SLA月次分析のルール
- 時刻はすべてUTCで入っている。集計前にAsia/Tokyoへ変換する
- deleted が true のイベントは捨てる
- 指標名の対応: first_reply_time=reply_time, total_resolution_time=resolution_time
- business_hours が true の目標は営業時間、false は暦時間で測られている。混ぜて平均しない
- 結果は必ず「分母(チケット数)」と「違反数」を併記する
- 原因の断定はしない。偏りを数値で示し、確認すべき仮説として書くそのうえで、指示は次の順に出します。
events.csvとtickets.csvをticket_idで結合し、結合できなかった行の件数を最初に報告させる- 指標×優先度ごとに、違反率(違反数÷対象チケット数)を出させる
- 起票の曜日×時間帯のヒートマップ用の表と、違反時刻の曜日×時間帯の表を別々に作らせる
- グループ・担当・カテゴリ別の違反率を出させ、母数が小さい行(例: 10件未満)を分けて示させる
- 上位3つの偏りについて、検証用に確認すべきチケットIDの一覧を出させる
結合件数の確認を最初に置く理由は、削除済みチケットや範囲外の起票が混ざると、違反率の分母がずれるためです。結合に失敗した行を握りつぶしたまま集計が進むと、エラーを出さずに数字だけがずれます。
計算結果は一度手元で検算する
Claude Codeは集計コードを書いて実行するため、結果の数字はコードの出力として出ます。それでも、違反総数だけは管理画面のSLAレポートや、イベントのbreach件数のワンライナー集計と一致するか確かめてください。ずれたときは、結合キーの欠落か、deletedの除外漏れが典型です。
結果から超過要因を読む
集計表が出たら、要因を次の3系統に分けて読みます。
偏りの出方から疑う要因
時間帯・曜日に偏る
特定の曜日や夕方に違反が集まるなら、シフトの穴や、営業時間外との境界が疑わしい。business_hoursがfalseの目標が夜間に落ちていないかも見ます。
グループ・担当に偏る
特定のグループだけ違反率が高いなら、割り当てルールやスキル不足が候補です。母数が少ない担当は、偶然の揺れを疑います。
カテゴリに偏る
特定カテゴリの解決時間が長いなら、手順書の不足やエスカレーション先の遅れが候補です。
注意したいのは、偏りは原因の証拠ではなく、調べる順番を決める手がかりという点です。たとえば夕方に違反が多くても、その時間に問い合わせが集中しているだけで、体制は十分かもしれません。人員の過不足を試算する段階に進むなら、コールセンターのErlang C計算をExcelで行う手順が続きの作業になります。
Claudeに依頼するときは、「この偏りが起きうる理由を3つ挙げ、それぞれを確かめるために見るべきチケットIDを選べ」と頼みます。理由の列挙は仮説づくりに有効ですが、確定は実際のチケットのやり取りを読んで行います。ここを飛ばして「原因はシフト不足です」と月次報告に書くと、翌月の施策が外れます。
月次運用に載せるときの確認点
- ポリシーを途中で変えた月:
apply_slaイベントは、ポリシーや目標が変更された時点でも発生します。月の途中で目標を変えた場合、違反率の前月比較は目標の差を含みます。月次表に「その月に適用されていた目標」を併記します - グループSLA:
apply_group_slaは通常のSLAとは別イベントです。グループSLAを使っているアカウントでは、通常のSLAと混ぜずに集計します - レート制限: 増分エクスポートは1分10リクエストです。件数の多いアカウントでは、取得が数分かかる前提で夜間のジョブにします
- 取得のやり直し:
start_timeは任意の過去時点から指定できるので、数字に疑義が出た月は同じ範囲を取り直して比較できます
チケット本体の分析や返信下書きは、Zendeskチケット分析の記事が扱っています。MCPでZendeskにつなぐ方法はClaude Zendesk連携に、インシデント発生時のSLA監視をCoworkで自動化する話はPagerDutyとCoworkのSLA監視にあります。月次の差異を数字で説明する型は、月次予実対比レポートの進め方と共通です。
よくある質問
SLAポリシーをAPIで変更してよいか
PUT /api/v2/slas/policies/{id}で更新できます。ただし分析用のアクセストークンは読み取り専用にして、ポリシーの作成・更新・削除を呼べない権限にしておくのが無難です。Claude Codeに渡す認証情報は、書き込みを許可しない運用が事故を防ぎます。
まとめ
SLA違反の月次分析は、目標(sla_policies)・事実(ticket_metric_events)・切り口(チケット)の結合に尽きます。指標名の食い違い、UTCからJSTへの変換、営業時間と暦時間の混在の3つをCLAUDE.mdで固定すれば、Claude Codeの集計は月が変わっても同じ形で回ります。
出てくるのは偏りであって原因ではありません。上位の偏りから確認チケットを抜き、実際のやり取りを読んで裏を取るところまでを、毎月の手順に含めてください。