ATathenahq
Attributes

Attribute Observations

Changed on

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

Request

  • Base URL
    https://api.athenahq.ai
  • Auth
    API key in header x-api-key

Request body

website_idstring uuid required
entity_idsstring[]

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

attribute_idsstring[]

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

positiveboolean

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

sort'intensity' | 'recent'

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

page_numinteger

Zero-indexed page number.

page_sizeinteger

Rows per page.

Example request

{
  "filters": {
    "start_date": "2024-01-01T00:00:00.000Z",
    "end_date": "2024-12-31T23:59:59.999Z",
    "models": [
      "chatgpt",
      "perplexity"
    ],
    "location_ids": [
      "123e4567-e89b-12d3-a456-426614174111"
    ]
  }
}

Response

Successful response with a page of observations

page_numinteger required

Zero-indexed page number returned.

page_sizeinteger required

Maximum rows per page.

has_moreboolean required

true if another page is available.

Example response

{
  "data": [
    {
      "entity_name": "Acme",
      "attribute_name": "Affordable",
      "score": 0.9,
      "model": "chatgpt",
      "created_at": "2026-09-14T08:21:05Z"
    }
  ]
}

Changes