Reference - Encord

This topic provides a comprehensive reference of all events tracked in the Label Editor, including when they occur and what properties are captured for each event.

Overview

The Encord Editor tracks user interactions and changes to provide analytics, audit trails, and workflow management capabilities. All events are logged with a consistent base structure and additional properties specific to each action type.

Base Properties

All editor log events include the following base properties:

Property	Type	Description
`dataUnitId`	string	The hash/ID of the data unit being annotated
`workflowStageId`	string	UUID of the workflow stage
`workflowTaskId`	string	UUID of the workflow task (annotation, review task or empty when in view mode)
`branchName`	string	The branch name (useful when using consensus workflow)
`sessionId`	string	Unique session identifier for the editor session
`action`	string	The specific action being logged (see event-specific sections)
`actionCategory`	string	Category of the action: `"object"`, `"classification"`, `"task"`, `"agent"`, or `"editor"`
`timestamp`	string	Timestamp of when the event occurred

Object Actions

Object actions track changes to annotation objects (bounding boxes, polygons, points, etc.).

Common Object Properties

All object actions include these properties:

Property	Type	Description
`objectHash`	string	Unique identifier for the object
`featureId`	string	Feature hash identifying the ontology class/type
`labelName`	string	Display name of the label/ontology class
`labelRanges`	`[number, number][]`	Frame ranges where the object exists (empty array for segmentations)
`objectShape`	string	Shape type: `"bounding_box"`, `"rotatable_bounding_box"`, `"polygon"`, `"polyline"`, `"point"`, `"skeleton"`, `"bitmask"`, `"cuboid"`, `"segmentation"`, `"cuboid_2d"`
`objectId`	number	Numeric ID of the object
`objectCurrentFrame`	number	null	Current frame index (null for segmentations)

CREATE_OBJECT

When: An annotation object is created (drawn) in the editor. Additional Properties:

eventInformation.coordinates (null for audio): Object coordinates (bounding box, polygon points, etc.)

Example:

{
  "action": "create_object",
  "actionCategory": "object",
  "objectHash": "abc123...",
  "featureId": "feature_hash_xyz",
  "labelName": "Person",
  "objectShape": "bounding_box",
  "eventInformation": {
    "coordinates": { "x": 100, "y": 200, "w": 50, "h": 80 }
  }
}

UPDATE_OBJECT

When: An object is modified (frame range, classifications, or feature type changed). Additional Properties:

eventInformation.oldRange (optional): Previous frame ranges [number, number][]
eventInformation.newRange (optional): New frame ranges [number, number][]
eventInformation.oldClassification (optional): Previous classification values
eventInformation.newClassification (optional): New classification values
eventInformation.oldFeatureHash (optional): Previous feature hash
eventInformation.newFeatureHash (optional): New feature hash
eventInformation.lastEditedBy: User hash of who made the edit

Note: Only changed properties are included. If only coordinates change, see UPDATE_OBJECT with EventInformationObjectEditCoordinates.

UPDATE_OBJECT (Coordinate Changes)

When: Only the coordinates/shape of an object are modified (e.g., resizing a bounding box, moving polygon vertices). Additional Properties:

eventInformation.oldCoordinates: Previous coordinate values
eventInformation.newCoordinates: New coordinate values
eventInformation.lastEditedBy: User hash of who made the edit

DELETE_OBJECT

When: An annotation object is deleted. Additional Properties:

eventInformation.classifications (optional): Classification values that were associated with the object
eventInformation.coordinates (optional): Final coordinates of the deleted object

APPROVE_OBJECT

When: An object is approved during review. Additional Properties:

eventInformation.classifications (optional): Classification values associated with the object
eventInformation.isConsensus: Boolean indicating if this is part of a consensus review
eventInformation.previousAction (optional): Previous review action ("APPROVE", "REJECT", or "REOPEN")

REJECT_OBJECT

When: An object is rejected during review. Additional Properties:

eventInformation.classifications (optional): Classification values associated with the object
eventInformation.isConsensus: Boolean indicating if this is part of a consensus review
eventInformation.previousAction (optional): Previous review action

REVERT_TO_PENDING_OBJECT

When: An approved or rejected object is reopened/reverted to pending status. Additional Properties:

eventInformation.classifications (optional): Classification values associated with the object
eventInformation.isConsensus: Boolean indicating if this is part of a consensus review
eventInformation.previousAction (optional): Previous review action (typically "APPROVE")

Classification/Attribute Actions

Classification/attribute actions track changes to frame-level or object-level classifications (attributes).

Common Classification Properties

All classification actions include these properties:

