trait_get — Watt Data Docs

Retrieve detailed analytics for a single trait, including its top predictors, discriminators, and representative exemplar entities.

Quick Example

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

Input Parameters

Parameter	Type	Required	Default	Constraints	Description
entity_type	string	Yes	-	"person" or "business"	Type of entity
trait_hashes	string[]	Conditional	-	Max 100	Array of trait hashes to retrieve
domain	string	Conditional	-	See valid domains below	Trait domain for name-based lookup (requires trait_name and trait_value). Must be one of the valid domain values; invalid values are rejected with a validation error that lists the legal set.
trait_name	string	Conditional	-	-	Trait name for name-based lookup (requires domain and trait_value)
trait_value	string	Conditional	-	-	Trait value for name-based lookup (requires domain and trait_name)
csv_resource_uri	string	Conditional	-	-	Workflow resource URI to a CSV containing trait hashes for batch retrieval
trait_hash_column	string	No	"trait_hash"	-	Column name containing trait hashes in the CSV. Only used with csv_resource_uri
analytics_depth	number	No	10	5-50	Number of top results per analytics category
format	string	No	"none"	"none", "csv", "json", "jsonl"	Export format. When not "none", generates a presigned download URL valid for 1 hour
workflow_id	string	No	-	Valid UUID	Workflow session identifier

Identification: Provide exactly one of:

trait_hashes - Array of trait hashes (up to 100). Use trait_search to discover hashes.
domain + trait_name + trait_value - Deterministic name-based lookup
csv_resource_uri - Batch retrieval from a CSV file containing trait hashes

Valid domain values:

Person traits: affinity, content, demographic, employment, financial, household, intent, interest, lifestyle, political, purchase, geo
Business traits: about, appstore, digital, funding, hiring, industry, techstack

Geographic boundary discovery (domain: "geo", person only):

trait_get is the canonical way to discover and resolve geographic boundary traits. trait_search does not surface geo entries — use trait_get with domain="geo", trait_name=<type>, trait_value=<boundary_value> instead.

`trait_name` (boundary type)	`trait_value` format	Example
`state`	USPS two-letter code	`"CA"`
`zip5`	5-digit ZIP code	`"94103"`
`county`	County name as stored	`"Los Angeles"`
`dma`	Nielsen DMA numeric ID	`"506"`
`cbsa`	5-digit OMB code	`"10100"`
`msa`	2-4 digit OMB code	`"1000"`
`congressional_district`	Two-digit district number (today; state-prefixed after a planned upstream rebuild)	`"12"`

CBSA and MSA values are OMB numeric codes — not the structured "City1-City2, ST" name. For name→code lookup, see the Census Bureau CBSA delineation files.

For boundary types where the exact value is unknown (county, DMA, CBSA/MSA), guess from common naming conventions or fall back to a coarser boundary (e.g., state instead of county). trait_get returns "not found" for misses — retry with an alternate spelling or a broader boundary type.

Top-K analytics (predictors, discriminators, etc.) are empty for geo entries — only size, prevalence, and description carry information for geographies.

Request Schema:

interface TraitGetParams {
  entity_type: "person" | "business";
  trait_hashes?: string[];
  domain?: string;
  trait_name?: string;
  trait_value?: string;
  csv_resource_uri?: string;
  trait_hash_column?: string;
  analytics_depth?: number;
  format?: "none" | "csv" | "json" | "jsonl";
  workflow_id?: string;
}

Output Format

The response shape depends on how many traits are requested:

Single trait (trait_hashes with 1 entry, or domain+trait_name+trait_value): returns { trait: SemanticTrait, export?: ... }
Batch (trait_hashes with 2+ entries, or csv_resource_uri): returns { traits: SemanticTrait[], export?: ... }

// Single-trait response
{
  trait: SemanticTrait;
  export?: ExportMetadata;
  tool_trace_id: string;
  workflow_id: string;
}

// Batch response
{
  traits: SemanticTrait[];
  export?: ExportMetadata;
  tool_trace_id: string;
  workflow_id: string;
}

interface SemanticTrait {
  trait_id: string;
  trait_hash: string;
  name: string;
  value: string;
  domain: string;
  size: number;
  prevalence: number;
  skew: number;
  description?: string;
  // TopK analytics fields — currently returned as empty arrays (see deprecation note below)
  top_predictors: Array<{
    trait_id: string;
    lift: number;
    rank: number;
  }>;
  top_discriminators: Array<{
    trait_id: string;
    cohens_d: number;
    rank: number;
  }>;
  top_cooccurring: Array<{
    trait_id: string;
    prevalence: number;
    rank: number;
  }>;
  top_segments: Array<{
    segment_id: string;
    cohens_d: number;
    rank: number;
  }>;
  top_exemplars: Array<{
    entity_id: string;
    distance: number;
    rank: number;
  }>;
}

interface ExportMetadata {
  url: string;
  format: string;
  rows: number;
  expires_at: string;
  resource_uri: string;
}

