How to Integrate Retool with Segment

Segment's Public API uses personal access tokens scoped to specific workspace operations. Log in to your Segment workspace and navigate to Settings → Workspace Settings → Access Management → Tokens. Click Create Token. Give the token a descriptive name like 'Retool Integration'. Select the appropriate access level for the operations your Retool dashboard needs — for a management dashboard, select 'Workspace Owner' to access all API operations, or use more granular Function Access/Source Access/Destination Access scopes if your organization requires least-privilege access. After creating the token, copy it immediately — it is displayed only once. Store it securely. The token is used as a Bearer token in your Retool REST API Resource. Segment's Public API base URL is https://api.segmentapis.com — note this is different from the Tracking API (api.segment.io) which is for sending events, not for workspace management. For the Profile API (user profile lookup), you need a separate configuration: navigate to Unify → Profile API Settings and note the Profile API Access Token and your Space ID — these are different credentials from the Public API token.

Create two resources in Retool — one for the Public API and one for the Profile API (if needed). For the Public API: navigate to Resources → Add Resource → REST API. Name it 'Segment Public API'. Set the Base URL to https://api.segmentapis.com. In Authentication, select Bearer Token and paste your access token. Add a default header: Content-Type with value application/json. Click Save Changes. To test, create a query with GET method and path /workspaces — if it returns your workspace list, the connection is working. For the Profile API (optional, requires Unify/Engage): create a second resource named 'Segment Profile API'. The base URL format for Profile API is https://profiles.segment.com/v1/spaces/YOUR_SPACE_ID — replace YOUR_SPACE_ID with your Unify Space ID from Settings. In Authentication, select Basic Auth — Segment Profile API uses Basic Auth where the username is your Profile API access token and the password is empty. Click Save Changes. Store both tokens in Retool Configuration Variables as secrets for secure rotation: SEGMENT_PUBLIC_TOKEN and SEGMENT_PROFILE_TOKEN.

Create queries to manage your Segment workspace configuration. Create a query named 'getSources'. Set Method to GET, Path to /sources. Add URL parameters: pagination[count] → 25, pagination[cursor] → {{ sourcePagination.cursor || '' }}. Segment's Public API uses cursor-based pagination — the response includes a nextCursor value to fetch subsequent pages. Create a transformer to normalize source data. Create a second query 'getSourceDestinations' — GET /sources/{{ sourcesTable.selectedRow.id }}/destinations. This returns all destinations connected to the selected source. Create a query 'toggleDestination' for enabling or disabling destinations — PATCH /destinations/{{ destinationsTable.selectedRow.id }}. Body: { 'destination': { 'enabled': {{ !destinationsTable.selectedRow.enabled }} } }. For workspace overview, create 'getWorkspace' — GET /workspaces — to display workspace-level metadata. Build a Dashboard layout with: a left Table for sources, a right Table for that source's destinations, and a bottom panel showing destination connection details and settings when a destination row is selected.

1// Transformer: normalize Segment sources for Table display
2const sources = data.data?.sources || [];
3return sources.map(source => ({
4  id: source.id,
5  name: source.name,
6  slug: source.slug,
7  enabled: source.enabled,
8  category: source.metadata?.categories?.[0] || 'Unknown',
9  type: source.metadata?.name || source.slug,
10  created_at: source.createdAt
11    ? new Date(source.createdAt).toLocaleDateString()
12    : 'Unknown',
13  workspace_id: source.workspaceId
14}));

The Segment Profile API enables real-time user profile lookups by user ID, anonymous ID, or email. This is valuable for support and customer success teams who need to understand what behavioral data exists for a specific user. Create a query named 'lookupProfile'. Using the Segment Profile API resource, set Method to GET. The path structure is /users/{{ userIdentifier.value }}/traits — where the identifier type depends on the value format. For email lookups, Segment requires the identifier to be prefixed with the namespace: email:user@example.com. For user_id lookups: user_id:abc123. Segment requires the 'external_ids' identifier type prefix. Alternatively, use the collection-based path: /collections/users/profiles/{{ encodeURIComponent('email:' + emailInput.value) }}/traits. Add URL params: limit → 25. Create a second query 'getProfileEvents' — GET /collections/users/profiles/{{ encodeURIComponent('email:' + emailInput.value) }}/events, URL param: limit → 20. Build a two-panel layout: a search bar for email at the top, profile traits displayed in a key-value Table on the left, and recent events listed chronologically on the right. Add a 'Merge with Internal Data' section that triggers a PostgreSQL query using the email to join Segment profile data with your application customer records.

1// Transformer: reshape Segment profile traits for display
2const traits = data.traits || {};
3
4// Convert traits object to key-value array for Retool Table
5return Object.entries(traits).map(([key, value]) => ({
6  trait: key,
7  value: typeof value === 'object' ? JSON.stringify(value) : String(value || ''),
8  type: typeof value
9})).sort((a, b) => a.trait.localeCompare(b.trait));

Tracking plans are the quality control layer for Segment data — they define the expected schema for events and properties. Mismatched events generate violations that affect data quality downstream. Create a query named 'getTrackingPlans' — GET /tracking-plans. This returns all tracking plans in your workspace. Create a second query 'getTrackingPlanRules' — GET /tracking-plans/{{ trackingPlansTable.selectedRow.id }}/rules. URL params: pagination[count] → 50. Each rule represents an event type with its required and optional properties defined in JSON Schema format. Create a transformer that extracts the event name, type (track/identify/group/page), description, and property count from the JSON Schema definition in each rule. Build a two-level Table view: the top Table shows tracking plans with event count and source connections; selecting a plan shows its rules in the lower Table with event names and property schemas. For monitoring violations, Segment's Public API includes event delivery stats in the source configuration — look for the violations.count field in source metadata responses. Add a Chart component showing violation counts over time for the selected source to help data teams monitor data quality trends. For complex integrations involving tracking plan automation, destination monitoring workflows, and multi-workspace management, RapidDev's team can help architect your Retool Segment management solution.

1// Transformer: normalize Segment tracking plan rules for Table display
2const rules = data.data?.rules || [];
3return rules.map(rule => {
4  const schema = rule.jsonSchema || {};
5  const properties = schema.properties || {};
6  const required = schema.required || [];
7
8  return {
9    id: rule.key,
10    event_name: rule.key,
11    type: rule.type || 'track',
12    description: schema.description || '',
13    property_count: Object.keys(properties).length,
14    required_count: required.length,
15    version: rule.version || 1,
16    created_at: rule.createdAt
17      ? new Date(rule.createdAt).toLocaleDateString()
18      : 'Unknown'
19  };
20});