Event Reference | LaBrowser Docs for Behavioral Studies

Events are saved on the participant's machine first and uploaded automatically in the background. This helps LaBrowser keep data safe even if the connection drops.

Common Fields

Every event includes these base fields regardless of type.

Name	Type	Description
id	string	Unique event identifier
event_type	string	The event type identifier
timestamp_utc	string	ISO 8601 UTC timestamp
session_id	string	UUID of the session
tab_id	string \| null	UUID of the tab, or null for session-level events
page_id	string \| null	UUID of the current page load, or null
url	string \| null	Current page URL, or null
payload	object	Event-specific data (see per-type fields below)

NAVIGATE Navigation

Fired when the browser navigates to a new URL.

Name	Type	Description
trigger	string	What caused the navigation: link_click, address_bar, history_back, history_forward, redirect, new_tab, pushstate, replacestate, popstate
from_url	string \| null	The previous URL before navigation
to_url	string	The destination URL

Example payload

{
  "event_type": "NAVIGATE",
  "timestamp_utc": "2025-01-15T10:30:00.000Z",
  "tab_id": "a1b2c3d4",
  "page_id": "e5f6g7h8",
  "url": "https://www.google.com/search?q=climate+change",
  "payload": {
    "trigger": "address_bar",
    "from_url": "https://www.google.com",
    "to_url": "https://www.google.com/search?q=climate+change"
  }
}

PAGE_LOADED Navigation

Fired when a page finishes loading completely.

Name	Type	Description
url	string	URL of the loaded page
title	string	Document title
hostname	string	Hostname extracted from the URL
load_time_ms	number	Time from navigation start to load complete, in milliseconds
viewport_width	number	Browser viewport width in pixels
viewport_height	number	Browser viewport height in pixels
document_height	number	Total document height in pixels

Example payload

{
  "event_type": "PAGE_LOADED",
  "timestamp_utc": "2025-01-15T10:30:02.340Z",
  "tab_id": "a1b2c3d4",
  "page_id": "e5f6g7h8",
  "url": "https://www.google.com/search?q=climate+change",
  "payload": {
    "url": "https://www.google.com/search?q=climate+change",
    "title": "climate change - Google Search",
    "hostname": "www.google.com",
    "load_time_ms": 2340,
    "viewport_width": 1440,
    "viewport_height": 900,
    "document_height": 4280
  }
}

Tab Events

TAB_OPENED Tabs

Fired when a new tab is created.

Name	Type	Description
opener_tab_id	string \| null	The tab that opened this one, or null if opened via address bar
url	string \| null	Initial URL of the new tab, or null

Example payload

{
  "event_type": "TAB_OPENED",
  "timestamp_utc": "2025-01-15T10:31:15.000Z",
  "tab_id": "f9e8d7c6",
  "page_id": "b5a4c3d2",
  "url": "about:blank",
  "payload": {
    "opener_tab_id": "a1b2c3d4",
    "url": "about:blank"
  }
}

TAB_CLOSED Tabs

Fired when a tab is closed.

Example payload

{
  "event_type": "TAB_CLOSED",
  "timestamp_utc": "2025-01-15T10:45:30.000Z",
  "tab_id": "f9e8d7c6",
  "page_id": "b5a4c3d2",
  "url": "https://en.wikipedia.org/wiki/Climate_change",
  "payload": {}
}

TAB_SWITCHED Tabs

Fired when the participant switches to a different tab.

Name	Type	Description
from_tab_id	string	ID of the previously active tab
to_tab_id	string	ID of the newly active tab

Example payload

{
  "event_type": "TAB_SWITCHED",
  "timestamp_utc": "2025-01-15T10:32:05.000Z",
  "tab_id": "a1b2c3d4",
  "page_id": "e5f6g7h8",
  "url": "https://www.google.com/search?q=climate+change",
  "payload": {
    "from_tab_id": "f9e8d7c6",
    "to_tab_id": "a1b2c3d4"
  }
}

Interaction Events

CLICK Interaction

Fired when the participant clicks on a page element.

Name	Type	Description
x	number	Click X coordinate relative to the viewport
y	number	Click Y coordinate relative to the viewport
element_tag	string	HTML tag name of the clicked element
element_text_snippet	string	Text content snippet from the clicked element
css_selector	string	CSS selector identifying the clicked element
button	string	Mouse button used: left, right, or middle

Example payload

