tdx

Appearance

SDK API Reference / SegmentSDK

Class: SegmentSDK ​

Segment operations API

Methods ​

createActivation() ​

createActivation(parentId, segmentId, request): Promise<ActivationResponse>

Create a new activation for a segment

Parameters ​

parentId ​

string

Parent segment ID

segmentId ​

string

Segment ID

request ​

CreateActivationRequest

Activation creation request

Returns ​

Promise<ActivationResponse>

Created activation details

Throws ​

When the creation fails

Example ​

typescript
// Create activation
const activation = await segment.createActivation('123', '456', {
  name: 'Send to Salesforce',
  connectionId: 789,
  allColumns: true,
  scheduleType: 'daily',
});

createFolder() ​

createFolder(parentIdOrName, request): Promise<CreateSegmentFolderResponse>

Create a new segment folder for organization

Parameters ​

parentIdOrName ​

string

Parent segment ID or name

request ​

CreateSegmentFolderRequest

Folder creation request

Returns ​

Promise<CreateSegmentFolderResponse>

Created folder details

Throws ​

When the creation fails

Example ​

typescript
// Create top-level folder
const folder = await segment.createFolder('123', {
  name: 'Q1 2024 Campaigns',
  description: 'Campaign segments for Q1'
});

// Create nested folder
const folder = await segment.createFolder('My Audience', {
  name: 'West Region',
  parentFolderId: '789'
});

createJourneySegment() ​

createJourneySegment(request): Promise<string>

Create a journey-local segment that is associated with a specific journey. This uses the /entities/segments endpoint to create a segment-journey type (kind=3).

The workflow for creating journeys with entry criteria:

  1. Create the journey WITHOUT entry criteria first
  2. Call this method to create the segment with the journey's ID
  3. Update the journey to add entry criteria referencing this segment

Parameters ​

request ​

CreateJourneySegmentRequest

Journey segment creation request including journeyId

Returns ​

Promise<string>

Created segment ID

Throws ​

When the creation fails

createParent() ​

createParent(request): Promise<CreateParentSegmentResponse>

Create a new parent segment (audience)

Parameters ​

request ​

CreateParentSegmentRequest

Parent segment creation request

Returns ​

Promise<CreateParentSegmentResponse>

Created parent segment details

Throws ​

When the creation fails

Example ​

typescript
// Create minimal parent segment
const parent = await segment.createParent({
  name: 'My Audience',
  master: {
    parentDatabaseName: 'mydb',
    parentTableName: 'customers'
  }
});

// Create with attributes and behaviors
const parent = await segment.createParent({
  name: 'Customer 360',
  description: 'Complete customer view',
  scheduleType: 'daily',
  scheduleOption: '03:00',
  master: {
    parentDatabaseName: 'customer_data',
    parentTableName: 'customers'
  },
  attributes: [
    {
      name: 'Lifetime Value',
      type: 'number',
      parentDatabaseName: 'customer_data',
      parentTableName: 'metrics',
      parentColumn: 'ltv',
      parentKey: 'customer_id',
      foreignKey: 'customer_id'
    }
  ]
});

createSegment() ​

createSegment(parentId, request): Promise<CreateSegmentResponse>

Create a new child segment with filtering rules

Parameters ​

parentId ​

string

Parent segment ID

request ​

CreateSegmentRequest

Segment creation request

Returns ​

Promise<CreateSegmentResponse>

Created segment details

Throws ​

When the creation fails

Example ​

typescript
// Create segment with simple rule
const segment = await segment.createSegment('123', {
  name: 'High Value Customers',
  description: 'Customers with LTV > 1000',
  rule: {
    type: 'And',
    conditions: [
      {
        type: 'Value',
        leftValue: { name: 'Lifetime Value' },
        operator: { type: 'Greater', rightValue: 1000 }
      }
    ]
  }
});

// Create segment in folder
const segment = await segment.createSegment('123', {
  name: 'US Customers',
  segmentFolderId: '789',
  rule: {
    type: 'And',
    conditions: [
      {
        type: 'Value',
        leftValue: { name: 'Country' },
        operator: { type: 'Equal', rightValue: 'US' }
      }
    ]
  }
});

deleteActivation() ​

deleteActivation(parentId, segmentId, activationId): Promise<void>