Property	Type	Description
`classificationHash`	string	Unique identifier for the classification
`featureId`	string	Feature hash identifying the classification type
`labelName`	string	Display name of the classification
`labelRanges`	`[number, number][]`	Frame ranges where the classification applies

CREATE_ATTRIBUTE

When: A classification/attribute is created. Additional Properties:

eventInformation.classifications: Object mapping feature hashes to classification results, including:
- featureId: Feature hash
- name: Display name
- value: Selected value
- Nested answers (for nested attributes)

Example:

{
  "action": "create_attribute",
  "actionCategory": "classification",
  "classificationHash": "class_abc123...",
  "featureId": "attr_feature_hash",
  "labelName": "Weather",
  "eventInformation": {
    "classifications": {
      "attr_feature_hash": {
        "featureId": "attr_feature_hash",
        "name": "Weather",
        "value": "Sunny"
      }
    }
  }
}

UPDATE_ATTRIBUTE

When: A classification is modified (frame range or value changed). Additional Properties:

eventInformation.oldRange (optional): Previous frame ranges
eventInformation.newRange (optional): New frame ranges
eventInformation.oldValue (optional): Previous classification values
eventInformation.newValue (optional): New classification values
eventInformation.lastEditedBy: User hash of who made the edit

DELETE_ATTRIBUTE

When: A classification/attribute is deleted. Additional Properties:

eventInformation.classifications: Classification values that were deleted

APPROVE_CLASSIFICATION

When: A classification is approved during review. Additional Properties:

eventInformation.classifications (optional): Classification values
eventInformation.isConsensus: Boolean indicating if this is part of a consensus review
eventInformation.previousAction (optional): Previous review action

REJECT_CLASSIFICATION

When: A classification is rejected during review. Additional Properties:

eventInformation.classifications (optional): Classification values
eventInformation.isConsensus: Boolean indicating if this is part of a consensus review
eventInformation.previousAction (optional): Previous review action

REVERT_TO_PENDING_CLASSIFICATION

When: An approved or rejected classification is reopened/reverted to pending status. Additional Properties:

eventInformation.classifications (optional): Classification values
eventInformation.isConsensus: Boolean indicating if this is part of a consensus review
eventInformation.previousAction (optional): Previous review action

Task Actions

Task actions track workflow-level operations.

SKIP_TASK

When: A task is skipped in the workflow. Additional Properties:

eventInformation.skipReason: String reason provided for skipping the task

Example:

{
  "action": "skip_task",
  "actionCategory": "task",
  "eventInformation": {
    "skipReason": "Poor image quality"
  }
}

SAVE_TASK

When: A task is saved (manually or via autosave). Additional Properties:

eventInformation.saveType: Either "manual" or "autosave"
eventInformation.success: Boolean indicating if the save operation succeeded

SUBMIT_TASK

When: A task is submitted for review or completion. Additional Properties:

eventInformation.labels: Array of label identifiers (object/classification hashes) included in the submission

Example:

{
  "action": "submit_task",
  "actionCategory": "task",
  "eventInformation": {
    "labels": ["obj_hash_1", "obj_hash_2", "class_hash_1"]
  }
}

APPROVE_TASK

When: A task is approved during review. Additional Properties: For non-consensus reviews:

eventInformation.approvedLabelHashes: Array of approved label hashes
eventInformation.isConsensus: false

For consensus reviews (without determining consensus):

eventInformation.approvedLabelHashes: Array of approved label hashes
eventInformation.isConsensus: true
eventInformation.isDetermineConsensus: false
eventInformation.annotatorsWithApprovedLabels: Array of { email: string, hash: string } for annotators whose labels were approved

For consensus reviews (with determining consensus):

eventInformation.approvedLabelHashes: Array of approved label hashes
eventInformation.isConsensus: true
eventInformation.isDetermineConsensus: true
eventInformation.selectedAnnotators: Array of { email: string, hash: string } for selected annotators
eventInformation.winningSetAnnotator: { email: string, hash: string } for the annotator whose labels won

REJECT_TASK

When: A task is rejected during review. Additional Properties: For non-consensus reviews:

eventInformation.rejectedLabelHashes: Array of rejected label hashes
eventInformation.approvedLabelHashes: Array of approved label hashes
eventInformation.isConsensus: false

For consensus reviews:

eventInformation.approvedLabelHashes (optional): Array of approved label hashes
eventInformation.isConsensus: true
eventInformation.isDetermineConsensus: Boolean indicating if consensus determination was involved
eventInformation.annotators: Array of annotator identifiers

Agent Actions

RUN_AGENT

When: An automated agent/ML model is executed. Additional Properties:

eventInformation.objectHashes: Array of object hashes that were created or modified by the agent
eventInformation.agentUuid: UUID of the agent that was run
eventInformation.agentEndpoint: API endpoint used for the agent
eventInformation.agentTitle: Display title of the agent
eventInformation.agentDescription: Description of the agent
eventInformation.success: Boolean indicating if the agent run succeeded

Example:

{
  "action": "run_agent",
  "actionCategory": "agent",
  "eventInformation": {
    "objectHashes": ["obj_1", "obj_2"],
    "agentUuid": "agent-uuid-123",
    "agentEndpoint": "/api/v1/agents/detect",
    "agentTitle": "Object Detection Model",
    "agentDescription": "Detects objects in images",
    "success": true
  }
}

Editor Actions

Editor actions track editor-level state changes and user interactions.

ENTER_EDITOR

When: A user opens/enters the editor. Additional Properties:

None (empty eventInformation: {})

ENTER_EDIT_MODE

When: The editor enters edit mode (e.g., when starting to draw an annotation). Additional Properties:

None (empty eventInformation: {})

EXIT_EDIT_MODE

When: The editor exits edit mode (e.g., after completing an annotation). Additional Properties:

None (empty eventInformation: {})

FORCE_OVERWRITE

When: A user forces an overwrite operation (e.g., overwriting existing labels). Additional Properties:

None (empty eventInformation: {})

Event Flow Examples

Creating an Object

ENTER_EDITOR - User opens editor
ENTER_EDIT_MODE - User selects drawing tool
CREATE_OBJECT - User draws a bounding box
EXIT_EDIT_MODE - User completes the annotation
SAVE_TASK (autosave) - System auto-saves
SUBMIT_TASK - User submits the task

Reviewing Objects

APPROVE_OBJECT - Reviewer approves object 1
REJECT_OBJECT - Reviewer rejects object 2
APPROVE_TASK - Reviewer approves the entire task

Editing an Object

UPDATE_OBJECT (coordinates) - User resizes a bounding box
UPDATE_OBJECT (feature) - User changes the object’s class/type
UPDATE_OBJECT (range) - User extends the object to additional frames

Notes

All timestamps are in UTC ISO 8601 format
Empty UUIDs (EMPTY_UUID) are used when workflow information is not available
Classification values are stored as nested objects for complex attribute structures
Coordinates are stored in shape-specific formats (bounding boxes, polygons, etc.)
Frame ranges use inclusive start and end frames: [startFrame, endFrame]
Segmentations do not have frame ranges (empty array) or current frame (null)

Get Started

General

Index

Ontologies

Projects

Labels

Datasets

DICOM

Active API & SDK

Documentation Index

​Overview

​Base Properties

​Object Actions

​Common Object Properties

​CREATE_OBJECT

​UPDATE_OBJECT

​UPDATE_OBJECT (Coordinate Changes)

​DELETE_OBJECT

​APPROVE_OBJECT

​REJECT_OBJECT

​REVERT_TO_PENDING_OBJECT

​Classification/Attribute Actions

​Common Classification Properties

​CREATE_ATTRIBUTE

​UPDATE_ATTRIBUTE

​DELETE_ATTRIBUTE

​APPROVE_CLASSIFICATION

​REJECT_CLASSIFICATION

​REVERT_TO_PENDING_CLASSIFICATION

​Task Actions

​SKIP_TASK

​SAVE_TASK

​SUBMIT_TASK

​APPROVE_TASK

​REJECT_TASK

​Agent Actions

​RUN_AGENT

​Editor Actions

​ENTER_EDITOR

​ENTER_EDIT_MODE

​EXIT_EDIT_MODE

​FORCE_OVERWRITE

​Event Flow Examples

​Creating an Object

​Reviewing Objects

​Editing an Object

​Notes

Overview

Base Properties

Object Actions

Common Object Properties

CREATE_OBJECT

UPDATE_OBJECT

UPDATE_OBJECT (Coordinate Changes)

DELETE_OBJECT

APPROVE_OBJECT

REJECT_OBJECT

REVERT_TO_PENDING_OBJECT

Classification/Attribute Actions

Common Classification Properties

CREATE_ATTRIBUTE

UPDATE_ATTRIBUTE

DELETE_ATTRIBUTE

APPROVE_CLASSIFICATION

REJECT_CLASSIFICATION

REVERT_TO_PENDING_CLASSIFICATION

Task Actions

SKIP_TASK

SAVE_TASK

SUBMIT_TASK

APPROVE_TASK

REJECT_TASK

Agent Actions

RUN_AGENT

Editor Actions

ENTER_EDITOR

ENTER_EDIT_MODE

EXIT_EDIT_MODE

FORCE_OVERWRITE

Event Flow Examples

Creating an Object

Reviewing Objects

Editing an Object

Notes