Join us now
← Back to API Reference overview

Events

Endpoints for managing events in Linkbreakers. These endpoints allow you to collect data and list events.

Shortcut: ⌘K

#The Event object

Records each scan or workflow action Linkbreakers processes, stitching together visitor, device, link, and routing details so analytics and automations stay in sync.

action

string (enum)

The type of event action

Allowed values
ACTION_UNSPECIFIED

Action not specified

ACTION_SCAN

First-time scan or click

ACTION_RESCAN

Replay of the same device on the same link

createdAt

string (date-time)

Timestamp when the event object was created

destination

string

Final resolved destination after workflow evaluation

destinationAction

string (enum)

Event action types for workflow steps

Allowed values
EVENT_ACTION_UNSPECIFIED

Event action not specified

EVENT_ACTION_CLIENT_REDIRECT

Redirect visitors to a destination URL

EVENT_ACTION_QRCODE_SCAN

Entry step triggered when the QR code is scanned.

EVENT_ACTION_PASSWORD_VERIFY

Require visitors to enter a password before proceeding

EVENT_ACTION_FORM_SUBMIT

Present a data collection form to visitors

EVENT_ACTION_CONTACT_CARD

Generate a vCard (VCF) response with contact information

EVENT_ACTION_MULTI_LINK

Present a multi-link page with multiple buttons for different destinations

EVENT_ACTION_SCAN_RESCAN_CONDITION

Route visitors based on whether it's a first scan or rescan

EVENT_ACTION_COUNTRY_CONDITION

Route visitors based on their country location

EVENT_ACTION_DAY_OF_WEEK_CONDITION

Route visitors based on day of week

EVENT_ACTION_TIME_OF_DAY_CONDITION

Route visitors based on time of day

EVENT_ACTION_DAY_OF_MONTH_CONDITION

Route visitors based on day of month

EVENT_ACTION_SPECIFIC_DATE_CONDITION

Route visitors based on specific calendar dates

device

object

Tracks the fingerprint of a visitor's hardware/software so Linkbreakers can de-duplicate scans, enrich analytics, and power security heuristics.

deviceId

string

Device fingerprint associated with the event (UUID)

entrypoint

string

Entrypoint URL that received the request (short link)

httpMethod

string (enum)

The HTTP method used when the event was generated

Allowed values
HTTP_METHOD_UNSPECIFIED

HTTP method not specified

HTTP_METHOD_GET
HTTP_METHOD_POST
HTTP_METHOD_PUT
HTTP_METHOD_DELETE
HTTP_METHOD_PATCH
HTTP_METHOD_OPTIONS
HTTP_METHOD_HEAD

id

string

Unique identifier for the event object (UUID)

leadScore

object

Stores the AI-generated assessment Linkbreakers produces for a visitor's engagement with a link, including reasoning signals and user feedback to continuously refine scoring.

leadScoreId

string

Lead score entry computed for this visitor-link pair (UUID)

link

object

Core resource that ties a shortlink or QR entrypoint to its workflow, destination, and analytics metadata, letting Linkbreakers serve dynamic experiences while tracking scans for a workspace.

linkId

string

Identifier of the link producing the event (UUID)

scannedAt

string (date-time)

When the QR code or link was accessed

traces

array<object>

Workflow step traces for engagement tracking (included only on demand)

triggeredBy

string (enum)

The actor that triggered the event

Allowed values
TRIGGERED_BY_UNSPECIFIED

Trigger source not specified

TRIGGERED_BY_VISITOR

Visitor initiated the scan (as opposed to system-generated)

updatedAt

string (date-time)

Timestamp when the event object was last updated (e.g. when lead score computed)

visitor

object

Captures the cross-link profile Linkbreakers builds for someone who scans or clicks, combining reserved identity fields, attributed devices, events, and custom traits gathered from forms.

visitorId

string

Visitor profile associated with the event (UUID)

workspace

object

Serves as the tenant boundary in Linkbreakers, grouping links, members, settings, billing state, and analytics under a single organization's environment.

workspaceId

string

Identifier of the owning workspace (UUID)

GET/v1/eventsRequires auth

#List events

Retrieves the workspace's event timeline, returning paginated JSON by default or CSV payloads for reporting exports. For workspaces on the free plan, events older than 2 months are restricted and will not be included in the results.

#Parameters

query parameters

linkId

stringquery

Filter events to a specific link (optional, UUID) Optional

startDate

string (date-time)query

Inclusive start timestamp for the query window (workspace timezone aware). Note: For free plan workspaces, this will be automatically adjusted to not go back more than 2 months.

endDate

string (date-time)query

Inclusive end timestamp for the query window

responseFormat

stringquery

Desired response format (defaults to RESPONSE_FORMAT_JSON; use RESPONSE_FORMAT_CSV for exports)

Allowed values
RESPONSE_FORMAT_UNSPECIFIED

Response format not specified

RESPONSE_FORMAT_JSON

Response format JSON

RESPONSE_FORMAT_CSV

Response format CSV

pageSize

integer (int32)query

Maximum number of events to return (default: 100, max: 1000) Maximum number of events to return (default: 100, max: 1000)

pageToken

stringquery

Cursor token to retrieve the next page of results Cursor token to retrieve the next page of results

include

array<string>query

Optional list of relationships to include: visitor, device, link, workspace, leadScore Optional list of relationships to include: visitor, device, link, workspace, leadScore

#Response

200

Everything worked as expected.

csv

object

ListEventsCsvResponse streams the export payload when ResponseFormat is set to RESPONSE_FORMAT_CSV.

json

object

ListEventsJsonResponse returns paginated event objects suitable for dashboards.

#Error response

400-599

All endpoints may return an unexpected error payload when a request cannot be processed.

error

objectRequired

Wrapped error response.

GET/v1/events/{eventId}/tracesRequires auth

#List event traces

Retrieves all workflow step traces for an event, ordered by completion time. Useful for analyzing user engagement and workflow progression.

#Parameters

path parameters

eventId

stringRequiredpath

Event ID to get traces for (UUID)

#Response

200

Everything worked as expected.

traces

array<object>

List of event traces ordered by completed_at

#Error response

400-599

All endpoints may return an unexpected error payload when a request cannot be processed.

error

objectRequired

Wrapped error response.

POST/v1/events/{eventId}/tracesRequires auth

#Create event trace

Records a workflow step completion (form submission, page view, etc.) for engagement tracking and scoring.

#Parameters

path parameters

eventId

stringRequiredpath

Event ID to attach this trace to (UUID)

#Request body

stepAction

string

Workflow step action

stepData

object

EventTraceData captures the payload for a completed workflow step.

stepKind

string

Workflow step kind: ENTRY, EXIT, INTERACTION, CONDITION

#Response

200

Everything worked as expected.

trace

object

Records workflow step completion for engagement tracking, capturing form submissions, page views, and user interactions to measure engagement quality.

#Error response

400-599

All endpoints may return an unexpected error payload when a request cannot be processed.

error

objectRequired

Wrapped error response.