> ## Documentation Index
> Fetch the complete documentation index at: https://docs.querying.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Amazon S3、Google Cloud Storage、BigQuery への結果エクスポート

> 完了したすべてのタスクと採点済みのモニター回答を、自社バケットの時間別・日別 JSON Lines ファイル、または BigQuery テーブルのパーティションとして受け取ります。

エクスポートは 1 時間ごと、または UTC の 1 日ごとに、その期間の結果を gzip 圧縮の JSON Lines として Amazon S3 や Google Cloud Storage のバケットに書き込むか、BigQuery テーブルのパーティションに読み込みます。データウェアハウスは他のソースと同じ方法で読み込めるため、ポーリングのループは不要です。

バケットまたはデータセットに、当社のエクスポート用 ID への書き込み権限を付与するだけで、キーやパスワードを共有する必要はありません。このページのキー、バケット、アカウント ID、ロールはすべて例です。

## エクスポートされるデータ

| データセット | 行 | 期間の基準 | 同じフィールド |
| - | - | - | - |
| `tasks` | `COMPLETED` または `FAILED` で終了したアカウントのすべてのタスク | `completedAt` | [`GET /v1/async/task/{id}`](/ja/api-reference/get-task) と webhook |
| `monitor_results` | アカウントのすべてのモニターが採点したすべての回答 | `ranAt` | [`GET /v1/monitors/{id}/results?includeEvidence=true`](/ja/api-reference/monitors/export-results) |

アカウントのどのキーで送信したタスクも、Playground とモニターが作成したタスクもすべて含まれます。1 つの期間には、時刻が `[windowStart, windowEnd)` に入る行だけが正確に入ります。

**配信のタイミング。** 期間は閉じてから 10 分後に配信対象になるため、境界で確定した課金も含まれます。配信対象の期間は 15 分ごとに実行されるジョブが取り上げるので、通常は期間が閉じてから 10〜25 分後に配信が始まります。

## エクスポートを設定する

**1. エクスポート用 ID を確認する**

```bash theme={"theme":"css-variables"}
curl https://api.querying.ai/v1/exports/identity \
  -H "Authorization: Bearer $QUERYING_API_KEY"
```

```json theme={"theme":"css-variables"}
{
  "success": true,
  "identity": {
    "accountKey": "acct_3f9a1c2b7d4e",
    "gcp": { "serviceAccount": "querying-export@example-project.iam.gserviceaccount.com" },
    "aws": {
      "federatedPrincipal": "accounts.google.com",
      "audience": "117000000000000000001",
      "oaud": "querying-result-export",
      "roleSessionName": "querying-acct_3f9a1c2b7d4e",
      "trustPolicy": { "Version": "2012-10-17", "Statement": ["..."] }
    }
  }
}
```

`accountKey` はお客様のフォルダーとテーブルの名前です。当社が書き込むすべてのパスとテーブルにこの値が入るため、複数の querying.ai アカウントが 1 つのバケットやデータセットを共有しても、それぞれ自分のファイルだけを書き込みます。権限は上の例ではなく、実際のレスポンスに表示された ID に付与してください。

**2. 権限を付与する**

