本文へ移動
Telemetry
ドキュメントを見る
APIリファレンス更新日: 2026年7月27日Telemetry 編集チームと製品チームによるレビュー17 最小読み取り時間

コーディング エージェントでこのドキュメントを使用してください

Claude Code、Codex、Cursor、または別のコーディング エージェント用の集中プロンプト パックを開き、それをここで説明するワークフローに適応させます。

このページの内容
  1. リスト応答
  2. ボディの作成
  3. 応答の作成
  4. 本文の編集
  5. 応答を編集する
  6. 本文の削除
  7. 応答の削除
  8. よくあるエラー
  9. ウィジェットフィールド
  10. レイアウトを理解する
  11. ウィジェット構成のクエリ
  12. 例: カテゴリ棒グラフの X 軸を持つクエリ ウィジェット
  13. ヘッダーウィジェットの設定
  14. フリーテキストウィジェット構成
  15. エクスプローラーのウィジェット構成
  16. 例: 空のダッシュボードを作成する
  17. 例: ダッシュボードのリスト
  18. 例: 空のダッシュボードを作成する
  19. 例: ダッシュボードの名前を変更し、その説明を更新します
  20. 例: 既存のダッシュボード上のすべてのウィジェットを置き換えます
  21. 例: ダッシュボードを削除する
  22. 一般的なウィジェットの例
  23. 例: 2 つの共通の Explore ウィジェットを含むダッシュボードを作成する
  24. 例: コホート保持率の笑顔曲線のクエリ ウィジェットを作成する
  25. 応答

ダッシュボード

ダッシュボード API を使用すると、取り込み操作やクエリ操作にすでに使用しているのと同じ API キーを使用して、プログラムでダッシュボードの一覧表示、作成、編集、削除を行うことができます。

サポートされている操作:

  • リスト. GET https://api.telemetry.sh/dashboard
  • 作成. POST https://api.telemetry.sh/dashboard
  • 編集. PATCH https://api.telemetry.sh/dashboard
  • 削除. DELETE https://api.telemetry.sh/dashboard

ヘッダー

名前 タイプ 説明
Content-Type 文字列 きっと application/json.
Authorization 文字列 API キー (生のキーまたは Bearer <key>.

スコープのルール:

  • GET /dashboard 受け入れる read, write、または read-and-write
  • POST /dashboard, PATCH /dashboard、そして DELETE /dashboard 必要とする write または read-and-write

リスト応答

GET /dashboard API キーのチームのすべてのダッシュボードを次の順序で返します。 updated_at DESC.

サポートされているクエリパラメータ:

フィールド タイプ 必須 正確な契約 デフォルト
page 整数 いいえ 正の整数のページ番号。未満の値 1 拒否されます。 1
pageSize 整数 いいえ 正の整数のページ サイズ。より大きい値 100 に固定されている 100。 API は従来のエイリアスも受け入れます page_size. 50

各項目には、ダッシュボードのメタデータ、 urlwidget_count、および API 形状の完全なウィジェット リスト。

トップレベルの応答:

フィールド タイプ 正確な契約
status 文字列 いつも "success" 成功について。
pagination オブジェクト 現在のページのページネーションのメタデータ。以下の表を参照してください。
dashboards 配列 API キーのチームのダッシュボード オブジェクトの配列。チームにダッシュボードがない場合は空の配列。

pagination 含まれるもの:

フィールド タイプ 正確な契約
page 整数 現在の 1 から始まるページ番号。 2
pageSize 整数 デフォルト設定および最大サイズクランプ後の有効ページサイズ。 25
total 整数 ページネーション前のチームのダッシュボードの合計数。 63
totalPages 整数 現在の総ページ数 pageSize. 0 いつ total です 0. 3
hasNextPage ブール値 true 現在のページの後に別のページが存在する場合。 true
hasPreviousPage ブール値 true 現在のページより前に別のページがある場合. true

の各項目 dashboards 含まれるもの:

フィールド タイプ 正確な契約
id 文字列 ダッシュボードID。 "550e8400-e29b-41d4-a716-446655440000"
team_id 文字列 所有チームID。 "a7d4..."
name 文字列 ダッシュボード名。 "Operations Overview"
slug 文字列 ダッシュボードのスラッグ。 "operations-overview"
description 文字列または null 保存されたダッシュボードの説明。 "Core service health and latency"
created_by 文字列または null UI で作成されたダッシュボードのユーザー ID。 null API で作成されたダッシュボード用。 null
created_by_api_key_id 文字列または null API が作成したダッシュボードのチーム API キー ID。 null UI で作成されたダッシュボードの場合。 "key_123"
created_at 文字列 ダッシュボード テーブルのタイムスタンプ文字列。 "2026-03-27T00:09:03.797Z"
updated_at 文字列 ダッシュボード テーブルのタイムスタンプ文字列。 "2026-03-27T00:09:03.797Z"
url 文字列 Telemetry UI の相対ダッシュボード URL。 "/team/acme/dashboard/operations-overview"
widget_count 整数 ダッシュボードにアタッチされているウィジェットの数。 2
widgets 配列 作成および編集応答によって返される同じ形状のウィジェット配列。 []

ボディの作成

フィールド タイプ 必須 正確な契約
name 文字列 はい トリミングされたダッシュボード名。トリミング後は空であってはなりません。 "HTTP Monitoring"
slug 文字列 いいえ オプションのカスタムスラッグ。 Telemetry は、トリミング、小文字化、および例外を除くすべての文字の削除によって正規化します。 a-z, 0-9、スペース、および -、空白行を次のように変換します -、崩壊が繰り返される -、および先頭/末尾のトリミング -。省略した場合、Telemetry は次から導出します。 name。正規化された結果には、少なくとも 1 つの英数字が含まれている必要があります。 "HTTP Monitoring!!!" になる "http-monitoring"
description 文字列または null いいえ オプションの説明。空の文字列は次のように正規化されます。 null. "Core service health and latency"
widgets 配列 いいえ すぐに作成するウィジェットのオプションの配列。省略した場合、ダッシュボードは空で作成されます。いずれかのウィジェットが無効な場合、リクエスト全体が拒否されます。 400. []

応答の作成

POST /dashboard 返品 201 Created 保存されたダッシュボードと正規化されたウィジェット リストを使用します。

{
  "status": "success",
  "dashboard": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "team_id": "a7d4...",
    "name": "HTTP Monitoring",
    "slug": "http-monitoring",
    "description": "Core service health and latency",
    "created_by": null,
    "created_by_api_key_id": "key_123",
    "created_at": "2026-03-27T00:09:03.797Z",
    "updated_at": "2026-03-27T00:09:03.797Z",
    "url": "/team/acme/dashboard/http-monitoring"
  },
  "widgets": [
    {
      "id": "0b3cb3f5-1147-4f2f-bf64-5044147c3e9a",
      "title": "Errors Per Hour",
      "widget_type": "query",
      "config": {
        "querySql": "SELECT hour, errors FROM error_rollups",
        "chartType": "Line Chart",
        "xAxis": "hour",
        "yAxis": "errors",
        "groupBy": null,
        "queryId": null,
        "sourceUrl": null
      },
      "layout": {
        "x": 0,
        "y": 0,
        "w": 12,
        "h": 4
      },
      "sort_order": 1
    }
  ]
}

