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

# Cumulative Position

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

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` 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 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

---

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