---
title: "Cumulative Attribute Metrics"
method: POST
path: "/api/v1/attributes/cumulative"
tags: ["Attributes"]
---

# Cumulative Attribute Metrics

`POST /api/v1/attributes/cumulative`

Returns, for each brand-perception attribute, how many AI responses mentioned it across the date range, and the percentage. `total_responses` is the denominator: responses in the date range that mention the brand AND had attribute extraction run on them. It is NOT every response for the website — responses that never mention the brand are excluded, and Athena samples which responses get extraction, so un-analyzed ones are excluded too. Compute rates from the returned `percentage` / `total_responses` rather than against a response count from another endpoint. Attributes nobody mentioned are returned with response_count 0 rather than omitted. `positive` describes the keyword itself, not the individual mention.

## Request body

- CumulativeAttributeMetricsRequest
  - `website_id` string, uuid, required
  - `filters` ApiFiltersNoCompetitors, required — Filter set for the brand cumulative endpoint. Same as the shared filters but without competitor_ids: this endpoint is brand-only. Sending competitor_ids is rejected — use /api/v1/attributes/competitors for per-competitor data.
    - `start_date` string, date-time, required — Filter start date (UTC)
    - `end_date` string, date-time — Filter end date (UTC)
    - `models` string[] — Filter by AI models
    - `prompt_ids` string[] — Filter by specific prompt IDs
    - `location_ids` string[] — 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`.
    - `prompt_status` 'active' | 'paused' — Filter by prompt status
    - `prompt_type` 'branded' | 'non_branded' — Filter by prompt type

## Response `200`

Successful response with attribute metrics

- object
  - `data` AttributeMetric[], required
    - `attribute_id` string, uuid, required
    - `attribute_name` string, required
    - `positive` boolean, required
    - `response_count` integer, required — Number of analyzed responses that mention this attribute.
    - `total_responses` integer, required — Analyzed responses in the date range — the denominator.
    - `percentage` number, required — response_count / total_responses, as a percentage.

## Other responses

- `400` — Bad request - Invalid parameters
- `401` — Unauthorized - Invalid or missing API key
- `403` — Forbidden - API key cannot access this website
- `404` — Not found - Website or attribute does not exist

---

[API](https://skmtc.net/athenahq/apis/athenahq-api.md) · [All operations](https://skmtc.net/athenahq/apis/athenahq-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/athenahq/athenahq-api/revisions/6c5d71622cb9/schema)