本文の編集

PATCH /dashboard 部分的な更新エンドポイントです。省略されたフィールドは変更されません。

ターゲットのダッシュボードを次のように指定する必要があります。 dashboardId または dashboardSlug.

フィールド タイプ 必須 正確な契約
dashboardId 文字列 の 1 つ dashboardId または dashboardSlug 編集する既存のダッシュボード ID。両方の識別子が送信される場合は、同じダッシュボードを参照する必要があります。 "550e8400-e29b-41d4-a716-446655440000"
dashboardSlug 文字列 の 1 つ dashboardId または dashboardSlug 編集する既存のダッシュボード スラッグ。これは新しいスラッグではなく、現在のスラッグです。 "http-monitoring"
name 文字列 いいえ 新しいトリミングされたダッシュボード名。指定する場合は空であってはなりません。更新中 name スラグは自動的に変更されません。 "HTTP Monitoring v2"
slug 文字列 いいえ 新しいスラッグ値。 Telemetry は、作成と同じルールで正規化します。省略した場合、既存のスラッグは変更されません。 "http-monitoring-v2"
description 文字列または null いいえ 新しいダッシュボードの説明。 null または "" 説明をクリアします。省略した場合、既存の説明は変更されません。 "Updated on-call dashboard"
widgets 配列 いいえ 完全な代替ウィジェットのリスト。省略した場合、既存のウィジェットは変更されません。指定された場合、Telemetry は現在のウィジェット セットを削除し、この配列内のウィジェットそのものに置き換えます。 [] すべてのウィジェットをクリアします。 []

注:

  • PATCH は、単一のウィジェットを適切な場所に追加または編集することをまだサポートしていません。
  • いつ widgets が提供されている場合、API が完全なウィジェット セットを置き換えるため、ウィジェット ID が再生成されます。

応答を編集する

PATCH /dashboard 返品 200 OK create と同じ応答形状を使用します。

  • dashboard 保存されたダッシュボードのメタデータが含まれており、 url
  • widgets API 形状の完全な永続化ウィジェット リストが含まれています
  • もし widgets 置き換えられた場合、返されたウィジェット ID には新しく挿入された行が反映されます

本文の削除

DELETE /dashboard 単一のダッシュボードとそのすべてのウィジェットを削除します。

ターゲットのダッシュボードを次のように指定する必要があります。 dashboardId または dashboardSlug.

