ダッシュボード
ダッシュボード 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-writePOST /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 |
各項目には、ダッシュボードのメタデータ、 url、 widget_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保存されたダッシュボードのメタデータが含まれており、urlwidgetsAPI 形状の完全な永続化ウィジェット リストが含まれています- もし
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 RequestJSON 本文が無効であるか、リクエスト本文が JSON オブジェクトではない場合400 Bad RequestもしpageまたはpageSizeは正の整数ではありませんGET /dashboard400 Bad RequestもしdashboardIdまたはdashboardSlugが欠けていますPATCHまたはDELETE400 Bad RequestもしPATCH編集可能なフィールドをすべて省略します400 Bad Requestもしname,slug,description、またはwidgets検証に失敗する400 Bad Requestクエリ ウィジェットに読み取り専用以外の SQL が含まれている場合403 ForbiddenAPI キーに要求された操作に対する権限がない場合401 UnauthorizedAPI キーが見つからないか無効な場合404 Not FoundAPI キーのチームにダッシュボードが存在しない場合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 = 0w = 12h = 4のためにqueryそしてexplorerh = 2のためにheaderh = 3のためにfree_texty次の開いている行に配置されます
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 Chartx 軸、ウィジェットはクエリ結果の順序を保持します。使用するORDER BYでquerySqlバーの順序を制御します。 - もし
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 軸列ですrequestsy 軸の数値列です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 でレンダリングされる前にエスケープされます。- ウィジェット
titleUI がこのコンポーネント タイプのマークダウン本文のみをレンダリングする場合でも、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 次のようなフィールドを含むテーブル。
citypricewait_time_minutesstatususer_idtimestamp_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 CityExplore テーブル ウィジェットですselectedColumns: ["city", "price"]プラスaggregation: "sum"1 つの集約が得られますprice列あたりcityorderBy: "price"集計された収益列で並べ替えますAverage Wait Time by CityExplore ライン ウィジェットです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ですnullAPI で作成されたダッシュボードの場合、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 UnauthorizedAPI キーが見つからないか無効な場合400 Bad RequestAPI キーのみがある場合read範囲