# レポート API v2 から SQL クエリを実行

Stripe データに対して、アドホックな SQL クエリをプログラムから実行できます。

Reports API v2 の `QueryRun` エンドポイントを使用すると、Stripe データに対する SQL クエリをプログラムで実行できます。これにより、ダッシュボードを使わずに [Sigma editor](https://docs.stripe.com/stripe-data/write-queries.md) で利用可能なクエリと同じクエリを実行でき、データ抽出を自動化し、任意の間隔でクエリをスケジュールし、自社システムに Stripe データを統合できるようになります。

> #### クエリ実行 API の使用
> 
> クエリ実行 API には、有効な [Sigma](https://stripe.com/sigma) サブスクリプションが必要です。

## API キーの権限

クエリ実行を作成するには、API キーに `reporting_write` 権限と `sigma_api_write` 権限の両方が必要です。キーに `reporting_read` 権限しかない場合、既存のクエリ実行は取得できますが、新しいクエリ実行は作成できません。権限の表示と管理には、[API キー](https://dashboard.stripe.com/apikeys)ページを使用します。ダッシュボードで制限付きのキーを作成すると、`reporting_write` は **Sigma** と表示され、`sigma_api_write` は **Sigma API** と表示されます。

## QueryRun を作成する

[QueryRun を作成](https://docs.stripe.com/api/v2/data/reporting/query-runs/create.md?api-version=2026-04-22.preview)するには、`sql` パラメーターに SQL ステートメントを指定します。[Sigma クエリエディタ](https://docs.stripe.com/stripe-data/write-queries.md)でサポートされているものと同じ SQL 構文を使用します。レスポンスには、常に `status=running` と `result=null` を持つ新しい [QueryRun オブジェクト](https://docs.stripe.com/api/v2/data/reporting/query-runs/object.md?api-version=2026-04-22.preview)が含まれます。

```curl
curl -X POST https://api.stripe.com/v2/data/reporting/query_runs \
  -H "Authorization: Bearer <<YOUR_SECRET_KEY>>" \
  -H "Stripe-Version: 2026-04-22.preview" \
  --json '{
    "sql": "SELECT * FROM balance_transactions LIMIT 10"
  }'
```

```json
{
  "id": "qryrun_123",
  "object": "v2.data.reporting.query_run",
  "created": "2025-07-03T01:02:29.964Z",
  "sql": "SELECT * FROM balance_transactions LIMIT 10",
  "status": "running",
  "result": null,
  "result_options": {
    "compress_file": false,
    "result_type": "file"
  },
  "livemode": false
}
```

返された `id` を使用して、クエリ実行の進行状況を追跡します。

## QueryRun を取得する

[QueryRun を取得](https://docs.stripe.com/api/v2/data/reporting/query-runs/retrieve.md?api-version=2026-04-22.preview)してステータスを確認します。クエリが完了したら、`result.file.download_url.url` 内の URL を使用して結果にアクセスします。

```curl
curl https://api.stripe.com/v2/data/reporting/query_runs/qryrun_123 \
  -H "Authorization: Bearer <<YOUR_SECRET_KEY>>" \
  -H "Stripe-Version: 2026-04-22.preview"
```

```json
{
  "id": "qryrun_123",
  "object": "v2.data.reporting.query_run",
  "created": "2025-07-03T01:02:29.964Z",
  "sql": "SELECT * FROM balance_transactions LIMIT 10",
  "status": "succeeded",
  "result": {
    "file": {
      "content_type": "csv",
      "download_url": {
        "expires_at": "2025-07-03T01:10:46.679Z","url": "https://stripeusercontent.com/files/us-west-2/download/wksp_123/file_123/qryrun_123.csv..."
      },
      "size": "512"
    },
    "type": "file"
  },
  "result_options": {
    "compress_file": false,
    "result_type": "file"
  },
  "livemode": false
}
```

> ダウンロード URL の有効期間は短く、5 分で期限切れになります。URL を再生成する必要がある場合は、`QueryRun` オブジェクトを再度取得してください。

## Webhook

ポーリングする代わりに、Webhook をリッスンして、クエリの完了を確認できます。クエリの実行が正常に完了すると、Stripe は [v2.data.reporting.query_run.succeeded](https://docs.stripe.com/api/v2/data/reporting/query-runs/event-types.md?api-version=2026-04-22.preview#v2.data.reporting.query_run.succeeded) Webhook を送信します。失敗した場合、Stripe は代わりに [v2.data.reporting.query_run.failed](https://docs.stripe.com/api/v2/data/reporting/query-runs/event-types.md?api-version=2026-04-22.preview#v2.data.reporting.query_run.failed) Webhook を送信します。Webhook を受信したら、上記のように `QueryRun` を取得し、結果の URL にアクセスします。

## その他の結果オプション

### ファイル圧縮をリクエストする

結果セットが大きい場合は、zip で圧縮された出力ファイルを受け取るために、`result_options.compress_file=true` を設定します。

```curl
curl -X POST https://api.stripe.com/v2/data/reporting/query_runs \
  -H "Authorization: Bearer <<YOUR_SECRET_KEY>>" \
  -H "Stripe-Version: 2026-04-22.preview" \
  --json '{
    "sql": "SELECT * FROM balance_transactions",
    "result_options": {
        "compress_file": true
    }
  }'
```

## Organization APIキーを使用する

Query Run API は [Organization API キー](https://docs.stripe.com/keys.md#organization-api-keys) をサポートしています。

### 組織全体でクエリを実行する

`Stripe-Context` ヘッダーなしで Organization API キーを使用すると、クエリは組織全体モードで実行されます。これは、[Sigma for Organizations](https://docs.stripe.com/stripe-data/sigma-organizations.md) でクエリを実行する場合と同じです。このモードでは、クエリは組織内のすべてのダイレクトアカウントのデータにアクセスでき、データテーブルでは各行が属するアカウントを識別するための `account` 列を使用できます。

```curl
curl -X POST https://api.stripe.com/v2/data/reporting/query_runs \
  -H "Authorization: Bearer {{ORG_SECRET_KEY}}" \
  -H "Stripe-Version: 2026-04-22.preview" \
  --json '{
    "sql": "SELECT account, id, amount FROM balance_transactions LIMIT 10"
  }'
```

### 単一のアカウントを対象とするクエリを実行する

組織内の 1 つのアカウントを対象とするクエリを実行するには、[Stripe-Context](https://docs.stripe.com/context.md) ヘッダーをそのアカウントに設定します。

```curl
curl -X POST https://api.stripe.com/v2/data/reporting/query_runs \
  -H "Authorization: Bearer {{ORG_SECRET_KEY}}" \
  -H "Stripe-Version: 2026-04-22.preview" \
  -H "Stripe-Context: {{CONTEXT_ID}}" \
  --json '{
    "sql": "SELECT * FROM balance_transactions LIMIT 10"
  }'
```

## 制限

v2 名前空間の API の一般的な詳細については、[API v2 概要](https://docs.stripe.com/api-v2-overview.md)をご覧ください。一般的な API レート制限については、[レート制限](https://docs.stripe.com/rate-limits.md)ページをご覧ください。Query Run API の具体的な制限は次のとおりです。

### 同時クエリ実行

API は、`QueryRuns` が `running` 状態になれる同時実行数を、アカウントまたは組織ごとに本番環境では 500、テスト環境では 100 に制限しています。この制限を超えると、API はステータスコード `429` を返します。実行中のクエリが完了するまで待つことで、処理枠を確保できます。

### クエリ実行のタイムアウト

実行時間が 90 分を超えるクエリは自動的に終了され、`QueryRun` は `status=failed` に移行します。

### ファイルサイズ

クエリ結果でサポートされる最大ファイルサイズは 5 GB です。この上限に達した場合は、`result_options.compress_file=true` を設定して圧縮結果をリクエストできます。

### ファイルの保持期間

クエリ実行結果は 90 日間保持されます。