瀏覽說明文件

API 參考更新於 2026年7月29日由 Telemetry 編輯團隊和產品團隊審查閱讀約需 5 分鐘

讓程式設計代理使用這篇文件

開啟 Claude Code、Codex、Cursor 或其他編碼代理的集中提示包，然後將其適應此處介紹的工作流程。

開啟提示詞包連線真實遙測

本頁內容

cURL 的使用範例
使用 JavaScript SDK
非同步查詢
它是如何運作的
API 參考
使用 cURL 進行非同步查詢
範例：匯出整個資料表
SDK邊界
常見錯誤

查詢

查詢 API 允許您針對 Telemetry 資料執行 SQL。

發布 https://api.telemetry.sh/query

標題

名稱	型別	描述
內容型別	字串	應用程式/json
授權	字串	您的 API 金鑰，作為原始金鑰或 `Bearer <key>`

身體

名稱	型別	必填	描述
查詢	字串	是的	要執行的 SQL 查詢。
即時	布林值	否	預設為 `true`。傳遞到查詢服務。
json	布林值	否	預設為 `true`。傳遞到查詢服務。

成功回應，200 OK

{
  "status": "success",
  "data": [
    {
      "city": "paris",
      "average_price": 42.0
    }
  ],
  "key_order": ["city", "average_price"]
}

data 包含結果行。 key_order 保留查詢結果中的列順序。

cURL 的使用範例

此 cURL 請求查詢 uber_rides 中各城市的平均車資：

QUERY=$(cat <<'SQL'
SELECT
  city,
  AVG(price) AS average_price
FROM
  uber_rides
GROUP BY
  city
LIMIT
  10000;
SQL
)

curl -X POST https://api.telemetry.sh/query \
  -H "Content-Type: application/json" \
  -H "Authorization: $API_KEY" \
  -d "$(jq -n --arg query "$QUERY" '{query: $query, realtime: true, json: true}')"

使用 JavaScript SDK

我們建議使用 SDK 以獲得更好的開發人員體驗：

import telemetry from "telemetry-sh";

telemetry.init("YOUR_API_KEY");

const results =
  await telemetry.query(`
    SELECT
      city,
      AVG(price)
    FROM
      uber_rides
    GROUP BY
      city
  `);

非同步查詢

較小的 JSON 結果透過 result 中的 data 和 key_order 直接回傳。較大的 JSON 結果和 Parquet 匯出使用 download_url。完成回應只需提供其中一種；直接回傳的結果不需要下載 URL 或 URL 到期欄位。如果 download_url_expired 為 true，請發起新查詢。到期欄位為選填。

這對於匯出整個資料表、執行大量聚合或將結果下載為 JSON 或 Parquet 檔案特別有用。

它是如何運作的

開始 — POST 您對 /query/async 的查詢。伺服器返回 job_id 和 status_url。
輪詢 — GET status_url 以檢查進度。
讀取 result 中的結果，或從 download_url 下載檔案。

API 參考

啟動非同步查詢

發布 https://api.telemetry.sh/query/async

標題

名稱	型別	描述
內容型別	字串	應用程式/json
授權	字串	您的 API 金鑰，作為原始金鑰或 `Bearer <key>`

身體

名稱	型別	必填	描述
查詢	字串	是的	要執行的 SQL 查詢。
即時	布林值	否	預設為 `true`。傳遞到查詢服務。
json	布林值	否	預設為 `true`。傳遞到查詢服務。
格式	字串	否	結果格式：`"json"`（預設）或`"parquet"`。

回覆（已接受 202）

{
  "status": "accepted",
  "job_id": "550e8400-e29b-41d4-a716-446655440000",
  "format": "json",
  "status_url": "/query/async/550e8400-e29b-41d4-a716-446655440000"
}

投票查詢狀態

獲取 https://api.telemetry.sh/query/async/{job_id}

標題

名稱	型別	描述
授權	字串	您的 API 金鑰，作為原始金鑰或 `Bearer <key>`

回應（200 OK）

直接回傳的 JSON 結果

{
  "status": "success",
  "job_id": "550e8400-e29b-41d4-a716-446655440000",
  "query_status": "completed",
  "format": "json",
  "progress_pct": 100,
  "result": {
    "data": [{ "events": 7 }],
    "key_order": ["events"]
  }
}

可下載的結果

{
  "status": "success",
  "job_id": "550e8400-e29b-41d4-a716-446655440000",
  "query_status": "completed",
  "format": "json",
  "progress_pct": 100,
  "message": "Query completed",
  "created_at": "2025-02-24T12:00:00Z",
  "completed_at": "2025-02-24T12:00:05Z",
  "download_url": "https://storage.example.com/results/...",
  "download_url_expires_in_seconds": 3600
}

當 format 為 "json" 時，下載的檔案包含查詢後設資料以及 result 下的標準查詢結果形狀：

{
  "job_id": "550e8400-e29b-41d4-a716-446655440000",
  "format": "json",
  "result": {
    "data": [
      {
        "city": "paris",
        "average_price": 42.0
      }
    ],
    "key_order": ["city", "average_price"]
  }
}

