Get individual brand trait (attribute) observations: each row is one AI response describing one entity (the brand or a competitor) with one brand trait, including the response excerpt as `text_span`. `score` runs from -1 to 1 and its sign always matches `positive`; its magnitude (0.1 to 1.0) is how strongly the wording praises or criticizes. `score` is null when the observation was not scored (extracted before scoring existed, or no valid value was recorded); for direction only, use `score ?? (positive ? 1 : -1)`. Omit `positive` for both directions. `sort: "intensity"` (the default) returns the strongest observations first with unscored ones last; `sort: "recent"` returns the newest first. Narrow with entity_ids and attribute_ids (from get_attributes). Paginate with page_num and page_size; a page can hold fewer than page_size rows when an excerpt is no longer available, so use `has_more` to decide whether to fetch the next page. Use get_attribute_metrics for how often each trait is mentioned.
View input schema
{
"type": "object",
"properties": {
"website_id": {
"type": "string",
"format": "uuid",
"pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
},
"filters": {
"type": "object",
"properties": {
"start_date": {
"description": "Start of the date range. Required. Accepts YYYY-MM-DD, ISO 8601 timestamps (timezone omitted means UTC), English month names with a four-digit year, and unambiguous numeric dates separated by /, -, or .; ambiguous dates are rejected.",
"type": "string"
},
"schedule_id": {
"description": "One schedule: \"default\" or a custom/archived schedule UUID. Omit for Default, which includes all pre-cutover history and ad hoc runs. The retired \"manual\" token is accepted as an alias of \"default\". Schedules cannot be combined.",
"anyOf": [
{
"type": "string",
"enum": [
"default",
"manual"
]
},
{
"type": "string",
"format": "uuid",
"pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
}
]
},
"end_date": {
"description": "End of the date range, inclusive. Date-only values include the UTC day through 23:59:59.999; timestamps keep their exact instant. Accepts YYYY-MM-DD, ISO 8601 timestamps (timezone omitted means UTC), English month names with a four-digit year, and unambiguous numeric dates separated by /, -, or .; ambiguous dates are rejected.",
"type": "string"
},
"models": {
"description": "AI models to include, as an array even for one model — e.g. [\"chatgpt\", \"perplexity\"]. Omit to include all models.",
"type": "array",
"items": {
"type": "string",
"enum": [
"chatgpt",
"perplexity",
"gemini",
"google_ai_overview",
"copilot",
"claude",
"ai_mode",
"grok",
"deepseek",
"meta_ai",
"mistral"
]
}
},
"prompt_ids": {
"description": "Prompt UUIDs to filter to, as an array even for one id. Omit for all prompts.",
"type": "array",
"items": {
"type": "string",
"format": "uuid",
"pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
}
},
"location_ids": {
"description": "Location UUIDs to filter to, as an array even for one id. The literal string \"no-location\" selects responses that ran without a location. Omit for all locations.",
"type": "array",
"items": {
"anyOf": [
{
"type": "string",
"format": "uuid",
"pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
},
{
"type": "string",
"const": "no-location"
}
]
}
},
"persona_ids": {
"description": "Persona UUIDs to filter to, as an array even for one id. Omit for all personas.",
"type": "array",
"items": {
"type": "string",
"format": "uuid",
"pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
}
},
"target_identifiers": {
"description": "Target identifier strings to filter to, as an array even for one value. The literal string \"no-identifier\" selects responses with no target identifier. Omit for all.",
"type": "array",
"items": {
"anyOf": [
{
"type": "string"
},
{
"type": "string",
"const": "no-identifier"
}
]
}
},
"variation_filter": {
"description": "Which prompt rows to include, as an array: \"prompt\" for base prompts, \"variation\" for generated variations, or both. Omit for both.",
"type": "array",
"items": {
"type": "string",
"enum": [
"variation",
"prompt"
]
}
},
"prompt_tags": {
"description": "Prompt tag IDs to filter prompts by, as an array (list tags with get_prompt_tags). Omit for all tags.",
"type": "array",
"items": {
"type": "string"
}
},
"prompt_tags_operator": {
"description": "How prompt_tags combine: \"is_any_of\" matches prompts with any listed tag, \"has_all_of\" only prompts carrying every listed tag.",
"type": "string",
"enum": [
"is_any_of",
"has_all_of"
]
},
"prompt_status": {
"description": "Filter prompts by tracking status: \"active\" or \"paused\". Omit for both.",
"type": "string",
"enum": [
"active",
"paused"
]
},
"prompt_type": {
"description": "Filter prompts by type: \"branded\" (mentions the brand) or \"non_branded\". Omit for both.",
"type": "string",
"enum": [
"branded",
"non_branded"
]
}
},
"required": [
"start_date"
],
"additionalProperties": false
},
"entity_ids": {
"description": "Entity UUIDs to filter to, as an array even for one id: the website_id for the brand itself, competitor ids from get_competitors for competitors. Omit for every entity.",
"maxItems": 100,
"type": "array",
"items": {
"type": "string",
"format": "uuid",
"pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
}
},
"attribute_ids": {
"description": "Attribute UUIDs to filter to (from get_attributes), as an array even for one id. Omit for every active attribute.",
"maxItems": 100,
"type": "array",
"items": {
"type": "string",
"format": "uuid",
"pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
}
},
"positive": {
"description": "true for favorable observations only, false for critical ones only. Omit for both directions.",
"type": "boolean"
},
"sort": {
"default": "intensity",
"description": "\"intensity\" (default): strongest first, unscored last, then newest. \"recent\": newest first.",
"type": "string",
"enum": [
"intensity",
"recent"
]
},
"page_num": {
"default": 0,
"description": "Zero-indexed page number. Defaults to 0.",
"type": "integer",
"minimum": 0,
"maximum": 9007199254740991
},
"page_size": {
"default": 40,
"description": "Rows per page, 1 to 100. Defaults to 40.",
"type": "integer",
"minimum": 1,
"maximum": 100
}
},
"required": [
"website_id",
"filters"
],
"$schema": "http://json-schema.org/draft-07/schema#"
}