SaaS User Activity Tracking

A project management tool like Asana or Linear needs a complete record of who did what and when. Immutable lets you track every action — from creating projects to completing tasks — with full actor context, session continuity, and multi-resource targeting. Your customers can even view their own activity feed via an embeddable viewer.

Setting Up the Client

JavaScript
Python
Laravel

import { ImmutableClient } from "getimmutable";

const client = new ImmutableClient({
  apiKey: "imk_sk_a1b2c3d4e5f6g7h8i9j0",
  baseUrl: "https://getimmutable.dev",
});

from getimmutable import ImmutableClient

client = ImmutableClient(
    api_key="imk_sk_a1b2c3d4e5f6g7h8i9j0",
    base_url="https://getimmutable.dev"
)

// config is loaded from .env automatically
// GETIMMUTABLE_API_KEY=imk_sk_a1b2c3d4e5f6g7h8i9j0
// GETIMMUTABLE_BASE_URL=https://getimmutable.dev

use GetImmutable\Laravel\Facades\AuditLog;

Tracking the Full Project Lifecycle

User Creates a Project

JavaScript
Python
cURL

await client
  .actor("user_8f3k2", { name: "Sarah Chen", type: "user" })
  .session("sess_29dk3f8a")
  .track("project.created", "project", {
    project_id: "proj_4a9f2c",
    project_name: "Q3 Marketing Campaign",
    visibility: "team",
    template: "marketing-launch",
  });

client.actor("user_8f3k2", name="Sarah Chen", type="user") \
    .session("sess_29dk3f8a") \
    .track("project.created", "project", {
        "project_id": "proj_4a9f2c",
        "project_name": "Q3 Marketing Campaign",
        "visibility": "team",
        "template": "marketing-launch",
    })

curl -X POST https://getimmutable.dev/api/v1/events \
  -H "Authorization: Bearer imk_sk_a1b2c3d4e5f6g7h8i9j0" \
  -H "Content-Type: application/json" \
  -d '{
    "actor_id": "user_8f3k2",
    "actor_name": "Sarah Chen",
    "actor_type": "user",
    "session_id": "sess_29dk3f8a",
    "action": "project.created",
    "resource": "project",
    "resource_id": "proj_4a9f2c",
    "resource_name": "Q3 Marketing Campaign",
    "metadata": {
      "visibility": "team",
      "template": "marketing-launch"
    }
  }'

User Adds a Task with Targets

When a task is created inside a project, use targets to link the event to both the project and the task:

JavaScript
Python
cURL

await client
  .actor("user_8f3k2", { name: "Sarah Chen", type: "user" })
  .session("sess_29dk3f8a")
  .track("task.created", "task", {
    task_id: "task_7b2e9d",
    task_title: "Design landing page mockup",
    priority: "high",
    due_date: "2026-04-15",
    targets: [
      { type: "project", id: "proj_4a9f2c", name: "Q3 Marketing Campaign" },
      { type: "task", id: "task_7b2e9d", name: "Design landing page mockup" },
    ],
  });

client.actor("user_8f3k2", name="Sarah Chen", type="user") \
    .session("sess_29dk3f8a") \
    .track("task.created", "task", {
        "task_id": "task_7b2e9d",
        "task_title": "Design landing page mockup",
        "priority": "high",
        "due_date": "2026-04-15",
        "targets": [
            {"type": "project", "id": "proj_4a9f2c", "name": "Q3 Marketing Campaign"},
            {"type": "task", "id": "task_7b2e9d", "name": "Design landing page mockup"},
        ],
    })

curl -X POST https://getimmutable.dev/api/v1/events \
  -H "Authorization: Bearer imk_sk_a1b2c3d4e5f6g7h8i9j0" \
  -H "Content-Type: application/json" \
  -d '{
    "actor_id": "user_8f3k2",
    "actor_name": "Sarah Chen",
    "actor_type": "user",
    "session_id": "sess_29dk3f8a",
    "action": "task.created",
    "resource": "task",
    "resource_id": "task_7b2e9d",
    "resource_name": "Design landing page mockup",
    "metadata": {
      "priority": "high",
      "due_date": "2026-04-15"
    },
    "targets": [
      {"type": "project", "id": "proj_4a9f2c", "name": "Q3 Marketing Campaign"},
      {"type": "task", "id": "task_7b2e9d", "name": "Design landing page mockup"}
    ]
  }'

