---
title: "Cumulative Position"
method: POST
path: "/api/v1/metrics/position/cumulative"
tags: ["Metrics"]
---

# Cumulative Position

`POST /api/v1/metrics/position/cumulative`

## Request

- Base URL: `https://api.athenahq.ai`
- URL: `https://api.athenahq.ai/api/v1/metrics/position/cumulative`
- Auth: API key in header `x-api-key`

Returns average position/ranking across the specified date range. Shows where your brand and competitors typically appear in AI responses.

## Request body

- PositionRequest: Request body for position endpoints
  - `website_id` string, uuid, required: The ID of the website to query position metrics for
  - `filters` MetricsApiFilters, required: Filters for the metrics endpoints: the shared response filters plus an optional saved view.
    - `schedule_id` union: 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. This field takes one schedule; a list returns 400.
      - 'default' | 'manual'
      - string, uuid
    - `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
    - `saved_view_id` string, uuid: A saved view to apply, from `GET /api/v1/saved-views`. Its filters apply the way the dashboard applies them, including the dashboard's defaults of active prompts and every model. Any filter you also send replaces the view's value for that field. The view's saved date range is ignored: `start_date` and `end_date` decide the window. Returns `404` when the view is not on `website_id`, and `400` naming any view filter the API cannot apply, which you can replace by sending that filter explicitly.

## Response `200`

Successful response with position data

- object
  - `data` object, required

## Other responses

- `400`: Bad request - Invalid parameters
- `401`: Unauthorized - Invalid or missing API key
- `403`: Forbidden - You don't have access to this website
- `404`: Website not found
- `500`: Internal server error

## Changes

- **2026-11-03** `2d1d86d5e067`: 2 breaking, 8 warning
  - added `#/components/schemas/ApiFilters, subschema #2` to the `filters` request property `allOf` list
  - the `filters` request property type changed from `object` to no type
  - removed the request property `filters/competitor_ids`
  - removed the request property `filters/end_date`
  - …6 more

[Operation history](https://skmtc.dev/athenahq/apis/athenahq-api/changes/api/v1/metrics/position/cumulative/post.md)

---

[API](https://skmtc.dev/athenahq/apis/athenahq-api.md) - [All operations](https://skmtc.dev/athenahq/apis/athenahq-api/llms.txt) - [OpenAPI document](https://skmtc.dev/athenahq/apis/athenahq-api/revisions/6cf9ca58edf6?raw)