フィールド タイプ 必須 正確な契約
dashboardId 文字列 の 1 つ dashboardId または dashboardSlug 削除する既存のダッシュボード ID。両方の識別子が送信される場合は、同じダッシュボードを参照する必要があります。 "550e8400-e29b-41d4-a716-446655440000"
dashboardSlug 文字列 の 1 つ dashboardId または dashboardSlug 削除する既存のダッシュボード スラグ。 "http-monitoring"

注:

  • 削除は永久的です。
  • ダッシュボードを削除すると、現在ダッシュボードにアタッチされているすべてのウィジェットも削除されます。

応答の削除

DELETE /dashboard 返品 200 OK:

{
  "status": "success",
  "deleted_dashboard": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "name": "HTTP Monitoring",
    "slug": "http-monitoring",
    "description": "Core service health and latency",
    "widget_count": 2,
    "url": "/team/acme/dashboard/http-monitoring"
  }
}

よくあるエラー

  • 400 Bad Request JSON 本文が無効であるか、リクエスト本文が JSON オブジェクトではない場合
  • 400 Bad Request もし page または pageSize は正の整数ではありません GET /dashboard
  • 400 Bad Request もし dashboardId または dashboardSlug が欠けています PATCH または DELETE
  • 400 Bad Request もし PATCH 編集可能なフィールドをすべて省略します
  • 400 Bad Request もし name, slug, description、または widgets 検証に失敗する
  • 400 Bad Request クエリ ウィジェットに読み取り専用以外の SQL が含まれている場合
  • 403 Forbidden API キーに要求された操作に対する権限がない場合
  • 401 Unauthorized API キーが見つからないか無効な場合
  • 404 Not Found API キーのチームにダッシュボードが存在しない場合
  • 409 Conflict 同じチーム内の別のダッシュボードが要求されたスラッグをすでに使用している場合

ウィジェットフィールド

の各項目 widgets サポート:

フィールド タイプ 必須 正確な契約
title 文字列 はい ウィジェットのタイトルをトリミングしました。トリミング後は空であってはなりません。 "Errors Per Hour"
widget_type 文字列 はい 正確な列挙型: query, explorer, header、または free_text. "query"
config オブジェクト はい ウィジェット構成オブジェクト。その必須フィールドは次のものに依存します widget_type. { "querySql": "...", "chartType": "Line Chart" }
layout オブジェクト いいえ オプションのグリッド配置。省略した場合、Telemetry はウィジェット タイプのデフォルトを使用してウィジェットを垂直に積み重ねます。 { "x": 0, "y": 0, "w": 12, "h": 4 }

レイアウトを理解する

Telemetry ダッシュボードは 12 列のグリッドを使用します。

layout オブジェクトはピクセルではなくグリッド単位を使用します。

フィールド タイプ デフォルト 正確な契約
x 整数 0 負ではない整数。 0 一番左です。無効な値は次のようになります。 0. 0
y 整数 次に開いている行 負ではない整数。 0 ダッシュボードの上部です。省略した場合、Telemetry は前のウィジェットの後にウィジェットを配置します。 y + h。無効な値は、その計算された行にフォールバックされます。 0
w 整数 12 グリッド列の正の整数の幅。 12 全角を意味し、 6 半角という意味です。無効な値は次のようになります。 12. 12
h 整数 ウィジェットタイプのデフォルト グリッド行の正の整数の高さ。無効な値は、以下にリストされているウィジェット タイプのデフォルトに戻ります。 4

したがって、これは次のとおりです。

"layout": { "x": 0, "y": 0, "w": 12, "h": 4 }

意味:

  • ウィジェットをダッシュボードの左上隅に配置します
  • 12 列すべてにまたがるようにする
  • ダッシュボードグリッドの4行分の高さにします

これ:

"layout": { "x": 6, "y": 0, "w": 6, "h": 4 }

意味:

  • ウィジェットを一番上の行に配置します
  • ダッシュボードの半分から開始する
  • 行の右半分を取得する

たとえば、次の 2 つのウィジェットは並べて表示されます。

[
  { "layout": { "x": 0, "y": 0, "w": 6, "h": 4 } },
  { "layout": { "x": 6, "y": 0, "w": 6, "h": 4 } }
]

省略した場合 layout、Telemetry は、次のデフォルトを使用してウィジェットを垂直にスタックします。

  • x = 0
  • w = 12
  • h = 4 のために query そして explorer
  • h = 2 のために header
  • h = 3 のために free_text
  • y 次の開いている行に配置されます

Telemetry はクランプしません x そして w 12 列グリッドに変換され、重複する位置は解決されません。キープする x + w <= 12 そして重複を避ける x/y 予測可能なレンダリングが必要な場合は、範囲を指定します。

ウィジェット構成のクエリ