Deprecation note: TopK analytics fields (top_predictors, top_discriminators, top_cooccurring, top_segments, top_exemplars) are currently returned as empty arrays — they remain in the schema for future use.

Response Fields:

Field	Type	Description
trait	object	Trait analytics data (single-trait mode only)
traits	array	Array of trait analytics objects (batch mode only)
trait.trait_id	string	Numeric trait identifier
trait.trait_hash	string	Stable hash identifier
trait.name	string	Trait name
trait.value	string	Trait value
trait.domain	string	Domain category
trait.size	number	Number of entities with this trait
trait.prevalence	number	Population proportion (0-1)
trait.skew	number	Data density skew correction factor
trait.description	string	Optional human-readable description
trait.top_predictors	array	Top traits that predict membership (currently empty)
trait.top_discriminators	array	Most distinguishing traits (currently empty)
trait.top_cooccurring	array	Top co-occurring traits (currently empty)
trait.top_segments	array	Top segments (currently empty)
trait.top_exemplars	array	Representative entity IDs (currently empty)
export	object	Export metadata (present when format !== "none")
export.url	string	Presigned download URL (valid 1 hour)
export.format	string	Export format used
export.rows	number	Number of rows in the export
export.expires_at	string	Expiry timestamp for the download URL
export.resource_uri	string	Workflow resource URI for downstream tool use
tool_trace_id	string	OpenTelemetry trace ID
workflow_id	string	Workflow session identifier

Example Response (single trait):

{
  "trait": {
    "trait_id": "1000000001",
    "trait_hash": "abc123def456",
    "name": "income_range",
    "value": "150000_plus",
    "domain": "demographic",
    "size": 2500000,
    "prevalence": 0.08,
    "skew": 1.2,
    "top_predictors": [],
    "top_discriminators": [],
    "top_cooccurring": [],
    "top_segments": [],
    "top_exemplars": []
  },
  "tool_trace_id": "a1b2c3d4e5f6",
  "workflow_id": "550e8400-e29b-41d4-a716-446655440000"
}

Example Response (batch):

{
  "traits": [
    {
      "trait_id": "1000000001",
      "trait_hash": "abc123def456",
      "name": "income_range",
      "value": "150000_plus",
      "domain": "demographic",
      "size": 2500000,
      "prevalence": 0.08,
      "skew": 1.2,
      "top_predictors": [],
      "top_discriminators": [],
      "top_cooccurring": [],
      "top_segments": [],
      "top_exemplars": []
    },
    {
      "trait_id": "1000000075",
      "trait_hash": "def789ghi012",
      "name": "luxury_retail",
      "value": "high",
      "domain": "purchase",
      "size": 1800000,
      "prevalence": 0.06,
      "skew": 0.9,
      "top_predictors": [],
      "top_discriminators": [],
      "top_cooccurring": [],
      "top_segments": [],
      "top_exemplars": []
    }
  ],
  "tool_trace_id": "b2c3d4e5f6a1",
  "workflow_id": "550e8400-e29b-41d4-a716-446655440000"
}

Common Errors

Error	Message
No lookup method provided	`Must provide one of: trait_hashes, csv_resource_uri, or domain+trait_name+trait_value.`
Multiple lookup methods provided	`trait_hashes, csv_resource_uri, and domain/trait_name/trait_value are mutually exclusive. Provide exactly one lookup method.`
Trait not found	`Trait not found: <identifier>. Use trait_search to discover valid trait identifiers.`
Invalid domain value	Validation error listing the valid domain set

Usage Examples

Example 1: Look up by trait hash

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

Example 2: Deterministic lookup by domain + name + value

{
  "entity_type": "person",
  "domain": "demographic",
  "trait_name": "income_range",
  "trait_value": "150000_plus"
}

Example 3: Batch lookup with multiple hashes

{
  "entity_type": "person",
  "trait_hashes": ["abc123def456", "def789ghi012", "jkl345mno678"],
  "analytics_depth": 25
}

Example 4: Batch retrieval from CSV

{
  "entity_type": "business",
  "csv_resource_uri": "workflow://550e8400-e29b-41d4-a716-446655440000/artifacts/trait-list.csv",
  "trait_hash_column": "hash",
  "format": "csv"
}

Example 5: Look up a geo trait by domain + name + value

{
  "entity_type": "person",
  "domain": "geo",
  "trait_name": "state",
  "trait_value": "CA"
}

Response:

{
  "trait": {
    "trait_id": "<state-CA hash>",
    "trait_hash": "<state-CA hash>",
    "name": "state",
    "value": "CA",
    "domain": "geo",
    "size": 26263444,
    "prevalence": 0.27,
    "skew": 0,
    "description": "California (CA)",
    "top_predictors": [],
    "top_discriminators": [],
    "top_cooccurring": [],
    "top_segments": [],
    "top_exemplars": []
  }
}

Quick Example

Input Parameters

Output Format

Common Errors

Usage Examples

On this page