# Sign-in history and timelines

Use `GET /v1/connections/{conn}/sessions` with an environment secret key to inspect the connection's recorded non-test sign-ins. Results are newest first, with cursor pagination and optional `status` (`succeeded` or `failed`) and email filters. The connection and sign-in must belong to the authenticated environment.

A history entry contains its ID, creation time, outcome and optional error code. Successful entries can expose an email joined from the saved profile; failed entries have no email or profile. Treat that email as personal data and avoid logging complete history responses. Test sign-ins are excluded: inspect the [connection test result](/hosted-portal/connection-doctor/) instead.

## Read a timeline

Use `GET /v1/sign_ins/{sign_in}/timeline` for the recorded steps of an entry. Each step contains its name, time and status, with optional error code and invariant. Follow the [error catalogue](/errors/) for code-specific messages.

An optional `duration_ms` measures that step's own elapsed work. A recorded zero is a real measurement; an absent value means unknown. It is not calculated from the gap between neighboring timestamps. Historical records and outage-buffered steps can omit durations.

Custom-attribute warning steps contain only the attribute key and a finite warning reason, never its source or mapped value. A timeline can also include `doctor` guidance derived from the recorded failure. See [connection health and Doctor](/reference/connection-health/) for the distinction between diagnosis and informational health.

Timelines never contain raw assertions, access tokens or email addresses. They describe the checks actually recorded; they do not guarantee every schema-defined step appears in every flow.

## Delayed and missing records

Profiles are materialized by the event worker. The worker retains the newest profile when an older buffered sign-in arrives, so a history email is a joined profile value rather than a preserved historical email snapshot.

During a [database outage](/trust/database-outages/), successful sign-ins can be buffered and become visible after the worker flushes them. Refused consumed flows are recorded off the request path with a bounded writer. If that writer fails, the refusal record can be dropped after logging; absence from history does not prove an attempt never happened. Invalid or replayed state is not a promise of a new history entry.

History is subject to retention. Keep your own application audit records when your requirements extend beyond the service's stored history.

For a scoped diagnostic copy of an attempt, see [debug bundles](/reference/debug-bundles/). Optional retained SAML diagnostics are separate from the ordinary timeline.