フィールド タイプ 必須 正確な値または形式
querySql 文字列 はい トリミングされた読み取り専用の SQL 文字列。トリミング後は空であってはなりません。ダッシュボード クエリ ウィジェットは、次のような書き込みステートメントを拒否します。 INSERT, UPDATE, DELETE, DROP, ALTER, TRUNCATE, CREATE, GRANT、そして REVOKE. "SELECT endpoint, COUNT(*) AS errors FROM http_logs GROUP BY endpoint"
chartType 文字列 はい API によって検証された正確な列挙型: table, Scatter Plot, Bar Chart, Line Chart、または Stacked Area Chart. "Line Chart"
xAxis 文字列 非対応の場合は必須table チャート X 軸に使用するトリミングされた結果の列名。のために Bar Chart、これはテキスト/カテゴリ、数値、または時間のような列にすることができます。のために Scatter Plot, Line Chart、そして Stacked Area Chart、数値または時間のような列を使用します。次の場合にのみ空の文字列になる可能性があります chartType です table. "hour"
yAxis 文字列 非対応の場合は必須table チャート Y 軸に使用するためにトリミングされた数値結果の列名。次の場合にのみ空の文字列になる可能性があります chartType です table. "errors"
groupBy 文字列または null いいえ グラフを複数の系列に分割するために使用されるオプションのトリム結果列名。使用する null またはグループ化しない場合は省略します。 "service"
queryId 文字列または null いいえ オプションでトリミングされた保存されたクエリ ID。 API はこれを文字列として保存し、その形状を検証しません。 "550e8400-e29b-41d4-a716-446655440000"
sourceUrl 文字列または null いいえ ウィジェットのタイトルをクリックしたときに開く、オプションのトリミングされた UI URL。アプリの相対 URL: /team/acme/ops/draft/0?... が推奨されます。 "/team/acme/ops/draft/0?tab=chart&chartType=Line+Chart&xAxis=hour&yAxis=errors"

注:

  • 使用する chartType: "table" グラフではなく単純な結果表が必要な場合。
  • ダッシュボード クエリ ウィジェットはダッシュボードの読み込み時に自動実行されるため、読み取り専用の SQL のみが受け入れられます。
  • 非すべての人にとって、table チャート、 xAxis そして yAxis によって返される実際の列と一致する必要があります querySql.
  • のために Bar Chart, xAxis テキスト/カテゴリ、数値、または時間のようなものにすることができます。
  • のために Scatter Plot, Line Chart、そして Stacked Area Chart, xAxis 数値または時間のようなものでなければなりません。
  • 非すべての人にとって、table チャート、 yAxis 数値でなければなりません。
  • カテゴリカルの場合 Bar Chart x 軸、ウィジェットはクエリ結果の順序を保持します。使用する ORDER BYquerySql バーの順序を制御します。
  • もし sourceUrl が省略されている場合、ダッシュボード UI は可能な場合はフォールバック ドラフト クエリ URL を派生します。派生リンクは維持されます defaultQuery, tab, chartType, xAxis, yAxis、そして groupBy.

例: カテゴリ棒グラフの X 軸を持つクエリ ウィジェット

{
  "title": "Requests by Endpoint",
  "widget_type": "query",
  "config": {
    "querySql": "SELECT endpoint, COUNT(*) AS requests FROM http_logs GROUP BY endpoint ORDER BY requests DESC",
    "chartType": "Bar Chart",
    "xAxis": "endpoint",
    "yAxis": "requests",
    "groupBy": null
  }
}

その例では:

  • endpoint テキストの X 軸列です
  • requests y 軸の数値列です
  • ORDER BY requests DESC 左から右へのバーの順序を制御します

ヘッダーウィジェットの設定

使用する widget_type: "header" 関連するウィジェットをグループ化するセクションのタイトル。

フィールド タイプ 必須 正確な値または形式
description 文字列または null いいえ ヘッダー タイトルの下に表示されるオプションのマークダウンの説明。空の文字列は次のように正規化されます。 null. "Watch these charts during deploys and incident triage."

注:

  • ウィジェット title は表示されるセクションのタイトルです。
  • description マークダウンをサポートします。生の HTML は、UI でレンダリングされる前にエスケープされます。

例:

{
  "title": "Deploy Health",
  "widget_type": "header",
  "config": {
    "description": "Use this section during rollout checks and incident response."
  }
}

フリーテキストウィジェット構成

使用する widget_type: "free_text" スタンドアロンのマークダウン ノート、リンク、または運用手順書用。

フィールド タイプ 必須 正確な値または形式
content 文字列 はい トリミング後の空ではないマークダウン コンテンツ。 "Check [the latency recipe](/sql/api-latency-percentiles) before paging infra."

注:

  • content マークダウンをサポートします。生の HTML は、UI でレンダリングされる前にエスケープされます。
  • ウィジェット title UI がこのコンポーネント タイプのマークダウン本文のみをレンダリングする場合でも、API では依然として必要です。

例:

{
  "title": "API Runbook Note",
  "widget_type": "free_text",
  "config": {
    "content": "Check the on-call runbook first, then compare request volume with deploy timestamps."
  }
}

