# ユーザーのログを一覧表示

`GET /v1/users/{user_id}/logs` · 権限 `logs:read`

1 人のユーザーのログレコードを、カーソルページネーションで新しい順に一覧表示します。これはダッシュボードのユーザーアクティビティビューに表示されるデータです。[ログを一覧表示](/docs/api/management/logs/list) と同じルールに従いますが、受け付けるフィルターは `from`、`to`、`type`、`org_id` のみです。それ以外のフィルターは無視されます。

## 組織の範囲

組織管理者向けにメンバーの診断ビューを作成するには、`org_id` を渡します。この場合、キーには `organizations:read` 権限も必要です。ユーザーがその組織のメンバーでない場合（`invited`、`active`、`suspended` のメンバーシップがない場合）、リクエストは `404 not_found` で失敗します。これは存在しないユーザーの場合と同じレスポンスです。ユーザーがメンバーである場合、返されるのはその組織の文脈で発生したレコード、つまり `org_id` がその組織のレコードのみです。組織外、または別の組織の文脈で行われたユーザーのサインインは、返されることはありません。`org_id` を指定しない場合、ビューには環境内のユーザーのすべてのレコードが含まれます。

## リクエスト

| パラメーター | 位置 | 必須 | 説明 |
|---|---|---|---|
| `user_id` | path | はい | `usr_` で始まるユーザー ID です。 |
| `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 個の値までパラメーターを繰り返し指定できます。いずれかに一致するレコードが返されます。 |
| `org_id` | query | いいえ | `org_` で始まる組織 ID です。ビューをその組織のレコードに限定します。詳しくは [組織の範囲](#組織の範囲) を参照してください。`organizations:read` が必要です。 |

レコードは常に `occurred_at` の新しい順に並びます。`order` パラメーターはありません（`order=desc` は受け付けられ、それ以外の値は `validation_failed` で失敗します）。カーソルは、発行されたときと同じフィルターでのみ有効です。

## レスポンス

`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 個を超える、`org_id` の形式が不正、パラメーターの重複）。 |
| 401 | `unauthenticated` | API キーがない、無効である、または取り消されています。 |
| 403 | `insufficient_permissions` | キーに `logs:read` 権限がないか、`org_id` が設定されているのにキーに `organizations:read` 権限がありません。`required_permissions` にリクエストに必要な権限が一覧で示されます。 |
| 404 | `not_found` | ユーザー ID の形式が不正であるか、`org_id` が設定されていてユーザーがその組織のメンバーではありません。 |
| 429 | `rate_limited` | レート制限を超えました。`Retry-After` に従ってください。 |
| 503 | `service_unavailable` | 依存先のサービスが一時的に利用できません。後で再試行してください。 |

## 例

```bash
curl "https://api.eu.keenauth.com/v1/users/usr_0a1b2c3d4e5f6g7h8j9k0m1n2p/logs?limit=50" \
  -H "Authorization: Bearer $KEENAUTH_SECRET_KEY"
```

1 つの組織のレコードのみを取得する場合:

```bash
keenauth users logs list usr_0a1b2c3d4e5f6g7h8j9k0m1n2p --org-id org_01j9xk3m7q8r2s4t6v8w0y2z4d --type authentication.
```

## 個人データ

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