配信先へのアクセス権を ID に付与します。S3、Cloud Storage、BigQuery については[権限を付与する](#権限を付与する)を参照してください。

**3. エクスポートを作成する**

`POST /v1/exports` が権限を確認し、エクスポートを保存します。[エクスポートを作成する](#エクスポートを作成する)を参照してください。

**4. 最初の配信を確認する**

`GET /v1/exports/{id}/runs` が各期間とそのステータスを一覧表示します。[配信履歴](#配信履歴)を参照してください。

## 権限を付与する

### Amazon S3

当社の Google ID が引き受けられる IAM ロールを AWS アカウントに作成します。ID のレスポンスにある `trustPolicy` をロールの信頼ポリシーとして使います。このポリシーは、当社のエクスポート用 ID がお客様アカウントのセッション名で要求した場合だけを受け入れます。

```json theme={"theme":"css-variables"}
{
  "Version": "2012-10-17",
  "Statement": [{
    "Effect": "Allow",
    "Principal": { "Federated": "accounts.google.com" },
    "Action": "sts:AssumeRoleWithWebIdentity",
    "Condition": { "StringEquals": {
      "accounts.google.com:aud": "117000000000000000001",
      "accounts.google.com:oaud": "querying-result-export",
      "sts:RoleSessionName": "querying-acct_3f9a1c2b7d4e"
    } }
  }]
}
```

ロールがプレフィックス配下に書き込めるよう、権限ポリシーをアタッチします。

```json theme={"theme":"css-variables"}
{
  "Version": "2012-10-17",
  "Statement": [{
    "Effect": "Allow",
    "Action": "s3:PutObject",
    "Resource": "arn:aws:s3:::acme-geo/querying/*"
  }]
}
```

バケットがカスタマー管理の KMS キーで暗号化している場合は、そのキーに `kms:GenerateDataKey` も許可します。

### Google Cloud Storage

バケットでエクスポート用サービスアカウントに **Storage Object User**（`roles/storage.objectUser`）を付与します。ファイルを作成し、期間を再送したときにファイルを置き換えます。

```bash theme={"theme":"css-variables"}
gcloud storage buckets add-iam-policy-binding gs://acme-geo \
  --member="serviceAccount:querying-export@example-project.iam.gserviceaccount.com" \
  --role="roles/storage.objectUser"
```

付与をお客様のフォルダーに限定するには、IAM 条件
`resource.name.startsWith("projects/_/buckets/acme-geo/objects/querying/acct_3f9a1c2b7d4e/")` を追加します。

### BigQuery

データセットでエクスポート用サービスアカウントに **BigQuery Data Editor**（`roles/bigquery.dataEditor`）を付与します。読み込みジョブは当社のプロジェクトで実行するため読み込み費用はかからず、お支払いはストレージと実行するクエリの分だけです。

```bash theme={"theme":"css-variables"}
bq add-iam-policy-binding \
  --member="serviceAccount:querying-export@example-project.iam.gserviceaccount.com" \
  --role="roles/bigquery.dataEditor" acme-analytics:geo_raw
```

## エクスポートを作成する

エンジンのスコープがない API キーを使ってください。エクスポートはアカウントのすべての結果を送るため、一部のエンジンに限定されたキーでは `403 KEY_SCOPE` になります。

```bash Amazon S3 theme={"theme":"css-variables"}
curl -X POST https://api.querying.ai/v1/exports \
  -H "Authorization: Bearer $QUERYING_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "destination": {
      "type": "s3",
      "bucket": "acme-geo",
      "region": "us-east-1",
      "roleArn": "arn:aws:iam::123456789012:role/querying-export",
      "prefix": "querying"
    },
    "interval": "daily",
    "data": ["tasks", "monitor_results"]
  }'
```

```bash Google Cloud Storage theme={"theme":"css-variables"}
curl -X POST https://api.querying.ai/v1/exports \
  -H "Authorization: Bearer $QUERYING_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "destination": { "type": "gcs", "bucket": "acme-geo", "prefix": "querying" },
    "interval": "hourly",
    "data": ["tasks"]
  }'
```

```bash BigQuery theme={"theme":"css-variables"}
curl -X POST https://api.querying.ai/v1/exports \
  -H "Authorization: Bearer $QUERYING_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "destination": { "type": "bigquery", "projectId": "acme-analytics", "datasetId": "geo_raw" },
    "interval": "daily",
    "startAt": "2026-10-01T00:00:00Z"
  }'
```

| フィールド | 必須 | 説明 |
| - | - | - |
| `destination.type` | はい | `s3`、`gcs` または `bigquery`。 |
| `destination.bucket` | S3、GCS | バケット名。 |
| `destination.prefix` | いいえ | バケット内のフォルダー。最大 256 文字の相対パスです（先頭の `/`、`.` や `..` のセグメントは不可）。末尾に `/` が付加されます。 |
| `destination.region` | S3 | バケットの AWS リージョン（例: `us-east-1`）。 |
| `destination.roleArn` | S3 | [権限を付与する](#amazon-s3)で作成したロール。`arn:aws:iam::<account>:role/<name>` の形式です。 |
| `destination.projectId`, `destination.datasetId` | BigQuery | Google Cloud のプロジェクトとデータセット。 |
| `interval` | いいえ | `hourly` または `daily`（既定）。エクスポートの存続期間中は変更できません。 |
| `data` | いいえ | `tasks`、`monitor_results`、または両方（既定）。 |
| `startAt` | いいえ | ISO 8601 の時刻。未来は指定できず、最大 30 日前までです。その時刻を含む期間が最初の期間になります。既定は現在です。 |

保存する前に、エクスポートは権限を確認します。S3 と Cloud Storage では `<prefix><accountKey>/_querying/connection-check.json` を書き込み、BigQuery ではデータセットを読み取ってそのロケーションを記録します。確認に失敗した場合は何も保存されません。1 アカウントあたり最大 10 件のエクスポートを作成できます。

レスポンスは `201` で、エクスポートを返します。

```json theme={"theme":"css-variables"}
{
  "success": true,
  "export": {
    "id": "6a1d0f3c-...",
    "destination": {
      "type": "bigquery",
      "projectId": "acme-analytics",
      "datasetId": "geo_raw",
      "location": "US",
      "tables": [
        "acme-analytics.geo_raw.querying_tasks_v1_acct_3f9a1c2b7d4e",
        "acme-analytics.geo_raw.querying_monitor_results_v1_acct_3f9a1c2b7d4e"
      ]
    },
    "interval": "daily",
    "data": ["tasks", "monitor_results"],
    "enabled": true,
    "schemaVersion": 1,
    "nextWindowStart": "2026-10-01T00:00:00.000Z",
    "createdAt": "2026-10-19T09:00:00.000Z",
    "deliveredThrough": null,
    "failedRuns": 0,
    "retryingRuns": 0
  }
}
```

S3 と Cloud Storage では、`destination` はバケットの設定をそのまま返し、ファイルが届くフォルダー `path`（例: `s3://acme-geo/querying/acct_3f9a1c2b7d4e/`、`gs://acme-geo/querying/acct_3f9a1c2b7d4e/`）を加えます。`nextWindowStart` は次に計画される期間の開始時刻です。

### エラー

| ステータス | コード | 原因 |
| - | - | - |
| `400` | `VALIDATION_ERROR` | JSON が不正か、フィールドが範囲外です。メッセージにフィールド名が示されます（例: `destination.region: region is the bucket's AWS region, e.g. us-east-1`）。 |
| `403` | `KEY_SCOPE` | API キーが一部のエンジンに限定されています。 |
| `409` | `EXPORT_LIMIT` | アカウントにすでに 10 件のエクスポートがあります。 |
| `422` | `EXPORT_DESTINATION_UNREACHABLE` | 接続確認に失敗しました。メッセージにストレージ側の理由が入ります。通常は権限の不足です。 |
| `502` | `EXPORT_CHECK_FAILED` | 配信先に到達できませんでした。もう一度お試しください。 |
| `503` | `EXPORTS_NOT_CONFIGURED` | この種類の配信先へのエクスポートは利用できません。 |

## ファイルとテーブル

### S3 と Cloud Storage のファイル

```text theme={"theme":"css-variables"}
s3://acme-geo/querying/acct_3f9a1c2b7d4e/tasks/v1/dt=2026-10-08/part-00000.jsonl.gz
s3://acme-geo/querying/acct_3f9a1c2b7d4e/tasks/v1/dt=2026-10-08/_manifest.json
s3://acme-geo/querying/acct_3f9a1c2b7d4e/monitor_results/v1/dt=2026-10-08/hour=13/part-00000.jsonl.gz
```

* ディレクトリは Hive パーティション（`dt=`、時間別エクスポートなら `hour=`）に従うため、Athena、BigQuery 外部テーブル、Spark が列として読み取ります。
* `v1` はスキーマのバージョン（エクスポートの `schemaVersion`）です。列を壊す変更は `v2` として並べて提供します。
* 1 つの期間は、時刻順に最大 100,000 行ずつの part ファイルに分かれます。
* `_manifest.json` は最後に書き込みます。マニフェストが存在する期間を読み込み、part の一覧はマニフェストから読んでください。

```json theme={"theme":"css-variables"}
{
  "schemaVersion": 1,
  "data": "tasks",
  "windowStart": "2026-10-08T00:00:00.000Z",
  "windowEnd": "2026-10-09T00:00:00.000Z",
  "rows": 20000,
  "files": [{ "key": "querying/acct_3f9a1c2b7d4e/tasks/v1/dt=2026-10-08/part-00000.jsonl.gz", "rows": 20000, "bytes": 1990096 }],
  "deliveredAt": "2026-10-09T00:16:02.114Z"
}
```

マニフェストの `rows` は part ファイルの行数と一致し、配信履歴の run の `rows` とも一致します。ファイル名は期間だけで決まるため、再送した期間は同じオブジェクトを置き換えます。

### BigQuery テーブル

BigQuery エクスポートは `querying_tasks_v1_<accountKey>` と `querying_monitor_results_v1_<accountKey>` に読み込みます。テーブルは最初の読み込みで作成され、`completedAt` または `ranAt` でパーティション分割されます（日別、時間別エクスポートは時間別）。期間ごとに自分のパーティションを置き換えるため、再送した期間が二重になることはありません。`payload`、`response`、`sources`、`scoringContext` は `JSON` 列です。

```sql theme={"theme":"css-variables"}
SELECT taskType, JSON_VALUE(payload.prompt) AS prompt, JSON_VALUE(response.text) AS answer
FROM `acme-analytics.geo_raw.querying_tasks_v1_acct_3f9a1c2b7d4e`
WHERE DATE(completedAt) = "2026-10-08" AND status = "COMPLETED";
```

## 行スキーマ (v1)

### `tasks`

| フィールド | 型 | BigQuery の型 | 説明 |
| - | - | - | - |
| `id` | string | `STRING` | タスク ID。 |
| `taskType` | string | `STRING` | エンジン（例: `CHATGPT`）。 |
| `status` | string | `STRING` | `COMPLETED` または `FAILED`。 |
| `priority` | integer | `INT64` | 送信した値。 |
| `idempotencyKey` | string or null | `STRING` | 送信した場合はお客様の冪等キー。 |
| `createdAt`, `completedAt` | timestamp | `TIMESTAMP` | UTC、マイクロ秒精度。 |
| `monitorId` | string or null | `STRING` | 実行したモニター。 |
| `creditsCharged` | decimal | `NUMERIC` | タスクに課金されたクレジット。小数点以下 2 桁まで（例: `1.25`）。失敗したタスクは `0`。整数ではなく小数として読んでください。 |
| `payload` | object | `JSON` | 送信した payload。 |
| `response` | object or null | `JSON` | `GET /v1/async/task/{id}` が返す結果。タスクが失敗した場合は `null`。 |
| `error` | string or null | `STRING` | コードで始まる失敗理由。完了時は `null`。 |

### `monitor_results`

| フィールド | 型 | BigQuery の型 | 説明 |
| - | - | - | - |
| `id`, `monitorId`, `taskId` | string | `STRING` | 結果、モニター、タスクの ID。 |
| `engine`, `prompt` | string | `STRING` | どこで何を質問したか。 |
| `mentioned`, `cited` | boolean | `BOOL` | ブランドの言及、お客様ドメインの引用。 |
| `position` | integer or null | `INT64` | 最初のブランド言及の文字位置。 |
| `competitorHits` | string array | `STRING`（repeated） | 回答に出た競合。 |
| `sources` | array | `JSON` | `{url, label, position}` 形式の引用。 |
| `answerText` | string or null | `STRING` | スコアの読み取りに使った回答。 |
| `scoringContext` | object or null | `JSON` | 当時の採点定義。 |
| `latitude`, `longitude` | number or null | `FLOAT64` | 位置モニターが質問した地点。 |
| `ranAt` | timestamp | `TIMESTAMP` | UTC、マイクロ秒精度。 |

## 配信履歴

データセットごとの 1 期間が 1 つの run です。新しい順に一覧表示します。

```bash theme={"theme":"css-variables"}
curl "https://api.querying.ai/v1/exports/$EXPORT_ID/runs?status=failed" \
  -H "Authorization: Bearer $QUERYING_API_KEY"
```

```json theme={"theme":"css-variables"}
{
  "success": true,
  "runs": [{
    "id": "3c9e1b7a-...",
    "data": "tasks",
    "windowStart": "2026-10-08T00:00:00.000Z",
    "windowEnd": "2026-10-09T00:00:00.000Z",
    "status": "failed",
    "attempts": 8,
    "nextAttemptAt": null,
    "rows": null,
    "bytes": null,
    "files": [],
    "error": "S3 PutObject s3://acme-geo/... failed: HTTP 403 AccessDenied: Access Denied",
    "deliveredAt": null
  }],
  "nextCursor": null
}
```

| `status` | 意味 |
| - | - |
| `pending` | 配信待ち、または失敗後の再試行待ち。`nextAttemptAt` にその時刻が入ります。 |
| `running` | 配信中です。 |
| `delivered` | 書き込み済みです。`rows`、`bytes`、`files`、`deliveredAt` が設定されます。 |
| `failed` | 8 回の試行がすべて失敗しました。再送するまで何も起きません。 |

`status`、`data`（`tasks` または `monitor_results`）、`limit`（1〜200、既定値 50）で絞り込めます。次のページは `nextCursor` を `cursor` として渡してください。

* **自動再試行。** 失敗した試行は 15 分後に再試行され、その後は間隔を倍にしながら最大 12 時間間隔で、合計 8 回まで試行します。`error` にはストレージ側の理由が入るため、権限の不足はまずここに表示されます。
* **期間を再送する。** `POST /v1/exports/{id}/runs/{runId}/retry` は期間を今すぐ送ります。権限を直した後の失敗した期間や、書き直したい配信済みの期間に使います。`attempts` をリセットし、run を `pending` として返します。配信中の run には `409 EXPORT_RUN_RUNNING` を返します。
* **エクスポートの健全性。** `GET /v1/exports` と `GET /v1/exports/{id}` は `deliveredThrough`（最後に配信された期間の終わり）、`failedRuns`、`retryingRuns`（少なくとも 1 回失敗した pending の run）を加えて返します。

## 一時停止、再開、削除

* `PATCH /v1/exports/{id}` に `{"enabled": false}` を送るとエクスポートを一時停止します。`{"enabled": true}` で再開し、抜けた期間を最大 30 日前まで追って送ります。
* `DELETE /v1/exports/{id}` はエクスポートを停止します。配信済みのファイルとパーティションはお客様のストレージに残ります。
* 配信先、間隔、データセットは変更できません。新しいエクスポートを作成し、古いものを削除してください。

## エンドポイント

| メソッドとパス | 用途 |
| - | - |
| [`GET /v1/exports/identity`](/ja/api-reference/exports/get-identity) | 権限を付与する ID とお客様のアカウントキー |
| [`POST /v1/exports`](/ja/api-reference/exports/create-export) | 配信先を接続する |
| [`GET /v1/exports`](/ja/api-reference/exports/list-exports) | 配信の健全性付きのエクスポート一覧 |
| [`GET /v1/exports/{id}`](/ja/api-reference/exports/get-export) | 1 件のエクスポート |
| [`PATCH /v1/exports/{id}`](/ja/api-reference/exports/update-export) | 一時停止または再開 |
| [`DELETE /v1/exports/{id}`](/ja/api-reference/exports/delete-export) | エクスポートを停止する |
| [`GET /v1/exports/{id}/runs`](/ja/api-reference/exports/list-runs) | 配信履歴 |
| [`POST /v1/exports/{id}/runs/{runId}/retry`](/ja/api-reference/exports/retry-run) | 期間を再送する |

所有していないエクスポートには `404 NOT_FOUND` を返します。


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.