エクスプローラーのウィジェット構成

フィールド タイプ 必須 正確な値または形式
tableName 文字列 はい トリミングされたソーステーブル名。トリミング後は空であってはなりません。 "queue_metrics"
explorerState オブジェクト はい ウィジェットのレンダリングに使用される完全な Explore 構成。以下の詳細なフィールド表を参照してください。 { "graphType": "line", "aggregation": "p95", ... }
sourceUrl 文字列または null いいえ ウィジェットのタイトルをクリックしたときに開く、オプションのトリミングされた UI URL。省略した場合、Telemetry はフォールバック Explore URL を派生します。 tableName そして explorerState. "/team/acme/table/queue_metrics?tab=explore&graphType=line"

explorerState フィールド

フィールド タイプ 必須 正確な値または形式 デフォルト
graphType 文字列 はい API によって検証された正確な列挙型: samples, table, line, bar, stacked-area. "samples" "line"
aggregation 文字列 はい API によって検証された正確な列挙型: count, sum, avg, min, max, p50, p90, p95, p99. "count" "p95"
metric 文字列または null いいえ 集計する列またはフィールドのパスをトリミングしました。使用する null のために count。非count 集計の場合、これは主要な測定値であり、自動検出された数値よりも優先されます。 selectedColumns 提供された場合。 null "latency_ms"
timeZone 文字列または null いいえ 使用する UTC または次のような IANA タイムゾーン識別子 America/Los_Angeles または Europe/Berlin。現在、API は空でない文字列をトリミングして保存しますが、無効なタイム ゾーン名は後でウィジェット クエリを実行するときに失敗する可能性があります。省略した場合、保存された設定が保持されます。 null UI はクライアントのタイムゾーンにフォールバックするか、 UTC 文脈に応じて。 null "America/Los_Angeles"
timePreset 文字列 はい サポートされている値は次のとおりです 1h, 6h, 24h, 7d, 30d, 90d, custom。 API は現在、空でない文字列を受け入れますが、UI および SQL ジェネレーターでサポートされるのはそれらの値のみです。 "7d" "7d"
customStart 文字列 いいえ ときに使用されます timePreset です custom。推奨フォーマット: YYYY-MM-DDTHH:mm, YYYY-MM-DD HH:mm, YYYY-MM-DDTHH:mm:ss、または YYYY-MM-DDTHH:mm:ss.sss、オプションでその後に Z または次のような数値オフセット -07:00。タイムゾーン接尾辞が存在しない場合、値は次のように解釈されます。 timeZone. 設定を解除する "2026-03-20T00:00:00Z"
customEnd 文字列 いいえ と同じ形式 customStart。カスタム範囲で省略した場合、クエリには時間の上限がありません。 設定を解除する "2026-03-26T00:00:00-07:00"
granularity 文字列 はい API によって検証された正確な列挙型: auto, minute, hour, day, week, month. "auto" "hour"
splitBy 文字列の配列 はい 空ではないトリミングされたフィールド名の配列。次のような点線のパス attributes.queue_name ネストされた JSON フィールドでは許可されます。 [] ["queue_name"]
seriesLimit 整数または null いいえ 正の整数または null. null 明示的なシリーズ上限がないことを意味します。分割グラフに最も役立ちます。 100 10
filters 配列 はい フィルターグループの配列。各グループは内部で AND 演算されます。複数のグループは OR 演算されます。空のグループまたは無効なグループは正規化中に削除されます。 [] []
selectedColumns 文字列の配列 はい 次のビューに表示する、前後の空白を除いた空でないフィールド名の配列: samples または table ビュー。点線の JSON パスが許可されます。使用する [] Telemetry にデフォルトを選択させます。 [] ["timestamp_utc", "queue_name", "latency_ms"]
orderBy 文字列または null いいえ 表形式の結果を並べ替えるために使用されるオプションのフィールド名。点線の JSON パスが許可されます。 null "timestamp_utc"
limit 整数 はい 正の整数の行またはグループの制限。無効な値はデフォルトに戻ります。 200 200
orderDirection 文字列 はい API によって検証された正確な列挙型: ASC または DESC. "DESC" "DESC"

timePreset 価値観

意味
1h 最後の 1 時間
6h 過去6時間
24h 過去 24 時間
7d 過去 7 日間
30d 過去 30 日間
90d 過去90日間
custom 使用する customStart そして customEnd 相対範囲の代わりに

書類のないものを送った場合 timePreset, 現在のSQLジェネレーターは 7-day behavior.上記の値をサポートされているコントラクトとして扱います。

granularity: "auto" 行動

いつ granularity です auto, Telemetry は次のように解決します。

timePreset 効果的な粒度
1h, 6h, 24h minute
7d hour
30d, 90d, custom day

フィルターグループと条件

filters 次のような形にする必要があります:

