trait_list

Browse available traits by entity type, with optional filtering by domain, trait ID, or name.

Quick Example

{
  "entity_type": "person",
  "domains": ["demographic"]
}

Input Parameters

Parameter	Type	Required	Default	Constraints	Description
entity_type	string	Yes	-	"person" or "business"	Type of entity to list traits for
domains	array	No	-	See available domains	Filter by trait domains
trait_ids	array	No	-	String array	Filter by specific trait IDs
trait_hashes	array	No	-	String array	Filter by specific trait hashes
trait_names	array	No	-	String array	Filter by trait names (exact match)
include_all	boolean	No	false	-	Retrieve all traits (for initial discovery)
limit	number	No	50	5-10000	Maximum traits to return
offset	number	No	0	>= 0	Pagination offset
workflow_id	string	No	-	Valid UUID	Workflow session identifier

Parameter Details:

entity_type:

Required. Use "person" for individual traits or "business" for company traits.

domains:

Available domains: purchase, demographic, intent, interest, financial, firmographic, affinity, content, employment, household, lifestyle, political
Example: ["demographic", "interest"]

include_all:

Set to true to retrieve all available traits without filtering
Useful for initial discovery and exploration
If false, at least one filter (domains, trait_ids, trait_hashes, or trait_names) must be provided

Request Schema:

interface TraitListParams {
  entity_type: "person" | "business";
  domains?: Array<"purchase" | "demographic" | "intent" | "interest" | "financial" | "firmographic" | "affinity" | "content" | "employment" | "household" | "lifestyle" | "political">;
  trait_ids?: string[];
  trait_hashes?: string[];
  trait_names?: string[];
  include_all?: boolean;
  limit?: number;
  offset?: number;
  workflow_id?: string;
}

Output Format

{
  traits: Array<{
    trait_id: string;
    trait_hash: string;
    name: string;
    value: string;
    domain: string;
    size: number;
    prevalence: number;
    skew: number;
  }>,
  total: number,
  returned: number,
  has_more: boolean,
  next_offset?: number,
  tool_trace_id: string,
  workflow_id: string
}

Response Fields:

Field	Type	Description
traits	array	Array of trait metadata
traits[].trait_id	string	Numeric trait identifier (may change across rebuilds)
traits[].trait_hash	string	Stable hash identifier (persists across rebuilds)
traits[].name	string	Trait name (e.g., "income_range")
traits[].value	string	Trait value (e.g., "150000_plus")
traits[].domain	string	Domain category
traits[].size	number	Number of entities with this trait
traits[].prevalence	number	Proportion of total population (0-1)
traits[].skew	number	Statistical skew measure
total	number	Total matching traits
returned	number	Number returned in this page
has_more	boolean	Whether more results exist
tool_trace_id	string	OpenTelemetry trace ID
workflow_id	string	Workflow session identifier

Example Response:

{
  "traits": [
    {
      "trait_id": "1000000001",
      "trait_hash": "abc123def456",
      "name": "income_range",
      "value": "150000_plus",
      "domain": "demographic",
      "size": 2500000,
      "prevalence": 0.08,
      "skew": 1.2
    },
    {
      "trait_id": "1000000002",
      "trait_hash": "ghi789jkl012",
      "name": "education",
      "value": "graduate_degree",
      "domain": "demographic",
      "size": 4200000,
      "prevalence": 0.14,
      "skew": 0.9
    }
  ],
  "total": 45,
  "returned": 2,
  "has_more": true,
  "next_offset": 2,
  "tool_trace_id": "a1b2c3d4e5f6",
  "workflow_id": "550e8400-e29b-41d4-a716-446655440000"
}

Usage Examples

Example 1: Browse demographic traits

{
  "entity_type": "person",
  "domains": ["demographic"]
}

Example 2: Browse multiple domains

{
  "entity_type": "person",
  "domains": ["demographic", "interest", "affinity"],
  "limit": 100
}

Example 3: Look up specific trait hashes

{
  "entity_type": "person",
  "trait_hashes": ["abc123def456", "ghi789jkl012"]
}

Example 4: Discover all traits

{
  "entity_type": "person",
  "include_all": true,
  "limit": 10000
}

Example 5: Paginated browsing

{
  "entity_type": "person",
  "domains": ["interest"],
  "limit": 50,
  "offset": 50
}

Quick Example

Input Parameters

Output Format

Usage Examples

On this page