Delete an activation

Parameters ​

parentId ​

string

Parent segment ID

segmentId ​

string

Segment ID

activationId ​

string

Activation ID

Returns ​

Promise<void>

Throws ​

When the deletion fails

Example ​

typescript
// Delete activation
await segment.deleteActivation('123', '456', '789');

deleteSegment() ​

deleteSegment(segmentId): Promise<void>

Delete a child segment

Parameters ​

segmentId ​

string

Segment ID to delete

Returns ​

Promise<void>

Throws ​

When the deletion fails

Example ​

typescript
// Delete segment by ID
await segment.deleteSegment('456');

detectResourceType() ​

detectResourceType(parentId, name): Promise<"folder" | "segment" | "ambiguous">

Detect resource type by name (folder, segment, or ambiguous)

Parameters ​

parentId ​

string

Parent segment ID

name ​

string

Resource name to detect

Returns ​

Promise<"folder" | "segment" | "ambiguous">

'folder', 'segment', or 'ambiguous' if both exist

Example ​

typescript
const type = await segment.detectResourceType('123', 'Marketing');
if (type === 'ambiguous') {
  // Prompt user to choose
}

detectResourceTypeInFolder() ​

detectResourceTypeInFolder(parentId, name, folderId?): Promise<"folder" | "segment" | "ambiguous">

Detect resource type by name within a specific folder

Parameters ​

parentId ​

string

Parent segment ID

name ​

string

Resource name to detect

folderId? ​

string

Folder ID to search within (undefined = root level)

Returns ​

Promise<"folder" | "segment" | "ambiguous">

'folder', 'segment', or 'ambiguous' if both exist

getActivation() ​

getActivation(parentId, segmentId, activationId): Promise<ActivationResponse>

Get activation details

Parameters ​

parentId ​

string

Parent segment ID

segmentId ​

string

Segment ID

activationId ​

string

Activation ID

Returns ​

Promise<ActivationResponse>

Activation details

Throws ​

When the activation is not found

Example ​

typescript
// Get activation details
const activation = await segment.getActivation('123', '456', '789');
console.log(activation.name);

getFolder() ​

getFolder(folderId): Promise<SegmentFolderDetails>

Get segment folder details by folder ID

Parameters ​

folderId ​

string

Folder ID

Returns ​

Promise<SegmentFolderDetails>

Folder details in JSON:API format

Throws ​

When the get operation fails

Example ​

typescript
// Get folder details
const folder = await segment.getFolder('456');
console.log(folder);

getParent() ​

getParent(parentId): Promise<ParentSegment>

Get parent segment details

Parameters ​

parentId ​

string

Parent segment ID

Returns ​

Promise<ParentSegment>

Parent segment details

Throws ​

When the get operation fails

Example ​

typescript
// Get parent segment details
const parent = await segment.getParent('123');
console.log(parent);

getParentFull() ​

getParentFull(parentIdOrName): Promise<CreateParentSegmentResponse>

Get full parent segment details including attributes and behaviors

Parameters ​

parentIdOrName ​

string

Parent segment ID or name

Returns ​

Promise<CreateParentSegmentResponse>

Full parent segment details

Throws ​

When the get operation fails

Example ​

typescript
// Get full details by ID
const parent = await segment.getParentFull('123');

// Get full details by name
const parent = await segment.getParentFull('My Audience');
console.log(parent.attributes, parent.behaviors);

getParentSQL() ​

getParentSQL(parentId): Promise<string>

Get SQL query for parent segment

Parameters ​

parentId ​

string

Parent segment ID

Returns ​

Promise<string>

SQL query string

Throws ​

When the SQL retrieval fails

Example ​

typescript
// Get SQL for parent segment
const sql = await segment.getParentSQL('123');
console.log(sql);

getSegment() ​

getSegment(parentId, segmentId): Promise<SegmentResponse>

Get segment details

Parameters ​

parentId ​

string

Parent segment ID

segmentId ​

string

Segment ID

Returns ​

Promise<SegmentResponse>

Segment details

Throws ​

When the get operation fails

Example ​

typescript
// Get segment details
const segment = await segment.getSegment('123', '456');
console.log(segment);

getSegmentSQL() ​

