> ## Documentation Index
> Fetch the complete documentation index at: https://docs.mavera.io/llms.txt
> Use this file to discover all available pages before exploring further.

# 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_...`                              |

<Info>
  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`.
</Info>

***

## Prerequisites

<Steps>
  <Step title="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).</Step>
  <Step title="Management API token">Generate an API token in Segment → Settings → Workspace → Access Management → Tokens. Grant **Workspace Owner** scope or narrow to specific resources.</Step>
  <Step title="Write Key (for Tracking API)">Find the Write Key in Segment → Sources → your source → Settings → API Keys.</Step>
  <Step title="Mavera API key">Get your key from [Mavera dashboard](https://app.mavera.io/settings/api-keys).</Step>

  <Step title="Environment variables">
    ```bash theme={"dark"}
    export SEGMENT_TOKEN="your-segment-api-token"
    export SEGMENT_WRITE_KEY="your-write-key"
    export MAVERA_API_KEY="mvra_live_xxxxx"
    ```
  </Step>
</Steps>

***

## Jobs

| # | Job                                                                                           | Segment Data                | Mavera Surface               | Output                                    |
| - | --------------------------------------------------------------------------------------------- | --------------------------- | ---------------------------- | ----------------------------------------- |
| 1 | [Audience Segments → Focus Groups](/integrations/segment/audience-focus-groups)               | Audiences API               | Focus Groups                 | Segment-specific qualitative insights     |
| 2 | [Profile Traits → Custom Persona Source](/integrations/segment/profile-traits-personas)       | Profile API computed traits | Custom Personas              | Trait-enriched personas via Advanced path |
| 3 | [Event Stream → Real-Time Persona Triggers](/integrations/segment/realtime-persona-triggers)  | Webhook destination         | Custom Personas / Mave Agent | Auto-triggered research from live events  |
| 4 | [Cross-Source Identity → Unified Persona](/integrations/segment/cross-source-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`                     |

<Warning>
  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.
</Warning>

**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](https://app.mavera.io/settings/usage). Webhook-triggered Mave calls can accumulate quickly — add rate limiting to your handler.                         |

***

## What's Next

<CardGroup cols={2}>
  <Card title="All Integrations" icon="plug" href="/integrations">
    50+ API integrations with full code
  </Card>

  <Card title="Segment API Docs" icon="diagram-project" href="https://segment.com/docs/api/">
    Official Segment API reference
  </Card>

  <Card title="Personas API" icon="users" href="/api-reference/personas">
    Full reference for POST /api/v1/personas
  </Card>

  <Card title="Focus Groups API" icon="comments" href="/api-reference/focus-groups">
    Full reference for POST /api/v1/focus-groups
  </Card>

  <Card title="Mave Agent" icon="brain" href="/api-reference/mave">
    Full reference for POST /api/v1/mave/chat
  </Card>
</CardGroup>