# ログを一覧表示

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

環境のログレコード(サインイン、セッション、トークン、多要素認証、攻撃保護など)を、新しいものから順にカーソルベースのページネーションで一覧表示します。プランの保持期間(Free 7 日、Startup 14 日、Business 30 日、Enterprise 90 日)より古いレコードは返されません。

## リクエスト

| パラメーター | 場所 | 必須 | 説明 |
|---|---|---|---|
| `limit` | query | いいえ | ページサイズ。1〜100。デフォルトは 20。 |
| `after` | query | いいえ | `list_metadata.after` から取得した不透明なカーソル(より古いレコード)。`before` と同時に指定できません。 |
| `before` | query | いいえ | `list_metadata.before` から取得した不透明なカーソル(より新しいレコード)。`after` と同時に指定できません。 |
| `from` | query | いいえ | RFC 3339 形式の時刻。この時刻以降のレコードを返します。保持期間内である必要があります。 |
| `to` | query | いいえ | RFC 3339 形式の時刻。この時刻より前のレコードを返します。`from` より後である必要があります。 |
| `type` | query | いいえ | `authentication.` や `session.created` などのログタイプの接頭辞。パラメーターを繰り返すことで最大 20 個の値を指定できます。いずれかに一致するレコードが返されます。 |
| `outcome` | query | いいえ | `success`、`failure`、`denied`、または `error`。 |
| `user_id`、`org_id`、`application_id`、`connection_id`、`directory_id`、`session_id` | query | いいえ | 接頭辞付き ID(`usr_`、`org_`、`app_`、`conn_`、`dir_`、`ses_`)の完全一致。 |
| `request_id` | query | いいえ | リクエストの `Idp-Request-Id`(UUID)。たとえばホストされたサインインのエラーページに表示される ID です。 |
| `correlation_id` | query | いいえ | ワークフローの `Idp-Correlation-Id`(UUID)。 |
| `ip` | query | いいえ | IP アドレスまたは CIDR ブロック(`203.0.113.0/24`)。`audit-events:read_ip` 権限が必要です。 |
| `ip_country` | query | いいえ | IP の国。ISO 3166-1 alpha-2 の大文字(`DE`)。 |
| `q` | query | いいえ | マスクされた識別子ヒントの接頭辞(`j***@`)。`users:read_pii` 権限が必要です。 |

レコードは常に `occurred_at` の順、新しいものから並べられます。`order` パラメーターはありません(`order=desc` は受け付けられ、それ以外の値は `validation_failed` で失敗します)。カーソルは、発行された時点のフィルターと組み合わせた場合にのみ有効です。

`ip` および `q` フィルターは、結果を絞り込むだけでも、その権限が必要です。権限がない場合、検索が実行される前に `403 insufficient_permissions` でリクエストが失敗します。そのため、キーは読み取る権限のない値を推測することはできません。

## レスポンス

`200 OK` を返します。`data` にはそのページのレコードが入ります。`list_metadata.after` はより古いレコードを、`list_metadata.before` はより新しいレコードを指します(該当がない場合は `null`)。総件数は返されません。空のフィールドは `null` になります。

`ip`、`ip_asn`、`user_agent`、`user_agent_family` は、キーが `audit-events:read_ip` 権限を持つ場合にのみ含まれ、`identifier_hint` は `users:read_pii` 権限を持つ場合にのみ含まれます。権限がない場合、そのフィールドは (マスクされた値も含めて) 完全に省略されます。`ip_country` は常に返されます。

```json
{
  "data": [
    {
      "id": "evt_01j9xk3m7q8r2s4t6v8w0y2z4a",
      "occurred_at": "2026-10-01T08:15:42.120Z",
      "type": "authentication.password.failed",
      "outcome": "failure",
      "reason_code": "invalid_credentials",
      "user_id": "usr_0a1b2c3d4e5f6g7h8j9k0m1n2p",
      "org_id": null,
      "application_id": "app_01j9xk3m7q8r2s4t6v8w0y2z4b",
      "connection_id": "conn_01j9xk3m7q8r2s4t6v8w0y2z4c",
      "directory_id": null,
      "session_id": null,
      "identifier_hint": "a***@e***.com",
      "ip": "203.0.113.7",
      "ip_country": "DE",
      "ip_asn": 64500,
      "user_agent": "Mozilla/5.0 (X11; Linux x86_64)",
      "user_agent_family": "Firefox",
      "risk": null,
      "auth_context": null,
      "act_chain": null,
      "details": {"attempt": 3},
      "request_id": "0192a6c1-7d3e-7a10-9b2c-3d4e5f607182",
      "correlation_id": null,
      "trace_id": "4bf92f3577b34da6a3ce929d0e0e4736"
    }
  ],
  "list_metadata": {
    "before": null,
    "after": "<opaque cursor>"
  }
}
```

## エラー

すべてのエラーは、安定した `code` を含む `application/problem+json` ボディで返されます。

| HTTP | `code` | 発生条件 |
|---|---|---|
| 400 | `invalid_cursor` | カーソルの形式が不正か、このリクエスト用に発行されたものではありません。 |
| 400 | `invalid_filter` | ログサービスがフィルターまたはカーソルを拒否しました。 |
| 400 | `range_outside_retention` | `from` がプランの保持期間より前の時刻です。 |
| 422 | `validation_failed` | クエリパラメーターが不正です(`limit` が範囲外、タイムスタンプが不正、`to` が `from` より後でない、`type` の値が 20 個を超える、ID または IP の形式が不正、パラメーターの重複)。 |
| 401 | `unauthenticated` | API キーが存在しない、無効、または取り消されています。 |
| 403 | `insufficient_permissions` | キーに `logs:read` 権限がないか、`audit-events:read_ip` 権限なしで `ip` を、`users:read_pii` 権限なしで `q` を使用しています(`required_permissions` にリクエストに必要な権限が一覧表示されます)。 |
| 429 | `rate_limited` | レート制限を超えました。`Retry-After` に従ってください。 |
| 503 | `service_unavailable` | 依存先が一時的に利用できません。後で再試行してください。 |

## 例

```bash
curl "https://api.eu.keenauth.com/v1/logs?type=authentication.&outcome=failure&from=2026-10-01T00:00:00Z" \
  -H "Authorization: Bearer $KEENAUTH_SECRET_KEY"
```

## 個人データ

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