Search for traits using natural language descriptions. Converts your query into a vector embedding and finds traits with similar semantic meaning.
Quick Example
{
"entity_type": "person",
"query": "people interested in outdoor activities and camping",
"domains": ["affinity", "interest"],
"limit": 20
}Input Parameters
| Parameter | Type | Required | Default | Constraints | Description |
|---|---|---|---|---|---|
| entity_type | string | Yes | - | "person" or "business" | Type of entity to search traits for |
| query | string | Yes | - | Min 1 character | Natural language description of desired traits |
| limit | number | No | 10 | 1-100 | Maximum results to return |
| domains | array | No | - | See available domains | Filter results by domains |
| workflow_id | string | No | - | Valid UUID | Workflow session identifier |
Request Schema:
interface TraitSearchParams {
entity_type: "person" | "business";
query: string;
limit?: number;
domains?: Array<"purchase" | "demographic" | "intent" | "interest" | "financial" | "firmographic" | "affinity" | "content" | "employment" | "household" | "lifestyle" | "political">;
workflow_id?: string;
}Output Format
{
results: Array<{
trait_id: string;
trait_hash: string;
name: string;
value: string;
domain: string;
size: number;
prevalence: number;
similarity_score: number;
}>,
tool_trace_id: string,
workflow_id: string
}Response Fields:
| Field | Type | Description |
|---|---|---|
| results | array | Array of matching traits ranked by similarity |
| results[].trait_id | string | Numeric trait identifier |
| results[].trait_hash | string | Stable hash identifier |
| results[].name | string | Trait name |
| results[].value | string | Trait value |
| results[].domain | string | Domain category |
| results[].size | number | Number of entities with this trait |
| results[].prevalence | number | Population proportion (0-1) |
| results[].similarity_score | number | Semantic similarity to query (0-1) |
| tool_trace_id | string | OpenTelemetry trace ID |
| workflow_id | string | Workflow session identifier |
Example Response:
{
"results": [
{
"trait_id": "1000000001",
"trait_hash": "abc123def456",
"name": "golf_affinity",
"value": "high",
"domain": "affinity",
"size": 1500000,
"prevalence": 0.05,
"similarity_score": 0.92
},
{
"trait_id": "1000000002",
"trait_hash": "ghi789jkl012",
"name": "outdoor_recreation",
"value": "active",
"domain": "interest",
"size": 3200000,
"prevalence": 0.11,
"similarity_score": 0.78
}
],
"tool_trace_id": "a1b2c3d4e5f6",
"workflow_id": "550e8400-e29b-41d4-a716-446655440000"
}Usage Examples
Example 1: Simple semantic search
{
"entity_type": "person",
"query": "people interested in golf and country clubs"
}Example 2: Filtered by domain
{
"entity_type": "person",
"query": "high income professionals",
"domains": ["demographic", "employment"]
}Example 3: Broad discovery
{
"entity_type": "person",
"query": "technology early adopters",
"limit": 25
}Example 4: Intent-based search
{
"entity_type": "person",
"query": "people looking to buy a new car",
"domains": ["intent"]
}Example 5: Business trait search
{
"entity_type": "business",
"query": "SaaS companies with over 100 employees",
"domains": ["firmographic"]
}