使用量の分析とクエリ非公開プレビュー

従量使用状況データをクエリおよび分析する方法をご紹介します。

Meter Usage Analytics APIを使用して、顧客のメーター使用状況データをクエリおよび分析します。これにより、カスタムの使用状況ダッシュボードを作成し、レポートを生成し、メーター全体の使用量パターンを判断することができます。

使用状況データをクエリ

Meter Usage Analytics APIは、指定された期間内の顧客の使用量の集計データを返します。期間でデータをクエリしたり、メーターのディメンションでフィルタリングしたり、複数のメーターで同時にクエリしたりできます。

単一メーターの使用状況を取得する

特定の顧客と時間範囲の使用状況データを取得する:

メーターディメンションでフィルタリングおよびグループ化したメーターの使用状況を取得する

プレミアム階層でフィルタリングされ、モデルごとにグループ化されている使用状況データをクエリ:

複数のメーターの使用状況を取得

さまざまなフィルターとグループを使用して、複数のメーターの使用状況をクエリします。

使用状況ダッシュボードの構築

API データを使用して、さまざまなディメンションの使用状況を示す積み上げグラフなどの視覚化を作成できます。次の例は、モデル別の API 使用状況を示すグラフのデータを構造化する方法を示しています。

このリクエストへの応答の例を次に示します。

レスポンスを表示

{
  "data": [
    {
      "bucket_start_time": 1735689600,
      "bucket_end_time": 1735776000,
      "bucket_value": 1500,
      "meter_id": "mtr_1234567890",
      "dimensions": {
        "model": "gpt-4"
      }
    },
    {
      "bucket_start_time": 1735689600,
      "bucket_end_time": 1735776000,
      "bucket_value": 800,
      "meter_id": "mtr_1234567890",
      "dimensions": {
        "model": "gpt-3.5-turbo"
      }
    },
    {
      "bucket_start_time": 1735776000,
      "bucket_end_time": 1735862400,
      "bucket_value": 2100,
      "meter_id": "mtr_1234567890",
      "dimensions": {
        "model": "gpt-4"
      }
    },
    {
      "bucket_start_time": 1735776000,
      "bucket_end_time": 1735862400,
      "bucket_value": 950,
      "meter_id": "mtr_1234567890",
      "dimensions": {
        "model": "gpt-3.5-turbo"
      }
    }
  ]
}

このサンプルコードを使用して、バックエンドの API からデータを引き出し、フロントエンドで積み上げ棒グラフとしてユーザーに表示します。

バックエンド

// Step 1: Extract the data from the Stripe API response
const data = stripeApiResponse.data;

// Step 2: Create a dictionary to store the processed data
const processedData = {};

// Step 3: Iterate through the data and organize it by date and model
data.forEach(point => {
  const date = new Date(point.bucket_start_time * 1000).toISOString().split('T')[0];
  const model = point.dimensions.model;
  const value = point.bucket_value;

  if (!processedData[date]) {
    processedData[date] = {};
  }

  processedData[date][model] = value;
});

// Step 4: Create a list of unique models and sort them
const models = [...new Set(data.map(point => point.dimensions.model))].sort();

// Step 5: Prepare the data for charting
const chartData = [];
Object.keys(processedData).sort().forEach(date => {
  const dataPoint = { date };
  let cumulativeValue = 0;

  models.forEach(model => {
    const value = processedData[date][model] || 0;
    dataPoint[`${model}_start`] = cumulativeValue;
    cumulativeValue += value;
    dataPoint[`${model}_end`] = cumulativeValue;
    dataPoint[model] = value; // For simple stacked charts
  });

  chartData.push(dataPoint);
});

// Return chart data for front end chart library usage
return chartData;

フロントエンド

// Step 1: Fetch usage chart data from your back end
const chartData = await fetch('/api/customer_usage/:customer_id').then(r => r.json());

// Step 2: Extract unique models from the chart data
const models = Object.keys(chartData[0]).filter(key =>
  key !== 'date' && !key.endsWith('_start') && !key.endsWith('_end')
);

// Step 3: Use the chart data to create your stacked bar chart
// Example using D3 or Recharts:
createStackedChart({
  data: chartData.map(point => ({
    date: point.date,
    'gpt-4': point['gpt-4'] || 0,
    'gpt-3.5-turbo': point['gpt-3.5-turbo'] || 0
  })),
  stackKeys: models,
  xKey: 'date',
  title: 'Daily API Usage by Model'
});

レート制限

Meter Usage Analytics API には、Stripe 全体の API レート制限とは別に、アカウントごとに 1 秒あたり 100 リクエストという独自のレート制限があります。この制限を超えると、API は 429 Too Many Requests ステータスコードを返します。

ベストプラクティス

データの鮮度を処理する

使用状況データには若干の遅延が発生する場合があります。レスポンスの data_refreshed_at フィールドを使用して、データの鮮度を把握できます。リアルタイムのダッシュボードやアラートを構築する際には、このレイテンシーも考慮してください。

クエリをカスタマイズする

次のベストプラクティスに従います。

適切な value_grouping_window 値を使用して、細かさとパフォーマンスのバランスを取ります。
dimension_filters を適用して、特定のセグメントのみが必要な場合にデータ量を減らします。
関連する使用状況パターンを分析する際に、1 回のリクエストで複数のメーターをクエリ。

データサイズの制限

応答が過度に大きくなるのを防ぐために、メーターごとに次の制限が適用されます。

最大 2 つの dimension_group_by_keys
最大 10 個の dimension_filters
最大 3 つの tenant_filters

エラーを処理する

API は標準 HTTP ステータスコードと構造化されたエラー応答を返します。

{
  "error": {
    "type": "invalid_request_error",
    "code": "invalid_time_range",
    "message": "Param start_time should not be greater than end_time"
  }
}