Skip to main content

​
Overview

While every event has a primary resource (resource.type, resource.id, resource.name), many actions involve multiple resources. The targets field lets you attach additional resources to an event for cross-resource tracking.

​
Target Structure

Each target object has the following fields:
​
type
string
required
The type of resource. Example: folder, team, permission.
​
id
string
The resource identifier. Example: folder_3mK9pLq.
​
name
string
Human-readable name. Example: Engineering Team.
​
metadata
object
Optional metadata specific to this target.

​
Example

A user shares a document with a team and moves it to a folder: 
{
  "actor_id": "user_2hG9kLm",
  "actor_name": "Sarah Chen",
  "action": "document.shared",
  "resource_id": "doc_8nXpQr3",
  "resource_name": "Q4 Financial Report",
  "resource": "document",
  "targets": [
    { "type": "folder", "id": "folder_3mK9pLq", "name": "Shared Reports" },
    { "type": "team", "id": "team_5bR7cNx", "name": "Engineering" }
  ]
}

​
Filtering by Target

Query events by target using the target_type and target_id query parameters: 
curl "https://getimmutable.dev/api/v1/events?target_type=folder&target_id=folder_3mK9pLq" \
  -H "Authorization: Bearer imk_your_api_key_here"
This returns all events where the specified target appears in the targets array, regardless of the primary resource.

​
Use Cases

ScenarioPrimary ResourceTargets
File moved to folderFileSource folder, destination folder
User added to teamUserTeam, role
Permission grantedPermissionUser, resource
Invoice payment appliedInvoicePayment method, subscription
Merge request approvedMerge requestRepository, reviewer
Bulk action on recordsBatch operationIndividual records affected

​
SDK Usage

import { ImmutableClient, PendingEvent } from "@getimmutable/sdk";

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

// Single target
const event = new PendingEvent(client, { id: "user_2hG9kLm", name: "Sarah Chen", type: "user" });
await event
  .target("folder", "folder_3mK9pLq", "Shared Reports")
  .target("team", "team_5bR7cNx", "Engineering")
  .track("document.shared", "document");

// Multiple targets at once
await new PendingEvent(client, { id: "user_2hG9kLm" })
  .targets([
    { type: "folder", id: "folder_3mK9pLq", name: "Shared Reports" },
    { type: "team", id: "team_5bR7cNx", name: "Engineering" },
  ])
  .track("document.shared", "document");

​
Hash Chain

Targets are included in the hash chain computation. They are sorted by type then id before hashing to ensure deterministic results regardless of the order you provide them.