Datadog APIの実装手順｜2種類のキーの権限分離とモニター操作・429対策

Datadog APIを叩き始めて最初に手が止まるのは、たいてい認証です。キーを1本作ってヘッダーに入れたのに、モニター一覧の取得だけ403が返る。原因はキーが2種類あり、読み取り系には片方だけでは足りないところにあります。ここを理解したうえで、どのエンドポイントを使い、権限をどこまで絞り、レート制限にどう備えるか。2026年8月時点の公式ドキュメントをもとに、実装目線で順に整理します。

まとめ：Datadog API利用で先に決めるキー設計と自動化の範囲

結論を先に置きます。コードを書く前に決めるのは3つです。どのキーを誰の名義で持つか、どのサイトのAPIホストへ送るか、そして何をAPIで動かし何をTerraformに任せるか。この3点が曖昧なまま実装を始めると、動いた後に権限の付け直しとキーの配り直しが発生します。

キーの持ち方から述べます。個人アカウントに紐づくアプリケーションキーを自動化に使わないでください。担当者のアカウントが無効化されると、そのアプリケーションキーは失効し、夜間バッチだけが静かに止まります。サービスアカウントに保有させるのが既定解です。

使い分けの線引きも先に示します。モニターやダッシュボードのように恒久的に存在し続ける設定はTerraformへ寄せる。メトリクス送信、障害時の一括ミュート、調査のための時系列取り出しといった一過性の操作はAPIを直接叩く。この境界を最初に引いておくと、同じモニターをUIとコードの両方から書き換えて設定が巻き戻る事故を防げます。根拠と例外は判断章に書きます。

APIキーとアプリケーションキーの役割分担と認証ヘッダーの渡し方

Datadogの認証は2階建てです。片方だけで通るエンドポイントと、両方そろわないと通らないエンドポイントがあります。この構造を先に押さえると、401と403の切り分けが一瞬で終わります。

APIキーが担う送信とアプリケーションキーが担う読み取りの境界

APIキーは組織に紐づく識別子で、Datadog Agentがメトリクスやイベントを送るときにも同じものを使います。データを書き込む方向のリクエストは、このAPIキーだけで通ります。一方、モニターの一覧取得やダッシュボードの読み出しといった読み取り・設定変更系は、APIキーに加えてアプリケーションキーが必要です。

アプリケーションキーはユーザー（またはサービスアカウント）に紐づき、そのユーザーが持つ権限の範囲でしか動きません。つまりキーを渡しただけでは足りず、名義側のロール設計まで含めて権限が決まります。403が返ったときに疑うのはキーの有無ではなく、名義の権限です。

DD-API-KEYとDD-APPLICATION-KEYを渡すヘッダー構成と疎通確認

認証情報はクエリ文字列ではなくHTTPヘッダーで渡します。APIキーはDD-API-KEY、アプリケーションキーはDD-APPLICATION-KEYという名前のヘッダーです。読み取り系ではこの2本を同時に付けます。

実装前の疎通確認には検証専用のエンドポイントが有効です。GET /api/v1/validate はAPIキーのみで通るため、キーが有効かどうかだけを単独で確かめられます。新しく発行したキーは反映まで数秒かかるとされており、CIでキーを差し替えた直後に本処理へ入ると失敗することがあります。差し替え後はこの検証エンドポイントが通るまで待ってから先へ進める作りにしてください。

サイト別APIホスト名の違いと送信先取り違えで起きる無反応の症状

Datadogはリージョンごとにサイトが分かれており、APIホスト名も別です。US1はapi.datadoghq.com、US3はapi.us3.datadoghq.com、US5はapi.us5.datadoghq.com、EUはapi.datadoghq.eu、日本から使うことの多いAP1はapi.ap1.datadoghq.com、AP2はapi.ap2.datadoghq.com、英国はapi.uk1.datadoghq.com、米政府向けはapi.ddog-gov.comです。

取り違えたときの症状がやっかいです。AP1の組織で発行したキーをUS1のホストに向けると、キーが不正だという扱いになり、画面には何も届きません。Agent側でも同種の事故が起きるため、送信先の指定は収集経路と揃えておくと調査が短くなります。Agent側の設定はDatadog Agent導入の実装手順で扱っています。

キー発行と権限スコープ設定の手順・サービスアカウントでの保有方針

キーは作れてしまうため、作り方より「誰が持ち、どこまでできるか」の設計が実務の本体になります。ここを詰めずに配ると、退職や棚卸しのたびに自動化が止まります。

組織あたり50本というAPIキーの上限と失効後7日間の復元可否

