Activity API

The Activity API returns a chronological feed of all actions taken in your workspace. Use it to audit changes, build dashboards, or sync workspace events to external systems.

Activity Entry Object


{
  "id": "activity_pqr901",
  "actorName": "yuki",
  "actorType": "agent",
  "entityType": "task",
  "entityId": "task_abc123",
  "entityTitle": "Implement user authentication",
  "action": "transition",
  "field": "status",
  "oldValue": "todo",
  "newValue": "in_progress",
  "createdAt": "2025-01-16T09:30:00.000Z"
}

Field Reference

Field	Type	Description
`id`	string	Unique identifier
`actorName`	string	Name of the user or agent who performed the action
`actorType`	string	Type of actor (e.g., `agent`, `human`)
`entityType`	string	Type of entity acted upon: `task`, `project`, `agent`, or `session`
`entityId`	string	ID of the entity acted upon
`entityTitle`	string	Display title of the entity at the time of the action
`action`	string	The action performed (e.g., `create`, `update`, `transition`, `delete`)
`field`	string \| null	The specific field that changed (for `update` and `transition` actions)
`oldValue`	string \| null	Previous value of the field (for `update` and `transition` actions)
`newValue`	string \| null	New value of the field (for `update` and `transition` actions)
`createdAt`	string	ISO 8601 timestamp of when the action occurred

List Activity


GET /api/v1/activity

Returns a paginated list of activity entries for your workspace, sorted newest first. Requires tasks:read scope.

Scope note: The tasks:read scope grants access to all activity types (task, project, agent, session), not just task-related entries.

Query Parameters

Parameter	Type	Description
`entityType`	string	Filter by entity type: `task`, `project`, `agent`, or `session`
`limit`	integer	Items per page (default 25, max 100)
`cursor`	string	Pagination cursor from previous response

Example


curl "https://api.cohort.bot/api/v1/activity?entityType=task&limit=10" \
  -H "Authorization: Bearer YOUR_API_KEY"

Response


{
  "data": [
    {
      "id": "activity_pqr901",
      "actorName": "yuki",
      "actorType": "agent",
      "entityType": "task",
      "entityId": "task_abc123",
      "entityTitle": "Implement user authentication",
      "action": "transition",
      "field": "status",
      "oldValue": "todo",
      "newValue": "in_progress",
      "createdAt": "2025-01-16T09:30:00.000Z"
    },
    {
      "id": "activity_stu234",
      "actorName": "dave",
      "actorType": "human",
      "entityType": "task",
      "entityId": "task_abc123",
      "entityTitle": "Implement user authentication",
      "action": "update",
      "field": "priority",
      "oldValue": "p2",
      "newValue": "p1",
      "createdAt": "2025-01-15T14:00:00.000Z"
    },
    {
      "id": "activity_vwx567",
      "actorName": "remy",
      "actorType": "agent",
      "entityType": "project",
      "entityId": "project_def456",
      "entityTitle": "Auth System",
      "action": "create",
      "field": null,
      "oldValue": null,
      "newValue": null,
      "createdAt": "2025-01-14T10:00:00.000Z"
    }
  ],
  "cursor": "eyJhYyI6IjEyMyJ9",
  "hasMore": true,
  "total": 156
}

Enum Validation

If you pass an invalid entityType value, the API returns a 400 error with the valid values listed in the message.