[
  {
    "logic": "AND",
    "conditions": [
      { "field": "queue_name", "operator": "=", "value": "email" },
      { "field": "latency_ms", "operator": ">", "value": "1000" }
    ]
  }
]

の各項目 filters はフィルタ グループです。

フィールド タイプ 必須 正確な値または形式
logic 文字列 はい きっと AND。ダッシュボード作成 API は、すべてのグループを次のように正規化します。 AND;グループごとにはありません OR。グループは OR 演算されるため、OR を表現するには複数のグループを使用します。 "AND"
conditions 配列 はい グループ内のフィルター条件の配列。有効な条件がゼロのグループは削除されます。 [{ "field": "queue_name", "operator": "=", "value": "email" }]

の各項目 conditions サポート:

フィールド タイプ 必須 正確な値または形式
field 文字列 はい 空ではないトリミングされたフィールド パス。次のようなドットでネストされた JSON パス attributes.queue_name サポートされています。空のパス セグメントは許可されません。 "latency_ms"
operator 文字列 はい API によって検証された正確な列挙型: =, !=, >, >=, <, <=, LIKE, NOT LIKE, IS NULL, IS NOT NULL. ">"
value 文字列、数値、ブール値、または null 通常 正規化中に文字列として保存されます。のために IS NULL そして IS NOT NULL、使用します "" または意味値を省略します。 null になる "". "1000"

生成された SQL が実行されると、次のようになります。

  • グループ内の条件は次のように結合されます AND
  • グループが参加しています OR
  • 次のような点線のフィールド パス attributes.queue_name ネストされたフィールドアクセスに変換されます

例: 空のダッシュボードを作成する

例: ダッシュボードのリスト

curl "https://api.telemetry.sh/dashboard?page=1&pageSize=25" \
  -H "Authorization: $API_KEY"

応答例:

{
  "status": "success",
  "pagination": {
    "page": 1,
    "pageSize": 25,
    "total": 1,
    "totalPages": 1,
    "hasNextPage": false,
    "hasPreviousPage": false
  },
  "dashboards": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "team_id": "team_123",
      "name": "Operations Overview",
      "slug": "operations-overview",
      "description": "Core service health and latency",
      "created_by": null,
      "created_by_api_key_id": "key_123",
      "created_at": "2026-03-27T00:09:03.797Z",
      "updated_at": "2026-03-27T00:09:03.797Z",
      "url": "/team/acme/dashboard/operations-overview",
      "widget_count": 1,
      "widgets": [
        {
          "id": "widget_123",
          "title": "Requests Per Hour",
          "widget_type": "query",
          "config": {
            "querySql": "SELECT DATE_TRUNC('hour', timestamp_utc) AS hour, COUNT(*) AS requests FROM http_logs GROUP BY 1 ORDER BY 1",
            "chartType": "Line Chart",
            "xAxis": "hour",
            "yAxis": "requests",
            "groupBy": null,
            "sourceUrl": "/team/acme/ops/draft/0?tab=chart&chartType=Line+Chart&xAxis=hour&yAxis=requests"
          },
          "layout": { "x": 0, "y": 0, "w": 12, "h": 4 },
          "sort_order": 0
        }
      ]
    }
  ]
}

例: 空のダッシュボードを作成する

curl -X POST https://api.telemetry.sh/dashboard \
  -H "Content-Type: application/json" \
  -H "Authorization: $API_KEY" \
  -d '{
    "name": "Operations Overview",
    "description": "Core service health and latency"
  }'

例: ダッシュボードの名前を変更し、その説明を更新します

curl -X PATCH https://api.telemetry.sh/dashboard \
  -H "Content-Type: application/json" \
  -H "Authorization: $API_KEY" \
  -d '{
    "dashboardSlug": "operations-overview",
    "name": "Operations Overview v2",
    "description": "Updated to focus on API latency and error rates"
  }'

例: 既存のダッシュボード上のすべてのウィジェットを置き換えます

このリクエストは同じダッシュボードを維持しますが、完全なウィジェット セットを新しいダッシュボードに置き換えます。 widgets 配列。

curl -X PATCH https://api.telemetry.sh/dashboard \
  -H "Content-Type: application/json" \
  -H "Authorization: $API_KEY" \
  -d '{
    "dashboardSlug": "operations-overview",
    "widgets": [
      {
        "title": "Revenue by City",
        "widget_type": "explorer",
        "config": {
          "tableName": "uber_rides",
          "explorerState": {
            "graphType": "table",
            "aggregation": "sum",
            "metric": "price",
            "timePreset": "30d",
            "granularity": "auto",
            "splitBy": ["city"],
            "filters": [],
            "selectedColumns": [],
            "orderBy": "price",
            "limit": 10,
            "orderDirection": "DESC"
          }
        },
        "layout": { "x": 0, "y": 0, "w": 12, "h": 4 }
      }
    ]
  }'

例: ダッシュボードを削除する