User Assigns a Team Member

JavaScript
Python
cURL

await client
  .actor("user_8f3k2", { name: "Sarah Chen", type: "user" })
  .session("sess_29dk3f8a")
  .track("task.member_assigned", "task", {
    task_id: "task_7b2e9d",
    assignee_id: "user_3m7p1q",
    assignee_name: "Marcus Rivera",
    targets: [
      { type: "project", id: "proj_4a9f2c", name: "Q3 Marketing Campaign" },
      { type: "task", id: "task_7b2e9d", name: "Design landing page mockup" },
      { type: "user", id: "user_3m7p1q", name: "Marcus Rivera" },
    ],
  });

client.actor("user_8f3k2", name="Sarah Chen", type="user") \
    .session("sess_29dk3f8a") \
    .track("task.member_assigned", "task", {
        "task_id": "task_7b2e9d",
        "assignee_id": "user_3m7p1q",
        "assignee_name": "Marcus Rivera",
        "targets": [
            {"type": "project", "id": "proj_4a9f2c", "name": "Q3 Marketing Campaign"},
            {"type": "task", "id": "task_7b2e9d", "name": "Design landing page mockup"},
            {"type": "user", "id": "user_3m7p1q", "name": "Marcus Rivera"},
        ],
    })

curl -X POST https://getimmutable.dev/api/v1/events \
  -H "Authorization: Bearer imk_sk_a1b2c3d4e5f6g7h8i9j0" \
  -H "Content-Type: application/json" \
  -d '{
    "actor_id": "user_8f3k2",
    "actor_name": "Sarah Chen",
    "actor_type": "user",
    "session_id": "sess_29dk3f8a",
    "action": "task.member_assigned",
    "resource": "task",
    "resource_id": "task_7b2e9d",
    "resource_name": "Design landing page mockup",
    "metadata": {
      "assignee_id": "user_3m7p1q",
      "assignee_name": "Marcus Rivera"
    },
    "targets": [
      {"type": "project", "id": "proj_4a9f2c", "name": "Q3 Marketing Campaign"},
      {"type": "task", "id": "task_7b2e9d", "name": "Design landing page mockup"},
      {"type": "user", "id": "user_3m7p1q", "name": "Marcus Rivera"}
    ]
  }'

Task Completed and Project Archived

JavaScript
Python
cURL

// Task completed by the assignee
await client
  .actor("user_3m7p1q", { name: "Marcus Rivera", type: "user" })
  .session("sess_44bf9c2e")
  .track("task.completed", "task", {
    task_id: "task_7b2e9d",
    time_spent_hours: 12.5,
    targets: [
      { type: "project", id: "proj_4a9f2c", name: "Q3 Marketing Campaign" },
      { type: "task", id: "task_7b2e9d", name: "Design landing page mockup" },
    ],
  });

// Project archived by the manager
await client
  .actor("user_8f3k2", { name: "Sarah Chen", type: "user" })
  .session("sess_29dk3f8a")
  .track("project.archived", "project", {
    project_id: "proj_4a9f2c",
    total_tasks: 24,
    completed_tasks: 24,
  });

# Task completed by the assignee
client.actor("user_3m7p1q", name="Marcus Rivera", type="user") \
    .session("sess_44bf9c2e") \
    .track("task.completed", "task", {
        "task_id": "task_7b2e9d",
        "time_spent_hours": 12.5,
        "targets": [
            {"type": "project", "id": "proj_4a9f2c", "name": "Q3 Marketing Campaign"},
            {"type": "task", "id": "task_7b2e9d", "name": "Design landing page mockup"},
        ],
    })

# Project archived by the manager
client.actor("user_8f3k2", name="Sarah Chen", type="user") \
    .session("sess_29dk3f8a") \
    .track("project.archived", "project", {
        "project_id": "proj_4a9f2c",
        "total_tasks": 24,
        "completed_tasks": 24,
    })