{
  "event_type": "CLICK",
  "timestamp_utc": "2025-01-15T10:30:08.120Z",
  "tab_id": "a1b2c3d4",
  "page_id": "e5f6g7h8",
  "url": "https://www.google.com/search?q=climate+change",
  "payload": {
    "x": 432,
    "y": 287,
    "element_tag": "A",
    "element_text_snippet": "Climate change - Wikipedia",
    "css_selector": "#search .g:nth-child(3) a[href]",
    "button": "left"
  }
}

SCROLL Interaction

Fired periodically as the participant scrolls the page.

Name	Type	Description
scroll_top	number	Vertical scroll position in pixels
viewport_height	number	Current viewport height in pixels
document_height	number	Total document height in pixels

Example payload

{
  "event_type": "SCROLL",
  "timestamp_utc": "2025-01-15T10:30:12.500Z",
  "tab_id": "a1b2c3d4",
  "page_id": "e5f6g7h8",
  "url": "https://www.google.com/search?q=climate+change",
  "payload": {
    "scroll_top": 1240,
    "viewport_height": 900,
    "document_height": 4280
  }
}

INPUT_SUBMIT Interaction

Fired when the participant submits text in a form field.

Name	Type	Description
text	string	The complete text content of the field at submission time
field_role	string	Detected role of the field: search_query, chat_prompt, site_search, generic_input
service	string	Detected service: google, chatgpt, claude, perplexity, amazon, gemini, custom_tool, any
url	string	URL of the page where the input was submitted
selector	string	CSS selector of the input element
submit_method	string	How the input was submitted: enter_key, form_submit, button_click, heuristic, blur
capture_id	string \| null	Client-generated correlation ID for linking later AI responses to this submitted prompt

Example payload

{
  "event_type": "INPUT_SUBMIT",
  "timestamp_utc": "2025-01-15T10:29:58.000Z",
  "tab_id": "a1b2c3d4",
  "page_id": "d4c3b2a1",
  "url": "https://www.google.com",
  "payload": {
    "text": "climate change effects on agriculture",
    "field_role": "search_query",
    "service": "google",
    "url": "https://www.google.com",
    "selector": "textarea[name='q']",
    "submit_method": "enter_key",
    "capture_id": "cap_01JQ4FW5E0J8S2Y7TK3J5W9Q3V"
  }
}

INPUT_SUBMIT captures the complete text content of the field at submission time, not individual keystrokes. For search queries and chat prompts, this gives you exactly what the participant sent.

AI Events

AI_RESPONSE AI

Fired when an AI assistant response is detected on the page.

Name	Type	Description
service	string	The AI service that generated the response (e.g. chatgpt, gemini, claude)
response_text	string	The text content of the AI response
response_selector	string	CSS selector used to locate the response element
capture_method	string	How the response was captured
url	string	URL of the page where the response appeared
prompt_capture_id	string \| null	Client-generated prompt correlation ID carried from the originating INPUT_SUBMIT when available
prompt_event_id	string \| null	ID of the INPUT_SUBMIT event that triggered this response, or null
char_count	number	Character count of the response
truncated	boolean	Whether the response was truncated due to length limits

Example payload

{
  "event_type": "AI_RESPONSE",
  "timestamp_utc": "2025-01-15T10:35:22.000Z",
  "tab_id": "f9e8d7c6",
  "page_id": "h8g7f6e5",
  "url": "https://chat.openai.com/c/abc123",
  "payload": {
    "service": "chatgpt",
    "response_text": "Climate change affects agriculture through several key mechanisms: 1) Rising temperatures alter growing seasons...",
    "response_selector": "div.message.assistant",
    "capture_method": "mutation_silence",
    "url": "https://chat.openai.com/c/abc123",
    "prompt_capture_id": "cap_01JQ4FW5E0J8S2Y7TK3J5W9Q3V",
    "prompt_event_id": "evt_a1b2c3",
    "char_count": 1847,
    "truncated": false
  }
}

AI_RESPONSE keeps both the raw client-side prompt correlation ID and the resolved event ID when available. Parsers prefer the resolved event ID, then fall back to the client ID, then finally to time-window matching for older data.

Task Events

TASK_START Task

Fired when the participant begins a study task.

Name	Type	Description
task_id	string	Identifier of the task being started

Example payload