APIキーは既定で1組織あたり50本までとされています。上限の引き上げはサポート経由で相談する形です。Datadogが管理する種類のAPIキーはこの本数に数えられません。50という数字は、環境ごと・用途ごとに無秩序に発行していくと現実に当たる水準です。

失効させたAPIキーは7日間は一覧に残り、その間なら復元できます。誤って失効させた場合の救済策があるということです。ただしブラウザ計測などで使うクライアントトークンは削除すると復元できません。同じ「キー」という言葉でも扱いが違う点に注意してください。

スコープ付きアプリケーションキーで権限を絞り込む設定の手順と注意

アプリケーションキーには本数の明示的な上限はありませんが、代わりに権限の絞り込みが用意されています。Organization Settings のApplication Keysからキーを作成・編集し、そのキーに与えるスコープを選ぶ方式です。スコープを指定したキーは、指定した権限だけを持ち、それ以外は一切持ちません。

設定順序は次の通りです。

1. 用途を1つに決める（例：モニター作成のみ）
2. その用途に必要なスコープだけを選ぶ
3. キー文字列を控え、シークレット管理へ登録する
4. 実際に叩いて403が出ないことを確認する

スコープ名は大文字小文字を区別します。monitors_writeやmetrics_readのような表記をそのまま写す必要があり、綴りが揺れると権限不足として弾かれます。読み取りだけのダッシュボード同期に書き込みスコープを付けないでください。過剰な権限は、キーが漏れたときの被害範囲をそのまま広げます。

退職でアプリケーションキーが止まる事故とサービスアカウント運用

ユーザーアカウントを無効化すると、そのユーザーのアプリケーションキーは失効します。一方でAPIキーは組織に紐づくため有効なままです。この非対称が事故の原因です。担当者が退職した翌日、メトリクス送信は動き続けているのにモニター同期のバッチだけが403で落ちる、という形で表面化します。

回避策はサービスアカウントです。Organization Settings のService Accountsから非対話型のアカウントを作り、そこにロールを割り当ててアプリケーションキーを発行します。人の在籍とは無関係に存続するため、自動化の寿命が人事に左右されません。

発行時に1点だけ気をつけてください。サービスアカウントのアプリケーションキーは作成直後に一度しか表示されません。控え損ねたら失効させて作り直すことになります。生成と同時にシークレットマネージャへ書き込む手順にしておくと確実です。

メトリクス送信からモニター・ダッシュボード操作までの主要API

ここからは実際に呼び出すエンドポイントを扱います。用途別に必要なキーの組み合わせが変わるため、まず表で対応関係を押さえます。

表中のdistribution_pointsが示す完全なパスは/api/v1/distribution_pointsです。

カスタムメトリクスを送るv2系エンドポイントと課金への影響範囲

アプリケーション独自の数値をDatadogへ送るときはPOST /api/v2/seriesを使います。系列名・タグ・時刻・値を持つ配列を投げる形で、APIキーだけで認証可能です。Agentを経由せずアプリから直接送れるため、バッチジョブの処理件数やキューの滞留数といった業務メトリクスの投入に向きます。

送る前に一度立ち止まってください。カスタムメトリクスはタグの組み合わせの数だけ系列が増え、そのまま課金対象です。ユーザーIDやリクエストIDのような値をタグに入れると、系列数が桁違いに膨らみます。タグ設計と費用の関係はDatadog運用のベストプラクティスで扱っています。

モニターの作成と一覧取得を担うmonitorエンドポイントの操作

モニターは/api/v1/monitorで扱います。POSTで作成、GETで一覧取得です。どちらもアプリケーションキーが要るため、スコープを絞ったキーを使うならモニター系のスコープを付与しておきます。

実務で効くのは一括操作です。障害対応やメンテナンス作業のとき、対象タグに一致するモニターだけをまとめてミュートする。デプロイ前後で閾値を一時的に緩める。こうした一過性の変更は、UIで1件ずつ触るより速く、作業ログも残ります。恒久的な定義そのものはコード管理に置き、一時的な状態変更をAPIで行う、という分担が扱いやすい形です。

ダッシュボードJSONの取り出しと別組織へ複製するときの実装手順

ダッシュボードはJSON定義として取得・投入できます。検証環境で作り込んだ画面を本番組織へ移す、部署ごとに同じ構成を配る、といった複製に使えます。

そのまま投げると失敗しがちなのが、定義内に埋め込まれた識別子です。取得したJSONにはIDや作成者の情報が含まれるため、投入先で衝突します。複製時はIDに相当する項目を落とし、テンプレート変数で参照している環境名やサービス名を投入先の値へ置換してからPOSTしてください。手作業で直すのは1枚が限界です。2枚目からはスクリプト化したほうが早く終わります。