curl -X DELETE https://api.telemetry.sh/dashboard \
  -H "Content-Type: application/json" \
  -H "Authorization: $API_KEY" \
  -d '{
    "dashboardSlug": "operations-overview"
  }'

一般的なウィジェットの例

次の例では、送信する JSON リクエスト本文のみを示します。 POST /dashboard.

これらの例では、次のことを前提としています。 uber_rides 次のようなフィールドを含むテーブル。

  • city
  • price
  • wait_time_minutes
  • status
  • user_id
  • timestamp_utc

例: 2 つの共通の Explore ウィジェットを含むダッシュボードを作成する

この例には次のものが含まれます。

  • 都市ごとの乗車収益を合計し、収益の降順に並べ替えるテーブル ウィジェット
  • 都市別の平均待ち時間をグループ化された線としてグラフ化する時系列ウィジェット
{
  "name": "Uber Marketplace Overview",
  "widgets": [
    {
      "title": "Revenue by City",
      "widget_type": "explorer",
      "config": {
        "tableName": "uber_rides",
        "explorerState": {
          "graphType": "table",
          "aggregation": "sum",
          "metric": "price",
          "timePreset": "30d",
          "granularity": "auto",
          "splitBy": ["city"],
          "filters": [
            {
              "logic": "AND",
              "conditions": [
                { "field": "status", "operator": "=", "value": "completed" }
              ]
            }
          ],
          "selectedColumns": ["city", "price"],
          "orderBy": "price",
          "limit": 20,
          "orderDirection": "DESC"
        }
      },
      "layout": { "x": 0, "y": 0, "w": 6, "h": 4 }
    },
    {
      "title": "Average Wait Time by City",
      "widget_type": "explorer",
      "config": {
        "tableName": "uber_rides",
        "explorerState": {
          "graphType": "line",
          "aggregation": "avg",
          "metric": "wait_time_minutes",
          "timePreset": "7d",
          "granularity": "hour",
          "splitBy": ["city"],
          "seriesLimit": null,
          "filters": [
            {
              "logic": "AND",
              "conditions": [
                { "field": "status", "operator": "=", "value": "completed" }
              ]
            }
          ],
          "selectedColumns": ["city", "wait_time_minutes"],
          "limit": 200,
          "orderDirection": "ASC"
        }
      },
      "layout": { "x": 6, "y": 0, "w": 6, "h": 4 }
    }
  ]
}

その例では:

  • Revenue by City Explore テーブル ウィジェットです
  • selectedColumns: ["city", "price"] プラス aggregation: "sum" 1 つの集約が得られます price 列あたり city
  • orderBy: "price" 集計された収益列で並べ替えます
  • Average Wait Time by City Explore ライン ウィジェットです
  • splitBy: ["city"] 都市ごとに 1 つの回線を作成します
  • orderDirection: "ASC" 時間軸を時系列に保つ

例: コホート保持率の笑顔曲線のクエリ ウィジェットを作成する

Explore でコホート保持を表現するのは非常に難しいため、この例ではクエリ ウィジェットを使用します。それは以下を使用します:

  • 初乗車コホートの定義
  • 明確な週次アクティビティ表
  • コホートサイズと維持されたライダーの間の結合

読みやすい querySql:

WITH first_rides AS (
  SELECT
    user_id,
    date_trunc('week', MIN(timestamp_utc)) AS cohort_week
  FROM
    uber_rides
  WHERE
    status = 'completed'
  GROUP BY
    user_id
),
weekly_activity AS (
  SELECT DISTINCT
    user_id,
    date_trunc('week', timestamp_utc) AS activity_week
  FROM
    uber_rides
  WHERE
    status = 'completed'
),
cohort_activity AS (
  SELECT
    f.cohort_week,
    a.activity_week,
    date_part('day', a.activity_week - f.cohort_week) / 7 AS weeks_since_first_ride,
    COUNT(DISTINCT a.user_id) AS retained_riders
  FROM
    first_rides f
    JOIN weekly_activity a ON a.user_id = f.user_id
  WHERE
    a.activity_week >= f.cohort_week
  GROUP BY
    f.cohort_week,
    a.activity_week,
    date_part('day', a.activity_week - f.cohort_week) / 7
),
cohort_sizes AS (
  SELECT
    cohort_week,
    COUNT(*) AS cohort_size
  FROM
    first_rides
  GROUP BY
    cohort_week
)
SELECT
  weeks_since_first_ride,
  100.0 * retained_riders / cohort_size AS retention_pct,
  CAST(ca.cohort_week AS VARCHAR) AS cohort_week
FROM
  cohort_activity ca
  JOIN cohort_sizes cs ON ca.cohort_week = cs.cohort_week
WHERE
  weeks_since_first_ride BETWEEN 0 AND 12