getSegmentSQL(parentId, segmentId): Promise<string>

Get SQL query for a segment with filtering

Parameters ​

parentId ​

string

Parent segment ID

segmentId ​

string

Segment ID

Returns ​

Promise<string>

SQL query string

Throws ​

When the SQL retrieval fails

Example ​

typescript
// Get SQL for segment
const sql = await segment.getSegmentSQL('123', '456');
console.log(sql);

listActivations() ​

listActivations(parentId, segmentId): Promise<ActivationResponse[]>

List activations for a segment

Parameters ​

parentId ​

string

Parent segment ID

segmentId ​

string

Segment ID

Returns ​

Promise<ActivationResponse[]>

Array of activations

Throws ​

When the list operation fails

Example ​

typescript
// List activations for segment
const activations = await segment.listActivations('123', '456');
console.log(activations);

listFields() ​

listFields(parentIdOrName): Promise<ParentSegmentField[]>

List available fields for a parent segment (for segmentation)

Extracts fields from parent segment's attributes and behaviors by calling GET /audiences/{id} and parsing the response.

Parameters ​

parentIdOrName ​

string

Parent segment ID or name

Returns ​

Promise<ParentSegmentField[]>

Array of available fields (attributes, behaviors)

Throws ​

When the list operation fails

Example ​

typescript
// List fields by ID
const fields = await segment.listFields('123');

// List fields by name
const fields = await segment.listFields('My Audience');
console.log(fields);

listFolders() ​

listFolders(parentId): Promise<SegmentFolder[]>

List segment folders under a parent segment

Parameters ​

parentId ​

string

Parent segment ID

Returns ​

Promise<SegmentFolder[]>

Array of segment folders

Throws ​

When the list operation fails

Example ​

typescript
// List segment folders
const folders = await segment.listFolders('123');
console.log(folders);

listParents() ​

listParents(): Promise<ParentSegment[]>

List all parent segments (audiences)

Returns ​

Promise<ParentSegment[]>

Array of parent segments

Throws ​

When the list operation fails

Example ​

typescript
// List all parent segments
const segments = await segment.listParents();
console.log(segments);

listRecursive() ​

listRecursive(parentId, folderId?, _depth?, maxDepth?): Promise<SegmentTreeNode[]>

Build a tree structure recursively from a parent or folder

Uses the /entities/by-folder API for efficient single-call retrieval of all entities (folders, segments, journeys) under a folder.

Parameters ​

parentId ​

string

Parent segment ID

folderId? ​

string

Optional folder ID to start from

_depth? ​

number

maxDepth? ​

number = 10

Maximum depth to traverse (default: 10, max: 32)

Returns ​

Promise<SegmentTreeNode[]>

Tree nodes with nested children (folders, segments, and journeys)

Deprecated ​

No longer used. Tree is built from single API response.

Example ​

typescript
// Build full tree recursively
const tree = await segment.listRecursive('123');
console.log(tree);

listSegments() ​

listSegments(parentId): Promise<SegmentResponse[]>

List segments under a parent segment

Parameters ​

parentId ​

string

Parent segment ID

Returns ​

Promise<SegmentResponse[]>

Array of child segments

Throws ​

When the list operation fails

Example ​

typescript
// List segments under parent
const segments = await segment.listSegments('123');
console.log(segments);

listUnifiedWithJourneys() ​

listUnifiedWithJourneys(parentId, folderId?): Promise<{ folders: SegmentFolder[]; journeys: JourneyListItem[]; segments: SegmentResponse[]; }>

List folders, segments, and journeys under a parent or within a folder (unified view)

Uses the /entities/by-folder API for efficient single-call retrieval.

Parameters ​

parentId ​

string

Parent segment ID

folderId? ​

string

Optional folder ID to list contents of a specific folder

Returns ​

Promise<{ folders: SegmentFolder[]; journeys: JourneyListItem[]; segments: SegmentResponse[]; }>

Object with folders, segments, and journeys arrays

Example ​

typescript
const { folders, segments, journeys } = await segment.listUnifiedWithJourneys('123');
console.log(`Found ${folders.length} folders, ${segments.length} segments, ${journeys.length} journeys`);

previewParentYaml() ​

previewParentYaml(yamlContent, options): Promise<PreviewResult>