query_status 欄位將是以下之一：

狀態	描述
`queued`	查詢正在等待執行
`running`	查詢當前正在執行
`completed`	結果透過 `result` 或 `download_url` 提供。
`failed`	查詢失敗。檢查 `error` 欄位。
`cancelled`	查詢已取消。

使用 cURL 進行非同步查詢

# 1. Start the async query
QUERY='SELECT * FROM uber_rides'
RESPONSE=$(curl --fail-with-body -sS --max-time 30 https://api.telemetry.sh/query/async \
  -H "Content-Type: application/json" \
  -H "Authorization: $API_KEY" \
  -d "$(jq -n --arg query "$QUERY" '{query: $query, format: "json", realtime: true, json: true}')") || exit 1
STATUS_URL="https://api.telemetry.sh$(echo "$RESPONSE" | jq -r '.status_url')"

# 2. Poll for at most ten minutes
DEADLINE=$((SECONDS + 600))
while [ "$SECONDS" -lt "$DEADLINE" ]; do
  STATUS=$(curl --fail-with-body -sS --max-time 30 -H "Authorization: $API_KEY" "$STATUS_URL") || exit 1
  QUERY_STATUS=$(echo "$STATUS" | jq -r '.query_status')

  if [ "$QUERY_STATUS" = "completed" ]; then
    if echo "$STATUS" | jq -e '.download_url_expired == true' >/dev/null; then
      echo "Result expired. Start a new query."
      exit 1
    elif echo "$STATUS" | jq -e '.result | type == "object"' >/dev/null; then
      echo "$STATUS" | jq '{result: .result}' > results.json
    else
      DOWNLOAD_URL=$(echo "$STATUS" | jq -r '.download_url // empty')
      if [ -z "$DOWNLOAD_URL" ]; then
        echo "Completed response has neither a result nor an active download URL."
        exit 1
      fi
      curl --fail-with-body -sS --max-time 300 -o results.json "$DOWNLOAD_URL" || exit 1
    fi
    # Both branches have the same result shape, including an empty data array.
    jq '.result' results.json
    exit 0
  elif [ "$QUERY_STATUS" = "failed" ] || [ "$QUERY_STATUS" = "cancelled" ]; then
    echo "Query $QUERY_STATUS: $(echo "$STATUS" | jq -r '.error // .message')"
    exit 1
  elif [ "$QUERY_STATUS" != "queued" ] && [ "$QUERY_STATUS" != "running" ]; then
    echo "Unexpected query status: $QUERY_STATUS"
    exit 1
  fi
  sleep 5
done
echo "Query polling timed out."
exit 1

範例：匯出整個資料表

非同步查詢 API 非常適合全資料表匯出。由於非同步查詢沒有行數限制，因此您可以匯出所有內容並將結果下載為單個檔案。

# Start the export as Parquet
QUERY='SELECT * FROM uber_rides'

RESPONSE=$(curl -s -X POST https://api.telemetry.sh/query/async \
  -H "Content-Type: application/json" \
  -H "Authorization: $API_KEY" \
  -d "$(jq -n --arg query "$QUERY" '{query: $query, format: "parquet", realtime: true, json: true}')")

STATUS_URL="https://api.telemetry.sh$(echo "$RESPONSE" | jq -r '.status_url')"

# Poll until complete
while true; do
  STATUS=$(curl -s -H "Authorization: $API_KEY" "$STATUS_URL")
  QUERY_STATUS=$(echo "$STATUS" | jq -r '.query_status')

  if [ "$QUERY_STATUS" = "completed" ]; then
    DOWNLOAD_URL=$(echo "$STATUS" | jq -r '.download_url // empty')
    if [ -z "$DOWNLOAD_URL" ]; then
      echo "Export completed, but no active download URL is available."
      exit 1
    fi
    curl -o uber_rides_export.parquet "$DOWNLOAD_URL"
    echo "Export complete: uber_rides_export.parquet"
    break
  elif [ "$QUERY_STATUS" = "failed" ]; then
    echo "Export failed: $(echo "$STATUS" | jq -r '.error // .message')"
    exit 1
  fi

  sleep 5
done

SDK邊界

當前JavaScript SDK的query方法呼叫互動式/query 端點。它不會啟動 /query/async、輪詢 status_url、強制執行非同步作業超時，或下載完成的工件。

對於大型 JSON 或 Parquet，使用上面的 HTTP 啟動、輪詢和下載流程出口。應用程式包裝器可以封裝這三個操作，但它仍應執行總投票截止日期，停止 failed，並處理過期的 download_url 作為新匯出而不是重試舊下載無限期地。

常見錯誤

400 Bad Request 如果 JSON 主體無效
400 Bad Request 如果 query 缺失或為空
401 Unauthorized（如果 API 金鑰丟失或無效）
402 Payment Required（如果帳戶被付費牆支票封鎖）
429 Too Many Requests 如果 API 金鑰超過閘道器速率限制

頁面作者與參考資料

Telemetry 編輯團隊負責維護本文；產品團隊審查功能行為、範例和適用範圍。

我們如何審查文件

Apache DataFusion SQL 參考