Segment - Mavera

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

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).

Management API token

Generate an API token in Segment → Settings → Workspace → Access Management → Tokens. Grant Workspace Owner scope or narrow to specific resources.

Write Key (for Tracking API)

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

Mavera API key

Get your key from Mavera dashboard.

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

​API Reference Card

​Prerequisites

​Jobs

​Rate Limits & Production Notes

​What’s Next

All Integrations

Segment API Docs

Personas API

Focus Groups API

Mave Agent

API Reference Card

Prerequisites

Jobs

Rate Limits & Production Notes

What’s Next