Attribute Observations

Returns individual brand trait observations: each row is one statement an AI response made about one entity (your brand or a competitor) for one attribute, with the supporting 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, because it was extracted before scoring existed or has no valid value. If you only need the direction, 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. 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. Also available as the MCP tool get_attribute_observations.

POST /api/v1/attributes/observations

Attribute Observations

cURL

curl --request POST \
  --url https://api.athenahq.ai/api/v1/attributes/observations \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: <api-key>' \
  --data '
{
  "website_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "filters": {
    "start_date": "2024-01-01T00:00:00.000Z",
    "schedule_id": "default",
    "end_date": "2024-12-31T23:59:59.999Z",
    "models": [
      "chatgpt",
      "perplexity"
    ],
    "prompt_ids": [
      "3c90c3cc-0d44-4b50-8888-8dd25736052a"
    ],
    "location_ids": [
      "123e4567-e89b-12d3-a456-426614174111"
    ]
  },
  "entity_ids": [
    "3c90c3cc-0d44-4b50-8888-8dd25736052a"
  ],
  "attribute_ids": [
    "3c90c3cc-0d44-4b50-8888-8dd25736052a"
  ],
  "positive": true,
  "sort": "intensity",
  "page_num": 0,
  "page_size": 40
}
'

200

{
  "data": [
    {
      "observation_id": "0b7c3f7e-2d4a-4c1e-9f3b-6a2e8d1c4b5a",
      "response_id": "7d9e1a2b-3c4d-4e5f-8a6b-9c0d1e2f3a4b",
      "entity_id": "123e4567-e89b-12d3-a456-426614174000",
      "entity_name": "Acme",
      "is_website": true,
      "attribute_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
      "attribute_name": "Affordable",
      "positive": true,
      "score": 0.9,
      "text_span": "Acme is by far the most affordable option for small teams.",
      "model": "chatgpt",
      "created_at": "2026-09-14T08:21:05Z"
    },
    {
      "observation_id": "5e6f7a8b-9c0d-4e1f-8a2b-3c4d5e6f7a8b",
      "response_id": "1a2b3c4d-5e6f-4a7b-8c9d-0e1f2a3b4c5d",
      "entity_id": "1f2e3d4c-5b6a-4798-8a9b-0c1d2e3f4a5b",
      "entity_name": "Globex",
      "is_website": false,
      "attribute_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
      "attribute_name": "Affordable",
      "positive": false,
      "score": null,
      "text_span": "Globex is priced above most alternatives.",
      "model": "perplexity",
      "created_at": "2026-08-02T17:44:39Z"
    }
  ],
  "page_num": 0,
  "page_size": 40,
  "has_more": false
}

Authorizations

x-api-key · string · header · required

API key for authentication. You can create one here.

Body

application/json

website_id · string<uuid> · required

filters · object · required

The shared filters without competitor_ids, for the brand trait endpoints that do not take it: /api/v1/attributes/cumulative is brand-only, and /api/v1/attributes/observations selects entities with entity_ids. Sending competitor_ids is rejected. Use /api/v1/attributes/competitors for per-competitor metrics.

Show child attributes

entity_ids · string<uuid>[]

Entities to return observations for: the website_id for your brand, or competitor ids from GET /api/v1/competitors. Omit for every entity.

Maximum array length: 100

attribute_ids · string<uuid>[]

Attributes to return observations for, from GET /api/v1/attributes. Omit for every active attribute.

Maximum array length: 100

positive · boolean

true for favorable observations only, false for critical ones only. Omit for both directions.

sort · enum<string> · default: intensity

intensity: strongest first, unscored last, then newest. recent: newest first.

Available options: intensity, recent

page_num · integer · default: 0

Zero-indexed page number.

Required range: x >= 0

page_size · integer · default: 40

Rows per page.

Required range: 1 <= x <= 100

Response

200

application/json

Successful response with a page of observations

data · object[] · required

Show child attributes

page_num · integer · required

Zero-indexed page number returned.

page_size · integer · required

Maximum rows per page.

has_more · boolean · required

true if another page is available.