ORDER BY
  weeks_since_first_ride ASC,
  cohort_week ASC
{
  "name": "Uber Rider Retention",
  "widgets": [
    {
      "title": "Weekly Rider Retention Smile Curves",
      "widget_type": "query",
      "config": {
        "querySql": "WITH first_rides AS ( SELECT user_id, date_trunc('week', MIN(timestamp_utc)) AS cohort_week FROM uber_rides WHERE status = 'completed' GROUP BY user_id ), weekly_activity AS ( SELECT DISTINCT user_id, date_trunc('week', timestamp_utc) AS activity_week FROM uber_rides WHERE status = 'completed' ), cohort_activity AS ( SELECT f.cohort_week, a.activity_week, date_part('day', a.activity_week - f.cohort_week) / 7 AS weeks_since_first_ride, COUNT(DISTINCT a.user_id) AS retained_riders FROM first_rides f JOIN weekly_activity a ON a.user_id = f.user_id WHERE a.activity_week >= f.cohort_week GROUP BY f.cohort_week, a.activity_week, date_part('day', a.activity_week - f.cohort_week) / 7 ), cohort_sizes AS ( SELECT cohort_week, COUNT(*) AS cohort_size FROM first_rides GROUP BY cohort_week ) SELECT weeks_since_first_ride, 100.0 * retained_riders / cohort_size AS retention_pct, CAST(ca.cohort_week AS VARCHAR) AS cohort_week FROM cohort_activity ca JOIN cohort_sizes cs ON ca.cohort_week = cs.cohort_week WHERE weeks_since_first_ride BETWEEN 0 AND 12 ORDER BY weeks_since_first_ride ASC, cohort_week ASC",
        "chartType": "Line Chart",
        "xAxis": "weeks_since_first_ride",
        "yAxis": "retention_pct",
        "groupBy": "cohort_week"
      },
      "layout": { "x": 0, "y": 0, "w": 12, "h": 5 }
    }
  ]
}

その例では:

  • weeks_since_first_ride は X 軸です
  • retention_pct はy軸です
  • groupBy: "cohort_week" サインアップ コホートごとに 1 行を作成し、スマイル カーブ スタイルの比較を生成します。
  • コホート ロジックは複数の CTE と結合に依存しているため、これは Explore ウィジェットではなく Query ウィジェットです。

応答

成功しました POST リクエストが返される 201 Created.

成功しました PATCH リクエストが返される 200 OK.

どちらも次の形状を返します。

{
  "status": "success",
  "dashboard": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "team_id": "team_123",
    "name": "HTTP Monitoring",
    "slug": "http-monitoring",
    "description": null,
    "created_by": null,
    "created_by_api_key_id": "8dff0c1a-8b36-49c3-9e6b-dc0d3ff51d74",
    "created_at": "2026-03-26T00:00:00.000Z",
    "updated_at": "2026-03-26T00:00:00.000Z",
    "url": "/team/acme/dashboard/http-monitoring"
  },
  "widgets": [
    {
      "id": "9a6e4f27-d3bf-4a70-bf3a-38fe63211f93",
      "title": "Errors Per Hour",
      "widget_type": "query",
      "config": {
        "queryId": null,
        "querySql": "SELECT ...",
        "chartType": "Line Chart",
        "xAxis": "hour",
        "yAxis": "errors",
        "groupBy": null,
        "sourceUrl": null
      },
      "layout": {
        "x": 0,
        "y": 0,
        "w": 12,
        "h": 4
      },
      "sort_order": 1
    }
  ]
}

成功しました DELETE リクエストが返される 200 OK 削除の概要:

{
  "status": "success",
  "deleted_dashboard": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "name": "HTTP Monitoring",
    "slug": "http-monitoring",
    "description": null,
    "widget_count": 6,
    "url": "/team/acme/dashboard/http-monitoring"
  }
}

この API を通じて作成されたダッシュボードはチーム スコープであり、ダッシュボードを作成した API キーに属します。

  • created_by です null API で作成されたダッシュボードの場合、API キーはユーザーではないため
  • created_by_api_key_id 内部です team_api_keys.id 作成キーの行
  • UI を通じて作成されたダッシュボードは引き続き使用されます created_by ユーザーIDを使用して通常は終了します created_by_api_key_id として null

正規化されたスラッグがチームにすでに存在する場合、API が返されます。 409 Conflict.

その他の一般的なエラー:

  • 400 Bad Request 必須フィールドが欠落しているか無効な場合
  • 400 Bad Request クエリ ウィジェットに読み取り専用以外の SQL が含まれる場合
  • 404 Not Found チームにターゲットのダッシュボードが存在しない場合
  • 401 Unauthorized API キーが見つからないか無効な場合
  • 400 Bad Request API キーのみがある場合 read 範囲

関連機能

検証されたクエリを、焦点を絞ったレビュー可能な運用ビューに変換します。

ページの著者と参考資料

Telemetry 編集チームがこの説明を所有しています。製品チームは動作、例、境界をレビューします。

ドキュメントのレビュー方法