{
  "event_type": "TASK_START",
  "timestamp_utc": "2025-01-15T10:28:00.000Z",
  "tab_id": "a1b2c3d4",
  "page_id": "d4c3b2a1",
  "url": "https://www.google.com",
  "payload": {
    "task_id": "task_1"
  }
}

TASK_END Task

Fired when the participant completes or ends a study task.

Name	Type	Description
task_id	string	Identifier of the task that ended

Example payload

{
  "event_type": "TASK_END",
  "timestamp_utc": "2025-01-15T10:48:00.000Z",
  "tab_id": "a1b2c3d4",
  "page_id": "k2j1i0h9",
  "url": "https://en.wikipedia.org/wiki/Effects_of_climate_change_on_agriculture",
  "payload": {
    "task_id": "task_1"
  }
}

Session Events

SESSION_TIME_WARNING Session

Fired when the session approaches its time limit.

Name	Type	Description
elapsed_seconds	number	Seconds elapsed since session start
max_seconds	number	Maximum session duration in seconds
threshold	string	The warning threshold reached (e.g. 75%, 90%)

Example payload

{
  "event_type": "SESSION_TIME_WARNING",
  "timestamp_utc": "2025-01-15T11:13:00.000Z",
  "tab_id": "a1b2c3d4",
  "page_id": "m4n3o2p1",
  "url": "https://scholar.google.com",
  "payload": {
    "elapsed_seconds": 2700,
    "max_seconds": 3600,
    "threshold": "75%"
  }
}

SESSION_TIME_EXPIRED Session

Fired when the session time limit is reached.

Name	Type	Description
elapsed_seconds	number	Seconds elapsed since session start
max_seconds	number	Maximum session duration in seconds

Example payload

{
  "event_type": "SESSION_TIME_EXPIRED",
  "timestamp_utc": "2025-01-15T11:28:00.000Z",
  "tab_id": "a1b2c3d4",
  "page_id": "q5r4s3t2",
  "url": "https://scholar.google.com/scholar?q=climate+agriculture",
  "payload": {
    "elapsed_seconds": 3600,
    "max_seconds": 3600
  }
}

Policy Events

NAVIGATION_BLOCKED Policy

Fired when a navigation attempt is blocked by the study's domain policy.

Name	Type	Description
attempted_url	string	The URL the participant tried to visit
reason	string	Why the navigation was blocked (e.g. domain_not_allowed)

Example payload

{
  "event_type": "NAVIGATION_BLOCKED",
  "timestamp_utc": "2025-01-15T10:40:15.000Z",
  "tab_id": "a1b2c3d4",
  "page_id": "e5f6g7h8",
  "url": "https://www.google.com/search?q=climate+change",
  "payload": {
    "attempted_url": "https://www.facebook.com",
    "reason": "domain_not_allowed"
  }
}

Artifact Events

SCREENSHOT Artifact

Fired when a screenshot of the current page is captured.

Name	Type	Description
trigger	string	What triggered the screenshot (e.g. navigate, scroll, timer)
artifact_id	string	ID of the stored artifact
tab_id	string	ID of the tab that was screenshotted
byte_count	number	Size of the screenshot in bytes
width	number	Screenshot width in pixels
height	number	Screenshot height in pixels
jpeg_quality	number	JPEG quality setting (0-100)
url	string \| null	URL of the page when the screenshot was taken, or null

Example payload

{
  "event_type": "SCREENSHOT",
  "timestamp_utc": "2025-01-15T10:30:03.000Z",
  "tab_id": "a1b2c3d4",
  "page_id": "e5f6g7h8",
  "url": "https://www.google.com/search?q=climate+change",
  "payload": {
    "trigger": "navigate",
    "artifact_id": "art_x1y2z3",
    "tab_id": "a1b2c3d4",
    "byte_count": 184320,
    "width": 1440,
    "height": 900,
    "jpeg_quality": 80,
    "url": "https://www.google.com/search?q=climate+change"
  }
}

DOM_SNAPSHOT Artifact

Fired when a snapshot of the page DOM is captured.

Name	Type	Description
trigger	string	What triggered the snapshot
artifact_id	string	ID of the stored artifact
tab_id	string	ID of the tab that was snapshotted
byte_count	number	Compressed size of the snapshot in bytes
raw_byte_count	number	Uncompressed size of the DOM snapshot in bytes
compressed	boolean	Whether the snapshot data is gzip-compressed
url	string \| null	URL of the page when the snapshot was taken, or null

Example payload

