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

# Competitor Attribute Metrics

`POST /api/v1/attributes/competitors`

Returns attribute metrics per tracked competitor: for each competitor and each attribute, how many AI responses mentioned that keyword for that competitor. Pair with POST /api/v1/attributes/cumulative to compare the brand against competitors. `total_responses` is per-competitor: responses in the date range that mention THAT competitor and had attribute extraction run on them. Each competitor therefore has its own denominator, and none of them is the website's total response count. `positive` describes the keyword itself, not the individual mention. Returns one row per competitor per attribute, so responses can be large — narrow with filters.competitor_ids. Competitors with no responses in the date range are omitted entirely rather than returned with zeros.

## Request body

- AttributeMetricsRequest
  - `website_id` string, uuid, required
  - `filters` ApiFilters, required — Filters for querying responses and metrics. Pass location filters in the JSON body as `filters.location_ids`.
    - `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
    - `competitor_ids` string[] — Filter by specific competitor 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 per-competitor attribute metrics

- object
  - `data` CompetitorAttributeMetric[], required
    - `competitor_id` string, uuid, required
    - `competitor_name` string, required
    - `attribute_id` string, uuid, required
    - `attribute_name` string, required
    - `positive` boolean, required
    - `response_count` integer, required
    - `total_responses` integer, required — Analyzed responses for THIS competitor — each competitor has its own denominator.
    - `percentage` number, required

## 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)