時系列データの取り出しでv1のqueryとv2を選び分ける基準

グラフの数値をコードから取りたいときは2系統あります。単一のメトリクスクエリを投げて点列を得るならGET /api/v1/query、複数プロダクトのデータを横断して時系列を組み立てるならPOST /api/v2/query/timeseriesです。2026年8月時点の公式リファレンスでは、どちらも非推奨の表示は付いていません。

選び分けの基準は単純です。メトリクスだけを短い式で取るならv1のクエリで十分です。ログやトレース由来のデータと同じ時間軸で並べたい、複数の式をまとめて1リクエストで投げたい、というときにv2へ移ります。レポート生成のように定期実行するなら、期間を細切れにせず1リクエストの範囲を広く取るほうがリクエスト数を抑えられます。

レート制限の挙動とX-RateLimitヘッダーに基づく429リトライ設計

自動化で最後に当たる壁がレート制限です。公式ドキュメントは、多くのエンドポイントに制限があり、その値はエンドポイントごとに異なると明記しています。全エンドポイントの一覧表は提供されていません。だからこそ、値を決め打ちにせずヘッダーを読む実装にする必要があります。

429応答時に読むX-RateLimitヘッダー5種の意味と使い分け

制限を超えると429が返ります。レスポンスには次の5つのヘッダーが含まれます。

• X-RateLimit-Limit：その期間に許可されるリクエスト数
• X-RateLimit-Period：リセット周期の秒数（カレンダー基準）
• X-RateLimit-Remaining：現在の期間で残っている回数
• X-RateLimit-Reset：次のリセットまでの秒数
• X-RateLimit-Name：上限緩和を申請するときの制限名

実装で使うのは主に Remaining と Reset の2つです。Remaining が閾値を下回ったら送出を絞り、429を受けたら Reset の秒数だけ待ってから再送する。固定秒のsleepを埋め込むより正確で、制限値が変わっても壊れません。上限そのものを引き上げたいときは Name の値を添えてサポートへ相談する流れになります。

イベント送信の毎分250,000件という上限と実務で当たる場面

ドキュメントが数値まで明示している例のひとつが、イベント送信の1組織あたり毎分250,000件です。通常のアプリケーション運用でこの水準に届くことはまずありません。当たるとすれば、ログの各行をイベントとして送るような設計をしたときです。

そもそもイベントは、デプロイや設定変更のような「起きたこと」を記録する枠です。連続する数値はメトリクス、テキストの詳細はログへ振り分けてください。上限に近づいた時点で、送り先の選び方そのものを疑うほうが早く解決します。

指数バックオフとバッチ化でリクエスト数を削る実装の組み立て方

リトライは指数バックオフに統一します。429を受けたら Reset の秒数を初期待機として、失敗のたびに待機時間を倍にし、上限回数で打ち切る。同時に走るワーカーが多い環境では、待機に少量のゆらぎを加えて再送が同時刻に集中しないようにします。

ただしリトライ設計より効くのはリクエスト数を減らすことです。メトリクスは1点ずつではなく複数系列をまとめて1リクエストで送る。モニター一覧は毎回全件取得せず、変更検知の間隔を業務要件まで緩める。監視の設定同期を1分おきに回している実装をよく見かけますが、その頻度が必要な理由はたいてい説明できません。

APIを直接叩く場面とTerraform管理へ寄せる場面の切り分け基準

ここが本記事の結論部です。同じモニター作成という操作でも、APIスクリプトで書くべき場合とコードで宣言すべき場合があり、混ぜると設定が巻き戻ります。条件を付けて言い切ります。

Terraformへ寄せるべき恒久的な設定リソースの範囲と理由

継続的に存在し、レビュー対象になり、環境間で同じ形を保ちたいもの。この条件に当てはまる設定はTerraformへ寄せてください。具体的にはモニター定義、ダッシュボード、通知先の連携設定、ロールとサービスアカウントの割り当てです。

差分管理が理由です。APIスクリプトで作ったモニターは、誰かがUIで閾値を触った瞬間に実態と手元のコードがずれ、次にスクリプトを流したときの結果を予測できません。宣言的に管理していればplanで差分が見え、UIでの変更は次回applyで元に戻る仕組みです。providerの設定方法とインポート手順はTerraformでDatadogを管理する方法にまとめています。

APIを直接叩くほうが早い一時操作と障害調査での具体的な用途