{
  "event_type": "DOM_SNAPSHOT",
  "timestamp_utc": "2025-01-15T10:30:03.500Z",
  "tab_id": "a1b2c3d4",
  "page_id": "e5f6g7h8",
  "url": "https://www.google.com/search?q=climate+change",
  "payload": {
    "trigger": "navigate",
    "artifact_id": "art_d4e5f6",
    "tab_id": "a1b2c3d4",
    "byte_count": 48000,
    "raw_byte_count": 256000,
    "compressed": true,
    "url": "https://www.google.com/search?q=climate+change"
  }
}

Augmentation Events

SITE_AUGMENTATION_AUDIT Augmentation

Fired by site augmentation for each action outcome on a matching page: applied, skipped, failed, or cleaned up.

Name	Type	Description
plugin_id	string	ID of the site plugin that owns this action
plugin_name	string	Human-readable name of the site plugin
action_id	string	ID of the action within the plugin
action	string	Action kind: hide or remove
reason	string	Operator-supplied reason for the change, copied from the action config
status	string	Outcome: applied, skipped, failed, or cleaned_up
page_url	string	URL of the page where the action ran
matched_selector	string	CSS selector the action evaluated
matched_count	number	Number of elements the selector matched
applied_count	number	Number of elements actually hidden or removed
limit	number	Effective match/mutation limit that applied to this run
element_fingerprints	object[]	Lightweight fingerprints of affected elements: { tag, id, class_name, text_preview } (up to 20)
error	string \| null	Reason code or error message when status is skipped or failed; null otherwise (e.g. url_not_matched, no_matches, matched_count_exceeds_limit, selector_too_broad)

Example payload

{
  "event_type": "SITE_AUGMENTATION_AUDIT",
  "timestamp_utc": "2025-01-15T10:30:04.000Z",
  "tab_id": "a1b2c3d4",
  "page_id": "e5f6g7h8",
  "url": "https://shop.example/product/123",
  "payload": {
    "plugin_id": "recommendation-shelf-suppression",
    "plugin_name": "Recommendation shelf suppression",
    "action_id": "hide-recommendation-shelf",
    "action": "hide",
    "reason": "condition_hide_recommendation_shelf",
    "status": "applied",
    "page_url": "https://shop.example/product/123",
    "matched_selector": "section[data-testid='recommendations']",
    "matched_count": 1,
    "applied_count": 1,
    "limit": 2,
    "element_fingerprints": [
      {
        "tag": "section",
        "id": "",
        "class_name": "recommendations",
        "text_preview": "You might also like"
      }
    ],
    "error": null
  }
}

Augmentation only emits these events when an action's audit field is enabled (the default). They are the evidence trail of what changed on a participant's page. See Site Augmentation for the full feature reference.

Other Events

DOWNLOAD Other

Fired when a file download completes (or is cancelled/interrupted).

Name	Type	Description
url	string	URL the file was downloaded from
filename	string	Name of the downloaded file
mime_type	string	MIME type of the file
file_size	integer	Number of bytes received
state	string	Download outcome: completed, cancelled, or interrupted

Example payload

{
  "event_type": "DOWNLOAD",
  "timestamp_utc": "2025-01-15T10:42:10.000Z",
  "tab_id": "a1b2c3d4",
  "page_id": "e5f6g7h8",
  "url": "https://example.com/report.pdf",
  "payload": {
    "url": "https://example.com/report.pdf",
    "filename": "report.pdf",
    "mime_type": "application/pdf",
    "file_size": 245760,
    "state": "completed"
  }
}

CLIENT_LOG Other

Fired for client-side diagnostic log entries (errors, warnings, crash recovery).

Name	Type	Description
level	string	Log level: error, warn, or info
source	string	Component that generated the log entry
message	string	Human-readable log message
stack	string \| null	Stack trace, if available

Example payload

{
  "event_type": "CLIENT_LOG",
  "timestamp_utc": "2025-01-15T10:30:00.500Z",
  "tab_id": null,
  "page_id": null,
  "url": null,
  "payload": {
    "level": "error",
    "source": "uncaughtException",
    "message": "Cannot read properties of null",
    "stack": "TypeError: Cannot read properties of null\n    at EventCapture.handleClick"
  }
}

Common Fields

Navigation Events

Tab Events

Interaction Events

AI Events

Task Events

Session Events

Policy Events

Artifact Events

Augmentation Events

Other Events