# Task completed
curl -X POST https://getimmutable.dev/api/v1/events \
  -H "Authorization: Bearer imk_sk_a1b2c3d4e5f6g7h8i9j0" \
  -H "Content-Type: application/json" \
  -d '{
    "actor_id": "user_3m7p1q",
    "actor_name": "Marcus Rivera",
    "actor_type": "user",
    "session_id": "sess_44bf9c2e",
    "action": "task.completed",
    "resource": "task",
    "resource_id": "task_7b2e9d",
    "resource_name": "Design landing page mockup",
    "metadata": {"time_spent_hours": 12.5},
    "targets": [
      {"type": "project", "id": "proj_4a9f2c", "name": "Q3 Marketing Campaign"},
      {"type": "task", "id": "task_7b2e9d", "name": "Design landing page mockup"}
    ]
  }'

# Project archived
curl -X POST https://getimmutable.dev/api/v1/events \
  -H "Authorization: Bearer imk_sk_a1b2c3d4e5f6g7h8i9j0" \
  -H "Content-Type: application/json" \
  -d '{
    "actor_id": "user_8f3k2",
    "actor_name": "Sarah Chen",
    "actor_type": "user",
    "session_id": "sess_29dk3f8a",
    "action": "project.archived",
    "resource": "project",
    "resource_id": "proj_4a9f2c",
    "resource_name": "Q3 Marketing Campaign",
    "metadata": {"total_tasks": 24, "completed_tasks": 24}
  }'

Querying Activity by Actor

Retrieve all actions performed by a specific user:

JavaScript
Python
cURL

const events = await client.getEvents({
  actor_id: "user_8f3k2",
  limit: 50,
});

events.data.forEach((event) => {
  console.log(`${event.occurred_at} — ${event.action} on ${event.resource_name}`);
});

events = client.get_events(actor_id="user_8f3k2", limit=50)

for event in events["data"]:
    print(f"{event['occurred_at']} — {event['action']} on {event['resource_name']}")

curl "https://getimmutable.dev/api/v1/events?actor_id=user_8f3k2&limit=50" \
  -H "Authorization: Bearer imk_sk_a1b2c3d4e5f6g7h8i9j0"

Building a Customer-Facing Activity Feed

Create a viewer token scoped to a tenant so customers can see their own team’s activity:

JavaScript
Python
cURL

const token = await client.createViewerToken({
  tenantId: "org_acme_corp",
  ttl: 3600,
});

// Pass token.viewer_token to your frontend
// Embed the viewer iframe or query the public events endpoint
console.log(token.viewer_token);

token = client.create_viewer_token(tenant_id="org_acme_corp", ttl=3600)

# Pass token["viewer_token"] to your frontend
print(token["viewer_token"])

curl -X POST https://getimmutable.dev/api/v1/viewer-tokens \
  -H "Authorization: Bearer imk_sk_a1b2c3d4e5f6g7h8i9j0" \
  -H "Content-Type: application/json" \
  -d '{"tenant_id": "org_acme_corp", "ttl": 3600}'

Viewer tokens are scoped by tenant_id, so each customer organization only sees their own events. Set a TTL that matches your frontend session length.

What’s Next

Targets

Learn how targets link events to multiple resources.

Session Tracking

Group events into user sessions for richer context.

Embeddable Viewer

Build a customer-facing activity feed with viewer tokens.

Customer-Facing Activity Feed

Full guide to multi-tenant activity feeds.

Industry

Patterns

SaaS User Activity Tracking

Setting Up the Client

Tracking the Full Project Lifecycle

User Creates a Project

User Adds a Task with Targets

User Assigns a Team Member

Task Completed and Project Archived

Querying Activity by Actor

Building a Customer-Facing Activity Feed

What’s Next

Targets

Session Tracking

Embeddable Viewer

Customer-Facing Activity Feed

​Setting Up the Client

​Tracking the Full Project Lifecycle

​User Creates a Project

​User Adds a Task with Targets

​User Assigns a Team Member

​Task Completed and Project Archived

​Querying Activity by Actor

​Building a Customer-Facing Activity Feed

​What’s Next

Targets

Session Tracking

Embeddable Viewer

Customer-Facing Activity Feed

Setting Up the Client

Tracking the Full Project Lifecycle

User Creates a Project

User Adds a Task with Targets

User Assigns a Team Member

Task Completed and Project Archived

Querying Activity by Actor

Building a Customer-Facing Activity Feed

What’s Next