Preview parent segment YAML sample data

Fetches sample data from tables - no validation, just raw data. Requires one of: master, attribute, behavior, or enriched option.

Parameters ​

yamlContent ​

YAML configuration string or parsed object

string | ParentSegmentDef

options ​

PreviewOptions = {}

Preview options (one required: master, attribute, behavior, enriched)

Returns ​

Promise<PreviewResult>

Preview result with sample data

pullParentYaml() ​

pullParentYaml(parentIdOrName): Promise<string>

Pull parent segment configuration as YAML string

Parameters ​

parentIdOrName ​

string

Parent segment ID or name

Returns ​

Promise<string>

YAML configuration string

Throws ​

When the parent segment is not found

Example ​

typescript
const yaml = await segment.pullParentYaml('Customer 360');
console.log(yaml);

pullSegments() ​

pullSegments(parentIdOrName, options): Promise<PullSegmentsResult>

Pull child segments and journeys from Treasure Data to YAML format.

This method fetches all child segments and journeys for a parent segment, converts them to YAML format, and calculates diffs against existing files.

The caller is responsible for:

  • Confirming with the user
  • Writing files to disk using the returned file data

Parameters ​

parentIdOrName ​

string

Parent segment ID or name

options ​

PullSegmentsOptions = {}

Pull options (targetDir, verbose, onProgress)

Returns ​

Promise<PullSegmentsResult>

Pull result with files and statistics

Example ​

typescript
// Pull all segments/journeys for a parent
const result = await segment.pullSegments('My Audience', {
  targetDir: 'segments/my-audience',
  onProgress: (phase) => console.log(phase)
});

// Check results
console.log(`${result.counts.segments} segments, ${result.counts.journeys} journeys`);
console.log(`${result.newFiles} new, ${result.changedFiles} changed`);

// Write files (caller responsibility)
for (const file of result.files) {
  if (file.isNew || file.hasChanges) {
    fs.mkdirSync(path.dirname(file.absolutePath), { recursive: true });
    fs.writeFileSync(file.absolutePath, file.content);
  }
}

pushParentYaml() ​

pushParentYaml(yamlContent): Promise<PushParentYamlResult & object>

Push parent segment configuration from YAML

This method compares the YAML configuration with the existing parent segment (if any) and returns diff information. It does NOT apply the changes automatically. Use the apply method on the result or call createParent/updateParent to apply.

Parameters ​

yamlContent ​

YAML configuration string or parsed object

string | ParentSegmentDef

Returns ​

Promise<PushParentYamlResult & object>

Push result with diff information and apply method

Throws ​

When YAML parsing fails or validation errors occur

Example ​

typescript
// Preview changes
const result = await segment.pushParentYaml(yamlContent);
if (result.hasChanges) {
  console.log(result.diffFormatted);
  // Apply changes
  await result.apply();
}

resolveFolderId() ​

resolveFolderId(parentId, name): Promise<string>

Resolve folder name to ID within a parent

Parameters ​

parentId ​

string

Parent segment ID

name ​

string

Folder name (case-sensitive)

Returns ​

Promise<string>

Folder ID

Throws ​

When the folder is not found

Example ​

typescript
// Resolve folder name to ID
const folderId = await segment.resolveFolderId('123', 'Marketing');
console.log(folderId); // '789'

resolveParentId() ​

resolveParentId(name): Promise<string>

Resolve parent segment name to ID

Parameters ​

name ​

string

Parent segment name (case-sensitive)

Returns ​

Promise<string>

Parent segment ID

Throws ​

When the parent segment is not found

Example ​

typescript
// Resolve parent name to ID
const parentId = await segment.resolveParentId('My Audience');
console.log(parentId); // '123'

resolvePathToResource() ​

resolvePathToResource(path): Promise<ResolvedSegmentPath>

Resolve a path string to a resource

Parameters ​

path ​

string

Path string (e.g., "My Audience/Marketing/High Value")

Returns ​

Promise<ResolvedSegmentPath>

Resolved path with IDs and type

Throws ​

When path is invalid or resource not found

Example ​

typescript
// Resolve path to segment or folder
const resolved = await segment.resolvePathToResource('My Audience/Marketing');
console.log(resolved.type); // 'folder'
console.log(resolved.folderId); // '456'

