Skip to content

Get activity feed for a process

Retrieving process activity feed via API

The activity feed API provides a comprehensive audit trail of all actions taken on a process, including task completions, comments, status changes, assignments, and system events. This endpoint is essential for compliance, auditing, and building custom activity dashboards.

Endpoint

GET /organizations/{org}/activity-feeds

Request

Headers

  • Authorization: Bearer {your_access_token} - Required
  • Accept: application/json
  • X-Tallyfy-Client: APIClient

Query Parameters

ParameterTypeRequiredDescriptionExample
entity_typestringYes*Type of entity to filterrun for processes
entity_idstringYes*ID of the specific processabc123
typestringNoFilter by activity typeTask, Comment, Process
verbstringNoFilter by action performedcompleted, commented, updated
actor_typestringNoFilter by who performed actionuser, guest
actor_idintegerNoID of specific user/guest12345
sourcestringNoSource of activityMember, Guest, Webhook
pageintegerNoPage number for paginationDefault: 1
per_pageintegerNoItems per page (max 100)Default: 20
sortstringNoSort order-created_at (newest first)

*Required when fetching activities for a specific process

Common Verb Values

  • created - Entity was created
  • updated - Entity was modified
  • completed - Task or step was completed
  • commented - Comment was added
  • assigned - Task was assigned
  • unassigned - Assignment was removed
  • archived - Entity was archived
  • activated - Entity was activated
  • deleted - Entity was deleted
  • reopened - Task was reopened
  • started - Process or task was started

Code Samples

// Get all activities for a specific process
const organizationId = 'your_org_id';
const processId = 'your_process_id';
const accessToken = 'your_access_token';
async function getProcessActivityFeed() {
const params = new URLSearchParams({
entity_type: 'run',
entity_id: processId,
per_page: '50',
sort: '-created_at'
});
const response = await fetch(
`https://api.tallyfy.com/organizations/${organizationId}/activity-feeds?${params}`,
{
method: 'GET',
headers: {
'Authorization': `Bearer ${accessToken}`,
'Accept': 'application/json',
'X-Tallyfy-Client': 'APIClient'
}
}
);
if (!response.ok) {
throw new Error(`HTTP error! status: ${response.status}`);
}
const data = await response.json();
return data;
}
// Filter for specific activity types
async function getTaskCompletions(processId) {
const params = new URLSearchParams({
entity_type: 'run',
entity_id: processId,
type: 'Task',
verb: 'completed',
per_page: '100'
});
const response = await fetch(
`https://api.tallyfy.com/organizations/${organizationId}/activity-feeds?${params}`,
{
method: 'GET',
headers: {
'Authorization': `Bearer ${accessToken}`,
'Accept': 'application/json'
}
}
);
return response.json();
}

Response

Success Response (200 OK)

{
"data": [
{
"id": "feed_abc123",
"organization_id": "org_xyz",
"verb": "completed",
"source": "Member",
"actor": {
"id": 12345,
"name": "John Smith",
"email": "john@example.com",
"type": "user"
},
"auditable_type": "task",
"auditable_id": "task_456",
"parentable_type": "run",
"parentable_id": "run_789",
"type": "Task",
"description": "Completed task: Review document",
"field": null,
"old_value": null,
"created_at": "2024-01-18T10:30:00Z",
"text": null,
"references": [],
"audit": {
"id": "task_456",
"name": "Review document",
"status": "completed",
"completed_at": "2024-01-18T10:30:00Z",
"completed_by": 12345
},
"parent": {
"id": "run_789",
"name": "Employee Onboarding - Jane Doe",
"status": "active"
}
},
{
"id": "feed_def456",
"organization_id": "org_xyz",
"verb": "commented",
"source": "Guest",
"actor": {
"id": 67890,
"name": "External Reviewer",
"email": "reviewer@external.com",
"type": "guest"
},
"auditable_type": "task",
"auditable_id": "task_456",
"parentable_type": "run",
"parentable_id": "run_789",
"type": "Comment",
"description": "Added comment on task",
"field": null,
"old_value": null,
"created_at": "2024-01-18T09:15:00Z",
"text": "Document looks good, approved for next step",
"references": [],
"audit": null,
"parent": {
"id": "run_789",
"name": "Employee Onboarding - Jane Doe",
"status": "active"
}
},
{
"id": "feed_ghi789",
"organization_id": "org_xyz",
"verb": "updated",
"source": "Member",
"actor": {
"id": 12345,
"name": "John Smith",
"email": "john@example.com",
"type": "user"
},
"auditable_type": "task",
"auditable_id": "task_123",
"parentable_type": "run",
"parentable_id": "run_789",
"type": "Task",
"description": "Updated deadline",
"field": "deadline",
"old_value": "2024-01-20T00:00:00Z",
"created_at": "2024-01-18T08:00:00Z",
"text": null,
"references": [],
"audit": {
"id": "task_123",
"name": "Prepare workspace",
"deadline": "2024-01-25T00:00:00Z"
},
"parent": {
"id": "run_789",
"name": "Employee Onboarding - Jane Doe",
"status": "active"
}
}
],
"total": 145,
"per_page": 20,
"current_page": 1,
"last_page": 8,
"from": 1,
"to": 20
}