逆に、状態が一時的なものはAPIで叩くほうが速い。メンテナンス時間帯の一括ミュート、障害調査での時系列データの取り出し、業務メトリクスの送信、月次レポート用の数値抽出。これらをTerraformで書こうとすると、状態ファイルに一時的な変更が残って邪魔になります。

もう1つAPI側が有利なのが、外部システムとの連携です。社内のインシデント管理や業務システムからDatadogの数値を引いて突き合わせる、といった処理はHTTPで直接呼ぶ以外に選択肢がありません。この種の連携は、キーの保管とリトライ設計を含めた実装設計が品質を左右します。基盤側の設計から相談したい場合はAPI開発・システム連携で対応しています。製品全体の位置づけを先に確認したい方はDatadogとは何かを読んでから戻ってきてください。

採用を見送る場面：モニター数が少なくUI運用で足りる小規模構成

API連携を見送るべき場面も明示します。監視対象が数台、モニターが10件未満、変更が月に数回。この規模ならUIでの手作業に勝てません。キーの保管、権限設計、リトライ実装、スクリプトの保守という固定費が、削減できる作業時間を上回ります。

境界の目安を数字で置きます。モニターが数十件を超える、環境が本番・検証・開発と3つ以上に分かれる、変更が週次以上で発生する。このいずれかに該当したらコード管理へ移す判断が立ちます。逆に、キーを配る相手が1人で、その1人がUIも触れる状態なら、自動化はまだ早い。作らない判断も設計のうちです。

よくある質問

Datadog APIの実装で問い合わせの多い論点を、実務での判断に絞って答えます。

APIキーとアプリケーションキーはどちらを先に作ればよいですか？

APIキーが先です。アプリケーションキーはAPIキーと組み合わせて使う前提のため、単独では意味を持ちません。手順としては、まず用途ごとにAPIキーを1本発行し、GET /api/v1/validateで有効性を確認します。読み取りや設定変更が必要になった時点で、サービスアカウント名義のアプリケーションキーをスコープ付きで追加してください。この順で作ると、401が返ったときにAPIキー側の問題だと即座に切り分けられます。

アプリケーションキーを付けているのに403が返るのはなぜですか？

キーの有無ではなく、キーの名義が持つ権限を疑ってください。アプリケーションキーは紐づくユーザーまたはサービスアカウントの権限範囲でしか動きません。スコープ付きで発行した場合はさらに絞られ、指定したスコープ以外は一切通らなくなります。スコープ名は大文字小文字を区別するため、綴りの写し間違いでも同じ症状が出ます。読み取り用途なのに書き込みスコープしか付けていない、という取り違えもよくある原因です。

キーが漏洩した疑いがあるとき、すぐに何をすべきですか？

該当キーの失効が最初です。APIキーは失効させても7日間は一覧に残り復元できるため、影響範囲が読めない段階でも思い切って止められます。次に、そのキーがどこから使われていたかを洗い、シークレット管理側の値を差し替えます。新しいキーは反映まで数秒かかるとされているので、切り替え直後の失敗は検証エンドポイントで待ってから判定してください。なお、ブラウザ側で使うクライアントトークンは削除すると復元できません。

レート制限の上限値はどこで確認できますか？

実際に返ってきたレスポンスヘッダーで確認するのが確実です。公式ドキュメントには全エンドポイントの上限一覧は掲載されておらず、値はエンドポイントごとに異なるとされています。X-RateLimit-Limit と X-RateLimit-Period を読めば、そのエンドポイントの許容量と周期が分かります。恒常的に不足するなら、X-RateLimit-Name に出ている制限名を添えてサポートへ緩和を相談する流れです。

APIでモニターを作った後にTerraformへ移行できますか？

できます。既存のモニターIDを指定してインポートし、状態ファイルに取り込んだうえで定義をコードへ書き起こす形です。移行時に気をつけるのは、インポート後もAPIスクリプト側が動き続けている状態を作らないことです。両方から同じリソースを書き換えると、applyのたびに設定が往復します。移行のタイミングでスクリプトの該当処理を停止し、コード管理へ一本化してください。

関連記事

• Datadogの料金体系と費用が膨らむ課金単位：APIで送るカスタムメトリクスが費用へ跳ねる仕組みを整理しています。
• Datadog APM導入の実装手順：トレース側の計装をdd-traceで自動化する手順を扱っています。
• Datadog RUM導入の実装手順：ブラウザSDKの設定とクライアントトークンの扱いをまとめています。
• Datadog OpenTelemetry連携の4方式：APIで送るか標準プロトコルで送るかという経路の選び分けを扱っています。