# Günlükleri listele

`GET /v1/logs` · izin `logs:read`

Ortamın günlük kayıtlarını (oturum açmalar, oturumlar, belirteçler, çok faktörlü kimlik doğrulama, saldırı koruması ve daha fazlası) imleç tabanlı sayfalama ile en yeniden en eskiye doğru listeler. Planınızın saklama süresinden (Free 7, Startup 14, Business 30, Enterprise 90 gün) daha eski kayıtlar hiçbir zaman döndürülmez.

## İstek

| Parametre | Konum | Zorunlu | Açıklama |
|---|---|---|---|
| `limit` | query | hayır | Sayfa boyutu, 1 ile 100 arası. Varsayılan 20. |
| `after` | query | hayır | `list_metadata.after` alanından gelen opak imleç (daha eski kayıtlar). `before` ile birlikte kullanılamaz. |
| `before` | query | hayır | `list_metadata.before` alanından gelen opak imleç (daha yeni kayıtlar). `after` ile birlikte kullanılamaz. |
| `from` | query | hayır | RFC 3339 zamanı; bu zamana eşit veya sonraki kayıtlar. Saklama süresi içinde olmalıdır. |
| `to` | query | hayır | RFC 3339 zamanı; bu zamandan önceki kayıtlar. `from` değerinden sonra olmalıdır. |
| `type` | query | hayır | `authentication.` veya `session.created` gibi günlük türü öneki. Parametreyi en fazla 20 değer için tekrarlayın; bunlardan herhangi biriyle eşleşen kayıt döndürülür. |
| `outcome` | query | hayır | `success`, `failure`, `denied` veya `error`. |
| `user_id`, `org_id`, `application_id`, `connection_id`, `directory_id`, `session_id` | query | hayır | Ön ekli kimlikle tam eşleşme (`usr_`, `org_`, `app_`, `conn_`, `dir_`, `ses_`). |
| `request_id` | query | hayır | Bir isteğin `Idp-Request-Id` değeri (UUID); örneğin barındırılan oturum açma hata sayfasında gösterilen kimlik. |
| `correlation_id` | query | hayır | Bir iş akışının `Idp-Correlation-Id` değeri (UUID). |
| `ip` | query | hayır | IP adresi veya CIDR bloğu (`203.0.113.0/24`). `audit-events:read_ip` izni gerektirir. |
| `ip_country` | query | hayır | IP adresinin ülkesi; büyük harfle ISO 3166-1 alpha-2 (`DE`). |
| `q` | query | hayır | Maskelenmiş tanımlayıcı ipucunun öneki (`j***@`). `users:read_pii` izni gerektirir. |

Kayıtlar her zaman `occurred_at` alanına göre en yeniden en eskiye sıralanır; `order` parametresi yoktur (`order=desc` kabul edilir, başka bir değer `validation_failed` hatasıyla sonuçlanır). İmleç yalnızca üretildiği filtrelerle geçerlidir.

`ip` ve `q` filtreleri yalnızca sonucu daraltsa bile bu izinleri gerektirir: izin olmadan istek, herhangi bir arama yapılmadan `403 insufficient_permissions` hatasıyla başarısız olur. Böylece bir anahtar okumasına izin verilmeyen değerleri yoklayamaz.

## Yanıt

`200 OK` döner. `data` sayfadaki kayıtları içerir; `list_metadata.after` daha eski kayıtlara, `list_metadata.before` ise daha yeni kayıtlara işaret eder (kayıt yoksa `null`). Toplam sayı döndürülmez. Boş alanlar `null` olur.

`ip`, `ip_asn`, `user_agent` ve `user_agent_family` alanları yalnızca anahtarın `audit-events:read_ip` iznine sahip olması durumunda bulunur; `identifier_hint` alanı ise yalnızca `users:read_pii` iznine sahip olması durumunda bulunur. İzin yoksa alan tamamen çıkarılır (maskelenmiş değer döndürülmez). `ip_country` her zaman döndürülür.

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

## Hatalar

Her hata, kararlı bir `code` değeri içeren bir `application/problem+json` gövdesidir.

| HTTP | `code` | Ne zaman |
|---|---|---|
| 400 | `invalid_cursor` | İmleç hatalı biçimde veya bu istek için üretilmemiş. |
| 400 | `invalid_filter` | Günlük hizmeti bir filtreyi veya imleci reddetti. |
| 400 | `range_outside_retention` | `from` değeri, planınızın saklama süresinden daha eski. |
| 422 | `validation_failed` | Bir sorgu parametresi geçersiz (`limit` aralık dışında, hatalı zaman damgası, `to` değeri `from` değerinden sonra değil, 20'den fazla `type` değeri, hatalı kimlik veya IP, tekrarlanan parametre). |
| 401 | `unauthenticated` | API anahtarı eksik, geçersiz veya iptal edilmiş. |
| 403 | `insufficient_permissions` | Anahtarda `logs:read` izni yok ya da `ip` filtresi `audit-events:read_ip` olmadan ya da `q` filtresi `users:read_pii` olmadan kullanılmış (`required_permissions` isteğin gerektirdiklerini listeler). |
| 429 | `rate_limited` | Hız sınırı aşıldı; `Retry-After` değerine uyun. |
| 503 | `service_unavailable` | Bir bağımlılık geçici olarak kullanılamıyor; daha sonra yeniden deneyin. |

## Örnek

```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"
```

## Kişisel veriler

Bu uç nokta kişisel veri içerir: ortam günlükleri. [KeenAuth API'lerinde kişisel veriler](/docs/policies/personal-data) bölümünde neyin saklandığı, ne kadar süre tutulduğu ve nasıl silindiği açıklanmaktadır. Hiçbir alanda özel nitelikli kişisel verileri (sağlık, biyometrik veriler, din, siyasi görüşler, cinsel yönelim) göndermeyin.