Response Fields

  • data: Array of activity objects
  • total: Total number of activities matching the filters
  • per_page: Number of items per page
  • current_page: Current page number
  • last_page: Total number of pages
  • from: Starting item number
  • to: Ending item number

Activity Object Fields

  • id: Unique activity feed ID
  • organization_id: Organization ID
  • verb: Action performed (completed, updated, commented, etc.)
  • source: Who triggered the activity (Member, Guest, Webhook, System)
  • actor: Object containing details about who performed the action
  • auditable_type: Type of entity that was acted upon (task, step, run, etc.)
  • auditable_id: ID of the entity that was acted upon
  • parentable_type: Type of parent entity
  • parentable_id: ID of parent entity
  • type: Category of activity (Task, Comment, Process, etc.)
  • description: Human-readable description of the activity
  • field: For updates, which field was changed
  • old_value: For updates, the previous value
  • created_at: Timestamp when the activity occurred
  • text: Additional text/content (e.g., comment text)
  • references: Array of related references
  • audit: Current state of the audited object
  • parent: Information about the parent object

Common Use Cases

1. Export Complete Audit Log

Fetch all activities for a process and export to your preferred format:

// Fetch all pages of activities
async function exportAuditLog(processId) {
let allActivities = [];
let page = 1;
let hasMore = true;
while (hasMore) {
const params = new URLSearchParams({
entity_type: 'run',
entity_id: processId,
page: page.toString(),
per_page: '100',
sort: '-created_at'
});
const response = await fetch(
`https://api.tallyfy.com/organizations/${orgId}/activity-feeds?${params}`,
{ headers: { 'Authorization': `Bearer ${token}` } }
);
const data = await response.json();
allActivities = allActivities.concat(data.data);
hasMore = data.current_page < data.last_page;
page++;
}
return allActivities;
}

2. Monitor Real-Time Process Changes

Poll for new activities since last check:

let lastCheckTime = new Date().toISOString();
async function getRecentActivities(processId) {
const params = new URLSearchParams({
entity_type: 'run',
entity_id: processId,
per_page: '20',
sort: '-created_at'
});
const response = await fetch(
`https://api.tallyfy.com/organizations/${orgId}/activity-feeds?${params}`,
{ headers: { 'Authorization': `Bearer ${token}` } }
);
const data = await response.json();
// Filter activities newer than last check
const newActivities = data.data.filter(
activity => new Date(activity.created_at) > new Date(lastCheckTime)
);
if (newActivities.length > 0) {
lastCheckTime = newActivities[0].created_at;
}
return newActivities;
}

3. Track User Productivity

Get all activities by a specific user:

async function getUserActivities(userId, startDate, endDate) {
const params = new URLSearchParams({
actor_type: 'user',
actor_id: userId.toString(),
per_page: '100',
sort: '-created_at'
});
const response = await fetch(
`https://api.tallyfy.com/organizations/${orgId}/activity-feeds?${params}`,
{ headers: { 'Authorization': `Bearer ${token}` } }
);
return response.json();
}

4. Compliance Reporting

Generate compliance reports showing all changes to sensitive processes:

async function getComplianceData(processId) {
// Get all updates and completions
const params = new URLSearchParams({
entity_type: 'run',
entity_id: processId,
per_page: '100'
});
const response = await fetch(
`https://api.tallyfy.com/organizations/${orgId}/activity-feeds?${params}`,
{ headers: { 'Authorization': `Bearer ${token}` } }
);
const data = await response.json();
// Filter for compliance-relevant activities
return data.data.filter(activity =>
['completed', 'updated', 'assigned', 'unassigned'].includes(activity.verb) ||
activity.type === 'Comment'
);
}

Error Responses

401 Unauthorized

{
"error": "Unauthorized",
"message": "Invalid or expired access token"
}

403 Forbidden

{
"error": "Forbidden",
"message": "You don't have permission to view this process's activities"
}

404 Not Found

{
"error": "Not Found",
"message": "Process not found or has been deleted"
}

429 Rate Limited

{
"error": "Too Many Requests",
"message": "Rate limit exceeded. Please wait before making more requests"
}

Permissions

To access activity feeds, the authenticated user must have one of the following:

  • Be an administrator in the organization
  • Have PROCESS_READ permission for the specific process
  • Be the creator of the process
  • Be assigned to at least one task in the process
  • Be a support user with appropriate access

Rate Limits

  • Default rate limit: 1000 requests per hour per organization
  • Burst limit: 100 requests per minute
  • Use pagination and caching to minimize API calls

Processes > List processes

The GET endpoint retrieves process instances within organizations supporting extensive filtering options through query parameters and providing paginated results with detailed run information.

Tasks > List process tasks

The GET endpoint allows retrieval of task lists associated with a specific process run through authorization headers and optional query parameters for filtering sorting and pagination functionality.

Processes > Get process

A GET endpoint retrieves detailed information about a specific process run using organization and run IDs with optional parameters to include related data such as checklists tasks tags and form field values.

Tracker View > Check process activity

Tallyfy processes maintain detailed activity logs that record all actions including task completions deadline changes comments and archiving which can be viewed by administrators and authorized members through the Settings panel’s Activity tab.