How to capture Python event?

Sending custom events

You can send custom events using the capture method in Leanbase.

Python

# Events captured without context or an explicit distinct_id are marked as personless
# and automatically assigned a generated distinct_id
leanbase.capture('some-anon-event')

from leanbase import identify_context, new_context

# Use contexts to manage user identification across multiple capture calls
with new_context():
identify_context('distinct_id_of_the_user')
leanbase.capture('user_signed_up')
leanbase.capture('user_logged_in')

# You can also capture events with a specific distinct_id
leanbase.capture('some-custom-action', distinct_id='distinct_id_of_the_user')

💡 Tip: We recommend using a [object] [verb] format for event names — where [object] represents the entity and [verb] represents the action.
Examples: project created, user signed up, invite sent.

Setting event properties

You can include additional information with your event by passing a properties object:

leanbase.capture(
"user_signed_up",
distinct_id="distinct_id_of_the_user",
properties={
"login_type": "email",
"is_free_trial": True
}
)

Sending page views

If you're implementing Leanbase in a backend-only environment and not tracking from your frontend, you can still record $pageview events directly:

leanbase.capture(
'$pageview',
distinct_id="distinct_id_of_the_user",
properties={
'$current_url': 'https://example.com'
}
)

Event ingestion

Leanbase prioritizes fast and reliable event processing.
Most events become available for querying and analysis within just a few minutes.

Anonymous vs. Identified events

Leanbase supports two types of events: anonymous and identified.

Identified events

These are linked to specific users and allow you to attach person properties.
They’re ideal for tracking authenticated user activity.

Use cases include:

• Tracking logged-in users in B2B or B2C SaaS products

• Performing user-segmented analytics

• Understanding full customer conversion journeys

Anonymous events

Anonymous events don’t include personally identifiable data and are great for tracking user behavior before login.

Use cases include:

• Marketing or landing page tracking

• Content and engagement analytics

• B2C apps where users don’t sign up or log in

Technical difference:
Identified events create a person profile for the user, while anonymous events do not.

⚡ Note: Anonymous events are up to 4× cheaper to process.
Capture identified events only when user-level tracking is necessary.

Capturing anonymous events

Leanbase’s JavaScript SDK captures anonymous events by default.
This behavior depends on your person_profiles configuration when initializing Leanbase:

leanbase.init('lbp_your_api_key_here', {
api_host: 'https://us.i.leanbase.com',
defaults: '2025-05-24',
person_profiles: 'identified_only' // default, recommended
});

Options:

• person_profiles: 'identified_only' – Captures anonymous events by default. Leanbase only records identified events for users who already have a person profile.

• person_profiles: 'always' – Captures all events as identified.

Capturing identified events

If your person_profiles setting is 'identified_only' (default), anonymous events are captured automatically.
To capture identified events, call one of the following methods:

leanbase.identify('user_123')
leanbase.alias('user_123', 'temp_id')
leanbase.group('team', 'team_456')
leanbase.set_person_properties({ "plan": "Pro" })
leanbase.set_person_properties_for_flags({ "region": "US" })
leanbase.set_group_properties_for_flags({ "industry": "Fintech" })

When you call any of these functions, Leanbase creates a person profile for the user.
All subsequent events from that user will then be captured as identified events.

Alternatively, you can configure Leanbase to always capture identified events by setting:

person_profiles: 'always