イベントの一覧表示

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 でのみ有効です。

{
  "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
}

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

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 における個人データでは、保存される内容、保存期間、削除方法を説明しています。どのフィールドにも特別な種類の個人データ(健康、生体情報、宗教、政治的意見、性的指向)を送信しないでください。