M24 · Audience Builder

Audiences

Not a frozen cohort: a member list you actively sync and push to destinations. Hourly sync, CSV export, quota included.

Workflow

Cohort → audience flow

Define a cohort first, then promote it to an audience. source_cohort_id keeps the link; hourly tick kicks in.

1. Create a cohort

Under /app/cohorts define a cohort with event + property conditions. A cohort is a static count; the audience is the live, synced version.

/app/cohorts

2. Promote to audience

On /app/audiences pick 'New audience' → choose source cohort. source_cohort_id is linked, hourly refresh turns on automatically.

/app/audiences

# 1. Önce bir cohort oluştur
gurulu cohort create high-intent \
  --rule 'event:add_to_cart in last 7d' \
  --rule 'event:checkout_started in last 7d'

# 2. Cohort → audience promote
gurulu audience create \
  --name "Yüksek niyetli ziyaretçiler" \
  --source-cohort high-intent \
  --sync hourly

# 3. Aktif audience oluşur — destination'lara bağlanmaya hazır
gurulu audience list --status active

Active sync

Hourly refresh — triggered every hour

Worker tick + Redis pub/sub + delta diff + daily snapshot — audience members stay live.

How it works

Worker fires hourly, the audience definition is re-evaluated in CH, joined/left deltas are computed, and the audience_changes_daily snapshot is recorded.

Worker hourly tick → publish on Redis channel per audience
Diff against previous member list → joined + left split out
audience_changes_daily — daily member count + net change

// Worker hourly tick — Redis pub/sub trigger
PUBLISH gurulu:audience:refresh:{audience_id} '{"reason":"hourly_tick"}'

// Sonuç: audience_changes_daily snapshot
// { audience_id, snapshot_date, member_count, joined_count, left_count, net_change }

CSV export

Download the active member list

GET /v1/audiences/:id/export.csv — active audience members as a simple 3-column CSV.

curl -X GET https://api.gurulu.io/v1/audiences/aud_01H8XYZ/export.csv \
  -H "Authorization: Bearer $GURULU_SECRET_KEY" \
  -o audience-members.csv

# CSV kolonlar:
# audience_id, person_id, joined_at

Columns

audience_id, person_id, joined_at. Hashed PII (email_sha256 etc.) is reserved for destination pushes — not in CSV export.

Quota

Free 3 / Custom unlimited

Active audience count is tracked by the M28 W3 quota dimension 'audiences'.

Plan

Active audience limit

Quota dimension

Free

3 active audiences (drafts + archived don't count)

audiences

Custom

Unlimited (usage-based, post-bill)

audiences

When the limit is hit, new audience creation is rejected; existing audiences keep running.

Use cases

Where audiences earn their keep

Four starter recipes — inspiration to define your own.

RFM high-value

3+ purchases in last 30 days + last purchase <14 days → premium remarketing pool.

Churn-risk

Active sub + no login in last 14 days → save-the-customer email + Meta CAPI suppression.

B2B account

Filter by company_domain → roll up every user from a target account into one audience.

Behavioral

Visitors who add_to_cart but never purchase → cart-abandonment campaign.

Related docs