---
title: Activity Timeline
slug: activity-timeline
kind: pattern
summary: A record's history as an ordered list of events — who did what, when — so "how did this get like this" is answerable without asking anyone.
problem: >-
  A record shows its current state and nothing about how it got there. When
  something is wrong, the only way to reconstruct the history is to ask
  colleagues what they remember, and the answer arrives hours later and partly
  wrong.
family: [scan, inspect, coordinate]
data_shape: [record, collection]
principles: [orientation, progressive-disclosure]
interaction: [scanning, disclosure]
density: medium
complexity: medium
status: stable
visibility: public
use_when:
  - Several people touch the same record over time.
  - Disputes, audits or support questions turn on what happened and when.
  - The record has a lifecycle, so transitions are meaningful events.
avoid_when:
  - The record is written once and never changes.
  - Nobody would ever ask how it got to its current state.
  - The events would be almost entirely machine noise, drowning the human ones.
alternatives:
  - slug: version-history
    when: People need to see and restore previous CONTENT, not a log of actions.
  - slug: lifecycle-status
    when: Only the current state matters, and the path to it does not.
ask_leo: |
  Add an activity timeline to this record.

  - Record an event for every meaningful change: state transitions, field edits
    that matter, comments, assignments, and anything sent to a customer.
  - Each event shows who, what and when, in that order of prominence. Use a
    relative time with the exact timestamp available on hover or alongside.
  - Order newest first if people mostly check "what just happened", oldest first
    if they mostly reconstruct a story. Pick one and keep it consistent.
  - Write events as plain sentences in the past tense, naming the actual change:
    "Dana changed the amount from $8,400 to $8,900", not "Record updated".
  - Distinguish human actions from automated ones visually, and let the
    automated ones be filtered out. System noise is what kills timelines.
  - Group runs of similar events by the same person within a few minutes into
    one collapsible entry, so a bulk edit is one line rather than forty.
  - Never delete or rewrite an event. A timeline that can be edited is not a
    record of anything.
related:
  - title: Lifecycle Status
    url: /patterns/lifecycle-status
    summary: The state transitions that produce the most useful timeline events.
---

## Anatomy

```
  ● Dana Whitfield · 2 hours ago
    Changed amount from $8,400 to $8,900
    "Client added the second riser." 

  ○ System · 2 hours ago
    Recalculated tax                        ← automated, quieter, filterable

  ● Priya Nandi · yesterday
    Moved from In review to Approved

  ⌄ Dana Whitfield · 3 days ago
    Edited 12 line items                    ← 12 events collapsed into one
```

- **Who, what, when** — in that order, because "who" is the question people ask
  first when something is wrong.
- **Human events louder than machine events**, and machine events filterable.
- **Runs collapsed.** A bulk edit is one line with a count, not forty lines that
  bury everything else.
- **Append-only.** An editable history is not a history.

## Why it works

It answers the question that current state cannot: **how did this get like
this**. That question drives a surprising share of internal support work, and
without a timeline the answer lives in people's memories, which are slow to
query and unreliable.

It also changes behaviour. When actions are attributed and visible, people are
more careful and more willing to fix things, because the fix is attributable too.
That is worth more than the audit trail itself in most teams.

## The signal-to-noise problem

Timelines fail almost entirely one way: **automated events drown human ones.**
A system that logs every recalculation, every webhook, every cache refresh
produces a timeline where the one line that matters — a person changed a price —
is on page four.

Two mechanisms fix it, and you need both:

1. **A visual distinction** so the eye skips machine events without reading.
2. **A filter** that removes them entirely, remembered per user.

If the noise is bad enough that the default view is useless, the honest fix is to
stop recording events that no human will ever want, rather than to filter harder.

## Getting it wrong

- **"Record updated."** An event with no content. If you cannot say what
  changed, the event is not worth storing.
- **No attribution**, so the timeline answers when but not who — usually half
  the question.
- **Absolute timestamps only.** "2026-08-14 09:12:44" is precise and requires
  arithmetic; "3 weeks ago" is what people actually think in. Show both.
- **Uncollapsed bulk runs**, which push everything meaningful off the screen.
- **Editable or deletable events**, which makes the whole thing untrustworthy —
  and it only takes one person knowing it is editable.

## Exemplars

**Stripe's payment timeline** leads its detail view with the sequence of events,
because for a payment the history *is* the record. It also shows the value of
naming events precisely: "Payment failed — insufficient funds" answers the
support question on its own.

**GitHub's issue timeline** interleaves human comments with state changes and
references, and gets the collapsing right — long runs of automated activity fold
away without disappearing.

**Intercom's conversation view** demonstrates the human-versus-machine
distinction handled visually, so a person scanning for what a colleague said is
never reading bot events.

The extractable rule: **a timeline is only as useful as its worst event
description.** One "Record updated" teaches people the log is not worth reading,
and they stop.