> ## Documentation Index > Fetch the complete documentation index at: https://docs.athenahq.ai/llms.txt > Use this file to discover all available pages before exploring further. # 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`. ## OpenAPI ````yaml /api-reference/openapi.json post /api/v1/attributes/observations openapi: 3.1.0 info: title: AthenaHQ API description: >- AthenaHQ API provides programmatic access to manage your websites and prompts for AI-powered content optimization. version: 1.0.0 contact: email: support@athenahq.ai servers: - url: https://api.athenahq.ai description: Production server security: - apiKey: [] tags: - name: Basics description: Core API operations for managing websites and prompts - name: Metrics description: Metrics and analytics endpoints for tracking AI visibility - name: Billing description: Billing and credits endpoints for managing usage - name: Team Management description: Endpoints for managing team members and invitations - name: Groups description: Endpoints for managing groups of websites - name: Content description: >- Endpoints for accessing Content Hub data — tabs, tracked URLs, and per-URL prompt breakdowns. - name: Pitch Workspace description: >- Endpoints for accessing pitch workspace reports — org-scoped pitch runs with competitors, prompts, attributes, and aggregate metrics. - name: Knowledge Base description: >- Endpoints for reading the brand Knowledge Base — approved brand facts and the pillars that organize them. paths: /api/v1/attributes/observations: post: tags: - Attributes summary: Attribute Observations description: >- 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`. operationId: getAttributeObservations requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/AttributeObservationsRequest' responses: '200': description: Successful response with a page of observations content: application/json: schema: type: object properties: data: type: array items: $ref: '#/components/schemas/AttributeObservation' page_num: type: integer description: Zero-indexed page number returned. page_size: type: integer description: Maximum rows per page. has_more: type: boolean description: '`true` if another page is available.' required: - data - page_num - page_size - has_more example: 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 '400': description: Bad request - Invalid parameters content: application/json: schema: $ref: '#/components/schemas/Error' '401': description: Unauthorized - Invalid or missing API key content: application/json: schema: $ref: '#/components/schemas/Error' '403': description: Forbidden - API key cannot access this website content: application/json: schema: $ref: '#/components/schemas/Error' '404': description: Not found - Website does not exist content: application/json: schema: $ref: '#/components/schemas/Error' security: - apiKey: [] components: schemas: AttributeObservationsRequest: type: object properties: website_id: type: string format: uuid filters: $ref: '#/components/schemas/ApiFiltersNoCompetitors' entity_ids: type: array maxItems: 100 description: >- Entities to return observations for: the `website_id` for your brand, or competitor ids from `GET /api/v1/competitors`. Omit for every entity. items: type: string format: uuid attribute_ids: type: array maxItems: 100 description: >- Attributes to return observations for, from `GET /api/v1/attributes`. Omit for every active attribute. items: type: string format: uuid positive: type: boolean description: >- `true` for favorable observations only, `false` for critical ones only. Omit for both directions. sort: type: string enum: - intensity - recent default: intensity description: >- `intensity`: strongest first, unscored last, then newest. `recent`: newest first. page_num: type: integer minimum: 0 default: 0 description: Zero-indexed page number. page_size: type: integer minimum: 1 maximum: 100 default: 40 description: Rows per page. required: - website_id - filters AttributeObservation: type: object description: >- One brand trait observation: what one AI response said about one entity for one attribute. properties: observation_id: type: string format: uuid response_id: type: string format: uuid description: The AI response the excerpt comes from. entity_id: type: string format: uuid description: >- The entity described: your `website_id` for your brand, otherwise a competitor id. entity_name: type: string example: Acme is_website: type: boolean description: '`true` when the entity is your brand.' attribute_id: type: string format: uuid attribute_name: type: string example: Affordable positive: type: boolean description: >- Whether this observation praises (`true`) or criticizes (`false`) the entity on this attribute. score: type: - number - 'null' minimum: -1 maximum: 1 description: >- Signed strength from -1 to 1. The sign always matches `positive`; the magnitude (0.1 to 1.0) is how strongly the wording praises or criticizes. `null` when the observation was not scored, because it was extracted before scoring existed or has no valid value. For direction only, use `score ?? (positive ? 1 : -1)`. example: 0.9 text_span: type: string description: The excerpt of the response that supports the observation. model: type: string description: AI model that generated the response, as on /api/v1/responses. example: chatgpt created_at: type: string format: date-time description: ISO 8601 timestamp in UTC, to the second. example: '2026-09-14T08:21:05Z' required: - observation_id - response_id - entity_id - entity_name - is_website - attribute_id - attribute_name - positive - score - text_span - model - created_at Error: type: object description: Error response object required: - error properties: error: type: string description: Error message describing what went wrong example: Unauthorized ApiFiltersNoCompetitors: type: object description: >- 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. required: - start_date properties: schedule_id: $ref: '#/components/schemas/PromptScheduleSelection' start_date: type: string format: date-time description: Filter start date (UTC) example: '2024-01-01T00:00:00.000Z' end_date: type: string format: date-time description: Filter end date (UTC) example: '2024-12-31T23:59:59.999Z' models: type: array description: Filter by AI models items: type: string enum: - chatgpt - perplexity - gemini - google_ai_overview - copilot - claude - ai_mode - grok - deepseek - meta_ai - mistral example: - chatgpt - perplexity prompt_ids: type: array description: Filter by specific prompt IDs items: type: string format: uuid location_ids: type: array description: >- Filter by location IDs. Pass this in the JSON body as `filters.location_ids`, even when filtering by a single location. Use IDs returned by `GET /api/v1/locations`. items: type: string format: uuid example: - 123e4567-e89b-12d3-a456-426614174111 prompt_status: type: string enum: - active - paused description: Filter by prompt status prompt_type: type: string enum: - branded - non_branded description: Filter by prompt type additionalProperties: false PromptScheduleSelection: description: >- Select one streaming schedule. Use the selection returned by GET /api/v1/prompt-schedules. Default includes all pre-cutover history and ad hoc runs; archived schedules retain results. The retired manual token is accepted as an alias of default. No All schedules selection. default: default oneOf: - type: string enum: - default - manual - type: string format: uuid securitySchemes: apiKey: type: apiKey in: header name: x-api-key description: >- API key for authentication. You can create one [here](https://app.athenahq.ai/organization?tab=api). ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.