resolveSegmentId() ​

resolveSegmentId(parentId, name): Promise<string>

Resolve child segment name to ID within a parent

Parameters ​

parentId ​

string

Parent segment ID

name ​

string

Child segment name (case-sensitive)

Returns ​

Promise<string>

Child segment ID

Throws ​

When the child segment is not found

Example ​

typescript
// Resolve child segment name to ID
const segmentId = await segment.resolveSegmentId('123', 'High Value Users');
console.log(segmentId); // '456'

runParent() ​

runParent(parentIdOrName): Promise<AudienceExecution>

Run workflow to (re)generate a parent segment

Parameters ​

parentIdOrName ​

string

Parent segment ID or name

Returns ​

Promise<AudienceExecution>

Workflow execution details

Throws ​

When the parent segment is not found or run fails

Example ​

typescript
// Run parent segment workflow by name
const execution = await segment.runParent('My Audience');
console.log(`Workflow started: ${execution.workflowSessionId}`);

traversePath() ​

traversePath(pathSegments): Promise<ResolvedSegmentPath>

Traverse a multi-level path and resolve to final resource

Parameters ​

pathSegments ​

string[]

Array of path components (e.g., ['My Audience', 'Marketing', 'Campaigns'])

Returns ​

Promise<ResolvedSegmentPath>

Resolved path with IDs and type

Example ​

typescript
const resolved = await segment.traversePath(['My Audience', 'Marketing', 'High Value']);
console.log(resolved.type); // 'folder' or 'segment'

updateActivation() ​

updateActivation(parentId, segmentId, activationId, request): Promise<ActivationResponse>

Update an existing activation

Parameters ​

parentId ​

string

Parent segment ID

segmentId ​

string

Segment ID

activationId ​

string

Activation ID

request ​

UpdateActivationRequest

Activation update request

Returns ​

Promise<ActivationResponse>

Updated activation details

Throws ​

When the update fails

Example ​

typescript
// Update activation
const activation = await segment.updateActivation('123', '456', '789', {
  name: 'Updated Name',
  scheduleType: 'hourly',
});

updateParent() ​

updateParent(parentIdOrName, request): Promise<CreateParentSegmentResponse>

Update an existing parent segment (audience)

Parameters ​

parentIdOrName ​

string

Parent segment ID or name

request ​

CreateParentSegmentRequest

Parent segment update request

Returns ​

Promise<CreateParentSegmentResponse>

Updated parent segment details

Throws ​

When the update fails

Example ​

typescript
// Update by ID
const updated = await segment.updateParent('123', {
  description: 'Updated description',
  attributes: [...] // Add new attributes
});

// Update by name
const updated = await segment.updateParent('My Audience', {
  scheduleType: 'weekly',
  scheduleOption: '0' // Sunday
});

updateSegmentById() ​

updateSegmentById(parentId, segmentId, request): Promise<UpdateSegmentResponse>

Update an existing child segment

Parameters ​

parentId ​

string

Parent segment ID

segmentId ​

string

Child segment ID

request ​

UpdateSegmentRequest

Segment update request

Returns ​

Promise<UpdateSegmentResponse>

Updated segment details

Throws ​

When the update fails

Example ​

typescript
// Update segment name and description
const updated = await segment.updateSegmentById('123', '456', {
  name: 'Super High Value',
  description: 'LTV > 5000'
});

// Update segment rule
const updated = await segment.updateSegmentById('123', '456', {
  rule: {
    type: 'And',
    conditions: [
      {
        type: 'Value',
        leftValue: { name: 'Lifetime Value' },
        operator: { type: 'Greater', rightValue: 5000 }
      }
    ]
  }
});

validateParentYaml() ​

validateParentYaml(yamlContent, options): Promise<PreviewResult>

Validate parent segment YAML configuration

Validates schema and gathers statistics for a parent segment YAML before pushing. Does NOT fetch sample data - use previewParentYaml for that.

Parameters ​

yamlContent ​

YAML configuration string or parsed object

string | ParentSegmentDef

options ​

ValidateOptions = {}

Validate options for filtering what to validate

Returns ​

Promise<PreviewResult>

Preview result with validation and statistics

Copyright 2024-present Treasure Data