# イベントの一覧表示

`GET /v1/events` · 権限 `events:read`

environment のイベントを古い順に返します。各イベントは、Webhook で配信されるものと同じ `id` を持つ同じドキュメントです。イベントは、すべてのプランで 30 日間保持されます。

システムで Webhook を受信できない場合、または障害後の欠落を埋める場合にこのエンドポイントを使用します。最後に処理した `next_cursor` を保存しておき、そこから続けて取得してください。

環境は常に API キーから決まります。環境を指定するパラメータはありません。

## リクエスト

| パラメータ | 位置 | 必須 | 説明 |
|---|---|---|---|
| `after` | query | いいえ | 前のレスポンスの `next_cursor`、または今後記録されるイベントのみを受け取るための `latest`。指定しない場合、保持されている最も古いイベントから一覧が始まります。 |
| `types` | query | いいえ | カンマ区切りのイベントタイプ。最大 20 件(例: `user.created,user.deleted`)。指定しない場合は、すべてのタイプが返されます。 |
| `org_id` | query | いいえ | この組織(`org_…`)のイベントのみ。 |
| `limit` | query | いいえ | ページサイズ。1〜100。デフォルトは 20。 |
| `payload` | query | いいえ | `thin`(デフォルト)または `full`。`full` には `users:read` 権限も必要です。完全なペイロードが利用可能になるまでは、`full` を指定しても thin ペイロードが返されます。 |
| `purpose` | query | いいえ | `tail`(デフォルト)または `webhooks_listen`。`webhooks_listen` は `development` および `staging` の環境でのみ受け付けられます。 |

## レスポンス

`200 OK`:

| フィールド | 説明 |
|---|---|
| `data` | 順番どおりのイベント。すべてのイベントは、environment 内で増加する `seq` を持ちます。 |
| `next_cursor` | 常に含まれます。`data` が空の場合でも、次のリクエストで `after` として渡してください。 |
| `has_more` | 後続のイベントがある場合は `true`。すぐに再リクエストしてください。`false` の場合は、再度ポーリングする前に待機してください(5〜60 秒)。 |

カーソルは `types` や `org_id` に依存しません。フィルターを変更しても、同じ位置から続けて取得できます。カーソルは、発行された environment でのみ有効です。

```json
{
  "data": [
    {
      "id": "evt_01j9xk3m7q8r2s4t6v8w0y2z4a",
      "type": "connection.deleted",
      "schema_version": 1,
      "environment_id": "env_01j9xk3m7q8r2s4t6v8w0y2z4e",
      "occurred_at": "2026-11-03T08:15:42.120Z",
      "recorded_at": "2026-11-03T08:15:42.140Z",
      "seq": 4182,
      "data": {
        "object": {"id": "conn_01j9xk3m7q8r2s4t6v8w0y2z4f", "status": "deleted"},
        "object_version": 2
      },
      "context": {"actor": {"type": "system"}, "request_id": "0192a6c1-7d3e-7a10-9b2c-3d4e5f607182"}
    }
  ],
  "next_cursor": "eyJ2IjoxfQ.c2lnbmF0dXJl",
  "has_more": false
}
```

## 例: 新しいイベントをポーリングする

```bash
cursor=latest
while true; do
  page=$(curl -sS -G https://api.keenauth.com/v1/events \
    -H "Authorization: Bearer $KEENAUTH_API_KEY" \
    --data-urlencode "after=$cursor" --data-urlencode "limit=100")
  echo "$page" | jq -c '.data[]'
  cursor=$(echo "$page" | jq -r '.next_cursor')
  [ "$(echo "$page" | jq -r '.has_more')" = "true" ] || sleep 10
done
```

CLI でも `keenauth events tail` を使用して同じことができます。

## エラー

すべてのエラーは、安定した `code` を含む `application/problem+json` の本文です。

| HTTP | `code` | 発生条件 |
|---|---|---|
| 400 | `invalid_cursor` | カーソルの形式が不正、または別の environment で発行されたものです。 |
| 401 | `unauthenticated` | API キーがない、無効、または取り消されている。 |
| 403 | `insufficient_permissions` | キーに `events:read` がない、または `users:read` がない状態で `payload=full` を指定した。 |
| 403 | `test_feature_not_in_production` | 本番環境で `purpose=webhooks_listen` を指定した。 |
| 422 | `validation_failed` | パラメータが無効、または繰り返し指定されている。`errors[].pointer` が該当パラメータを示します。 |
| 429 | `rate_limited` | レート制限を超えた。`Retry-After` に従ってください。 |
| 503 | `service_unavailable` | 依存先が一時的に利用できない。後で再試行してください。 |

## 個人データ

このエンドポイントは個人データ(イベント)を扱います。[KeenAuth API における個人データ](/docs/policies/personal-data)では、保存される内容、保存期間、削除方法を説明しています。どのフィールドにも特別な種類の個人データ(健康、生体情報、宗教、政治的意見、性的指向)を送信しないでください。