Timeline

The Timeline is a CQRS read model that provides a chronological projection of all events occurring within a tenant. Events are indexed by family and type, enabling filtered views of entity lifecycle changes, user actions, and system events.

The Timeline is a read-side projection built by background workers (projector:run). There may be a short delay between when an action occurs and when it appears in the timeline.

The timeline entry model

Every timeline entry represents a single domain event that occurred within the tenant.

Properties

Name
id
Type
string
Description
Unique identifier for the timeline entry (UUID).
Name
event_id
Type
string
Description
The ID of the source domain event that produced this entry.
Name
event_type
Type
string
Description
The type of event, such as entity.created, entity.updated, entity.deleted, relation.created, or note.added.
Name
family_code
Type
string
Description
The entity family this event belongs to, such as contact, company, deal, or task.
Name
entity_id
Type
string
Description
The UUID of the entity that was affected by the event.
Name
actor_id
Type
string
Description
The UUID of the user who performed the action. May be null for system-generated events.
Name
summary
Type
string
Description
A human-readable summary of the event, such as "Contact 'John Doe' was created".
Name
occurred_at
Type
string
Description
ISO 8601 timestamp of when the event originally occurred.
Name
metadata
Type
object
Description
Additional context about the event. Contents vary by event type and may include field changes, old/new values, or related entity references.

GET/core/api/v1/timeline

List timeline entries

Retrieve a paginated list of timeline entries for the current tenant. Results are returned in reverse chronological order by default. Supports cursor-based pagination and filtering by family, event type, and date range.

Query parameters

Name
cursor
Type
string
Description
Cursor for pagination. Pass the next_cursor value from a previous response to fetch the next page.
Name
limit
Type
integer
Description
Maximum number of entries to return per page. Defaults to 50, maximum 100.
Name
family
Type
string
Description
Filter entries by entity family code, such as contact, company, deal, or task.
Name
event_type
Type
string
Description
Filter entries by event type, such as entity.created, entity.updated, or entity.deleted.
Name
from_date
Type
string
Description
Filter entries occurring on or after this date. ISO 8601 format (YYYY-MM-DD).
Name
to_date
Type
string
Description
Filter entries occurring on or before this date. ISO 8601 format (YYYY-MM-DD).

Request

GET

/core/api/v1/timeline

curl -G https://your-sphere.example.com/core/api/v1/timeline \
  -H "Authorization: Bearer eyJhbGciOiJSUzI1NiIs..." \
  -d family=contact \
  -d event_type=entity.created \
  -d from_date=2025-01-01 \
  -d to_date=2025-12-31 \
  -d limit=50

Response

{
  "data": [
    {
      "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "event_id": "evt_9f8e7d6c-5b4a-3210-fedc-ba0987654321",
      "event_type": "entity.created",
      "family_code": "contact",
      "entity_id": "c4d5e6f7-a8b9-0123-cdef-456789abcdef",
      "actor_id": "u1a2b3c4-d5e6-f7a8-b9c0-d1e2f3a4b5c6",
      "summary": "Contact 'John Doe' was created",
      "occurred_at": "2025-06-15T14:32:00Z",
      "metadata": {
        "entity_label": "John Doe",
        "family_label": "Contact"
      }
    },
    {
      "id": "b2c3d4e5-f6a7-8901-bcde-f12345678901",
      "event_id": "evt_8e7d6c5b-4a32-10fe-dcba-098765432100",
      "event_type": "entity.created",
      "family_code": "contact",
      "entity_id": "d5e6f7a8-b9c0-1234-defa-56789abcdef0",
      "actor_id": "u1a2b3c4-d5e6-f7a8-b9c0-d1e2f3a4b5c6",
      "summary": "Contact 'Jane Smith' was created",
      "occurred_at": "2025-06-14T09:18:00Z",
      "metadata": {
        "entity_label": "Jane Smith",
        "family_label": "Contact"
      }
    }
  ],
  "meta": {
    "next_cursor": "eyJpZCI6ImIyYzNkNGU1LWY2YTctODkwMS...",
    "has_more": true
  }
}

GET/core/api/v1/timeline/{id}

Get timeline entry

Retrieve a single timeline entry by its ID. Returns the full entry including all metadata fields.

Path parameters

Name
id
Type
string
Description
The UUID of the timeline entry to retrieve.

Request

GET

/core/api/v1/timeline/{id}

curl https://your-sphere.example.com/core/api/v1/timeline/a1b2c3d4-e5f6-7890-abcd-ef1234567890 \
  -H "Authorization: Bearer eyJhbGciOiJSUzI1NiIs..."

Response

{
  "data": {
    "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "event_id": "evt_9f8e7d6c-5b4a-3210-fedc-ba0987654321",
    "event_type": "entity.created",
    "family_code": "contact",
    "entity_id": "c4d5e6f7-a8b9-0123-cdef-456789abcdef",
    "actor_id": "u1a2b3c4-d5e6-f7a8-b9c0-d1e2f3a4b5c6",
    "summary": "Contact 'John Doe' was created",
    "occurred_at": "2025-06-15T14:32:00Z",
    "metadata": {
      "entity_label": "John Doe",
      "family_label": "Contact",
      "initial_fields": {
        "email": "john.doe@acme.com",
        "phone": "+33612345678"
      }
    }
  }
}

GET/core/api/v1/timeline/stats

Get timeline statistics

Retrieve aggregated statistics about the timeline for the current tenant. Returns the total number of events and breakdowns by family and event type. Useful for building dashboard widgets and activity summaries.

Request

GET

/core/api/v1/timeline/stats

curl https://your-sphere.example.com/core/api/v1/timeline/stats \
  -H "Authorization: Bearer eyJhbGciOiJSUzI1NiIs..."

Response

{
  "data": {
    "total_events": 1247,
    "by_family": {
      "contact": 523,
      "company": 198,
      "deal": 312,
      "task": 214
    },
    "by_type": {
      "entity.created": 480,
      "entity.updated": 612,
      "entity.deleted": 45,
      "relation.created": 78,
      "note.added": 32
    }
  }
}