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 | Integer, 1-100 | Maximum results to return |
| offset | number | No | 0 | Integer, >= 0 | Number of results to skip for pagination |
| domains | array | No | - | Subset of trait domains for the chosen entity_type | Filter results by trait domains. Allowed values depend on entity_type — see "Trait domains" below |
| format | string | No | "none" | "none", "csv", "json", "jsonl" | Export format |
| workflow_id | string | No | - | Valid UUID | Workflow session identifier |
Trait domains:
The values allowed in domains depend on entity_type and are validated server-side:
person→affinity,content,demographic,employment,financial,household,intent,interest,lifestyle,political,purchasebusiness→about,appstore,digital,funding,hiring,industry,techstack
A value outside the allowed set for the chosen entity_type is rejected with a validation error that lists the legal values.
Geographic boundaries are not surfaced through trait_search. Use trait_get with domain="geo" to look up a specific boundary by type and value. See the trait_get reference for details.
Request Schema:
interface TraitSearchParams {
entity_type: "person" | "business";
query: string;
limit?: number;
offset?: number;
// person: Array<"affinity" | "content" | "demographic" | "employment" | "financial" | "household" | "intent" | "interest" | "lifestyle" | "political" | "purchase">
// business: Array<"about" | "appstore" | "digital" | "funding" | "hiring" | "industry" | "techstack">
// "geo" is not a valid domain for trait_search; use trait_get for geographic boundary lookups.
// Values outside the allowed set are rejected with an invalid_enum_value error.
domains?: string[];
format?: "none" | "csv" | "json" | "jsonl";
workflow_id?: string;
}Output Format
{
results: Array<{
trait_id: string;
trait_hash: string;
entity_type: "person" | "business";
name: string;
value: string;
domain: string;
size: number;
prevalence: number;
similarity_score: number;
}>,
pagination: {
offset: number;
limit: number;
has_more: boolean;
},
export?: {
url: string;
format: string;
rows: number;
expires_at: string;
resource_uri: string;
},
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[].entity_type | string | Entity space the trait lives in ("person" or "business") |
| 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) |
| pagination | object | Pagination metadata |
| pagination.offset | number | Current offset |
| pagination.limit | number | Current limit |
| pagination.has_more | boolean | Whether more results exist beyond current page |
| export | object | Export metadata (when format is csv/json/jsonl) |
| export.resource_uri | string | Workflow resource URI for the exported file |
| tool_trace_id | string | OpenTelemetry trace ID |
| workflow_id | string | Workflow session identifier |
Example Response:
{
"results": [
{
"trait_id": "1000000001",
"trait_hash": "abc123def456",
"entity_type": "person",
"name": "golf_affinity",
"value": "high",
"domain": "affinity",
"size": 1500000,
"prevalence": 0.05,
"similarity_score": 0.92
},
{
"trait_id": "1000000002",
"trait_hash": "ghi789jkl012",
"entity_type": "person",
"name": "outdoor_recreation",
"value": "active",
"domain": "interest",
"size": 3200000,
"prevalence": 0.11,
"similarity_score": 0.78
}
],
"pagination": {
"offset": 0,
"limit": 10,
"has_more": true
},
"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: Paginated results
{
"entity_type": "person",
"query": "health and wellness interests",
"limit": 20,
"offset": 20
}Example 6: Business trait search
Business trait domains are: about, appstore, digital, funding, hiring, industry, techstack.
{
"entity_type": "business",
"query": "fast-growing direct-to-consumer wellness brands",
"domains": ["industry", "funding"]
}