Segment

4 production-ready jobs — audience-to-focus-groups mapping, computed-trait persona creation, real-time event-driven triggers, and cross-source unified personas

Segment is your customer data backbone — audiences, traits, events, and identity resolution across every channel. These four jobs connect Segment’s CDP capabilities to Mavera’s surfaces (Focus Groups, Custom Personas, Mave Agent) so your research reflects real behavioral segments, your personas are enriched with computed traits, and your research triggers in real time when user behavior changes.

---

API Reference Card

Detail	Value
Management API	https://api.segmentapis.com
Tracking API	https://api.segment.io/v1
Auth (Management)	Authorization: Bearer {SEGMENT_TOKEN}
Auth (Tracking)	Write Key via HTTP Basic (writeKey: as username, empty password)
Rate limits	1,000 req/sec (Tracking API); Management API varies by endpoint
Mavera base	https://app.mavera.io/api/v1
Mavera auth	Authorization: Bearer mvra_live_...

All examples use two environment variables: SEGMENT_TOKEN (Management API bearer token with Workspace Owner or appropriate scope) and MAVERA_API_KEY. The Tracking API examples also reference SEGMENT_WRITE_KEY for sending events. Python examples use requests; JavaScript examples use fetch.

---

Prerequisites

1. Segment workspace with sources

   You need an active Segment workspace with at least one source connected and flowing events. Audiences require Segment Engage (formerly Personas).
2. Management API token

   Generate an API token in Segment → Settings → Workspace → Access Management → Tokens. Grant Workspace Owner scope or narrow to specific resources.
3. Write Key (for Tracking API)

   Find the Write Key in Segment → Sources → your source → Settings → API Keys.
4. Mavera API key

   Get your key from Mavera dashboard.
5. Environment variables

   export SEGMENT_TOKEN="your-segment-api-token"
   export SEGMENT_WRITE_KEY="your-write-key"
   export MAVERA_API_KEY="mvra_live_xxxxx"
   

---

Jobs

#	Job	Segment Data	Mavera Surface	Output
1	Audience Segments → Focus Groups	Audiences API	Focus Groups	Segment-specific qualitative insights
2	Profile Traits → Custom Persona Source	Profile API computed traits	Custom Personas	Trait-enriched personas via Advanced path
3	Event Stream → Real-Time Persona Triggers	Webhook destination	Custom Personas / Mave Agent	Auto-triggered research from live events
4	Cross-Source Identity → Unified Persona	Identity graph	Mave Agent	Cross-channel unified persona

---

Rate Limits & Production Notes

Segment API	Limit	Strategy
Tracking API (api.segment.io)	1,000 req/sec burst	Batch with analytics.flush() or use .batch() endpoint
Management API (api.segmentapis.com)	Varies by endpoint; typically 10 req/sec	Add 100ms delays between calls; retry on 429
Profiles API	~100 req/sec for reads	Paginate with cursor; cache profiles locally
Webhooks (outbound)	Segment retries 3x with exponential backoff	Implement idempotency via messageId

Segment’s Management API has per-endpoint rate limits that aren’t always documented. If you hit 429 errors, implement exponential backoff starting at 1 second. The Tracking API’s 1,000/sec limit is generous but applies per-source.

Production checklist:

Concern	Recommendation
Token scoping	Use minimum-privilege tokens. For read-only jobs (1, 2, 4), create a token with read-only scope. Only the webhook job needs write access.
Workspace vs. space	Management API tokens are scoped to workspaces. Space IDs (spa_xxx) identify Engage spaces within a workspace.
Webhook reliability	Deploy webhook handlers to serverless platforms with auto-scaling. Segment retries on 5xx but drops on 4xx — return 200 even if downstream fails, then process asynchronously.
Data freshness	Computed traits update on a schedule (typically hourly). Real-time personas from webhooks are immediate but compute-trait-based personas have lag.
Mavera credits	Monitor at Dashboard. Webhook-triggered Mave calls can accumulate quickly — add rate limiting to your handler.

---

What’s Next

All Integrations

50+ API integrations with full code

Segment API Docs

Official Segment API reference

Personas API

Full reference for POST /api/v1/personas

Focus Groups API

Full reference for POST /api/v1/focus-groups

Mave Agent

Full reference for POST /api/v1/mave/chat