Reference

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.

This page describes the events in the Editor Logs. To fetch them with the SDK, see View Editor Logs. To read them in your code, see Read Events with the SDK.

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

---

Read Events with the SDK

The property names on this page are the field names the API uses. get_editor_logs() converts them to snake_case Python attributes, so dataUnitId becomes log.data_unit_id. To get the original names back, use log.to_dict(). The action value is a lowercase string, for example "create_object" for CREATE_OBJECT.

Python SDK Example

The following script prints the events from the last day for a Project. It reads the properties all events share, then checks the event’s class to read the properties only object or classification events have.

Read editor log events

    import datetime

    from encord import EncordUserClient
    from encord.orm.editor_log import EditorLogClassification, EditorLogObject

    # User input
    SSH_PATH = "/Users/chris-encord/ssh-private-key.txt"  # Replace with file path to your SSH private key
    PROJECT_ID = "00000000-0000-0000-0000-000000000000"  # Replace with the unique Project ID

    # Create user client using access key
    user_client: EncordUserClient = EncordUserClient.create_with_ssh_private_key(
        ssh_private_key_path=SSH_PATH,
        # For US platform users use "https://api.us.encord.com"
        domain="https://api.encord.com",
    )

    project = user_client.get_project(PROJECT_ID)

    # start_time and end_time are required. The maximum range is 30 days.
    end_time = datetime.datetime.now()
    start_time = end_time - datetime.timedelta(days=1)

    for log in project.get_editor_logs(start_time=start_time, end_time=end_time):
        # Properties on every event
        print(f"{log.timestamp} | {log.action} ({log.action_category})")
        print(f"  User: {log.actor_user_email} ({log.project_user_role})")
        print(f"  Data unit: {log.data_unit_title} | Stage: {log.workflow_stage_title} | Branch: {log.branch_name}")

        # Properties on object events only
        if isinstance(log, EditorLogObject):
            print(f"  Object: {log.label_name} ({log.object_shape}) | Hash: {log.object_hash} | Frames: {log.label_ranges}")

        # Properties on classification events only
        elif isinstance(log, EditorLogClassification):
            print(f"  Classification: {log.label_name} | Hash: {log.classification_hash} | Frames: {log.label_ranges}")

The SDK returns a different class for each action category:

Action category	SDK class
object	EditorLogObject
classification	EditorLogClassification
task, agent, editor	EditorLogGeneralAction

Properties on this page and their SDK names

Property on this page	SDK attribute	Available on
dataUnitId	data_unit_id	All events
workflowStageId	workflow_stage_id	All events
workflowTaskId	workflow_task_id	All events
branchName	branch_name	All events
sessionId	session_id	All events
action	action	All events
actionCategory	action_category	All events
timestamp	timestamp	All events
objectHash	object_hash	Object events
featureId	feature_id	Object and classification events
labelName	label_name	Object and classification events
labelRanges	label_ranges	Object and classification events
objectShape	object_shape	Object events
objectId	object_id	Object events
objectCurrentFrame	object_current_frame	Object events
classificationHash	classification_hash	Classification events

Additional properties returned by the SDK

Every log returned by the SDK also includes:

SDK attribute	Description
id	The log entry’s unique ID
actor_user_email	Email of the user who performed the action
actor_user_id	ID of the user who performed the action
actor_organisation_id	ID of the user’s Organization
project_user_role	The user’s role in the Project
project_organisation_user_role	The user’s role in the Organization
project_id	The Project’s ID
project_organisation_id	ID of the Organization that owns the Project
workflow_stage_title	Name of the Workflow stage
workflow_stage_type	Type of the Workflow stage: ANNOTATION, REVIEW, CONSENSUS_ANNOTATION, CONSENSUS_REVIEW, or DONE
data_unit_title	Name of the data unit
data_unit_data_type	Data type of the data unit
data_unit_dataset_id	ID of the Dataset the data unit belongs to
data_unit_dataset_title	Name of the Dataset the data unit belongs to
ontology_id	ID of the Project’s Ontology

eventInformation is not available through the SDK. The SDK log classes don’t define it, and the SDK ignores any field it doesn’t define, so details such as old and new coordinates, lastEditedBy, and winningSetAnnotator can’t currently be read with get_editor_logs().

---

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

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

Reviewing Objects

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

Editing an Object

1. UPDATE_OBJECT (coordinates) - User resizes a bounding box
2. UPDATE_OBJECT (feature) - User changes the object’s class/type
3. 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)