Skip to main content

​
Activity Timeline

The Activity Timeline provides a unified view of all communications — emails and meetings — for a specific CRM account or contact. Instead of querying email and calendar systems separately, get a single chronological feed for account review, call prep, or relationship analysis.

​
Usage

POST /api/v1/activity/timeline
{
  "account_id": "001ABC123",
  "days": 90,
  "limit": 50,
  "types": ["email", "meeting"]
}

​
Parameters

ParameterTypeRequiredDescription
account_idstringOne of account_id or contact_idCRM account ID
contact_idstringOne of account_id or contact_idCRM contact ID
daysintegerNoLookback window (1–365, default: 90)
limitintegerNoMax items to return
offsetintegerNoPagination offset
typesarrayNoFilter by type: ["email"], ["meeting"], or both (default)

​
Response

{
  "items": [
    {
      "type": "email",
      "subject": "Re: Q3 Renewal Discussion",
      "snippet": "Thanks for the updated pricing...",
      "timestamp": "2026-01-14T15:30:00Z",
      "recipients": ["[email protected]", "[email protected]"],
      "direction": "outbound"
    },
    {
      "type": "meeting",
      "subject": "Quarterly Business Review",
      "timestamp": "2026-01-10T14:00:00Z",
      "end_time": "2026-01-10T15:00:00Z",
      "attendees": ["[email protected]", "[email protected]"]
    }
  ],
  "total": 23
}
The timeline merges data from connected email and calendar integrations, resolves CRM entity relationships, and sorts everything chronologically.

​
How agents use activity data

Activity timelines are exposed to agents through two paths that serve different purposes:

​
As a tool result (on demand)

When an agent calls get_account_activity_timeline or get_contact_activity_timeline, the result flows through the artifact-backed result cache:
  1. The full timeline payload is stored in the result cache with a TTL
  2. A compact summary (item count, date range, 3-item preview) is returned to the LLM
  3. The agent emits a <account_activity_timeline ref="cr_xxx" /> tag
  4. The UI renders the full timeline as a panel artifact
This means agents can work with 90 days of email and meeting history without consuming the context window — the full data is accessible to the UI while the LLM works from the summary.

​
As background context (automatic)

The crm_context async prompt block automatically includes recent activity signals (last meeting date, last email date, communication frequency) as part of the agent’s background context. This gives agents ambient awareness of relationship health without the user explicitly asking “when did we last talk to Acme?”

​
Artifact-backed result types

The activity timeline artifacts live in artifacts/<type>/ARTIFACT.py. Each file uses @artifact(...) to register the UI type and register_cached_tool(...) to wire the matching tool result to the same summarizer:
ToolArtifact typeDisplay
get_account_activity_timelineaccount_activity_timelinePanel
get_contact_activity_timelinecontact_activity_timelinePanel
These types appear in the artifact catalog alongside draft types like draft_email and display types like records_table.