---
title: "Query Responses"
method: POST
path: "/api/v1/responses"
tags: ["Basics"]
---

# Query Responses

`POST /api/v1/responses`

Returns paginated AI model responses for a website with optional filtering by date range, models, prompts, and competitors.

## Request body

- ResponsesRequest — Request body for querying responses
  - `website_id` string, uuid, required — The ID of the website to query responses 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
  - `page_num` integer — Page number for pagination (0-indexed)
  - `page_size` integer — Number of responses per page

## Response `200`

Successful response with list of responses

- object
  - `responses` Response[], required
    - `id` string, uuid, required — Unique identifier for the response
    - `website_id` string, uuid, required — Associated website ID
    - `prompt_id` string, uuid, required — Associated prompt ID
    - `base_prompt` string, required — Original prompt text
    - `prompt` string, required — Actual prompt variation used
    - `model` string, required — AI model that generated the response
    - `response` string, required — The AI-generated response text
    - `mentioned` boolean, required — Whether your website was mentioned in the response
    - `position` integer, nullable — Your website's rank/position in the response (null if not mentioned)
    - `cited` boolean, required — Whether your website was cited as a source
    - `created_at` string, date-time, required — Timestamp when the response was captured (UTC)
    - `sources` Source[], required — Sources cited in the response
      - `url` string, required — The source URL
      - `normalized_url` string, nullable — Normalized version of the URL
      - `root_domain` string, required — Root domain of the source
      - `suffix` string, nullable — Domain suffix
    - `competitors` ResponseCompetitor[], required — Competitors mentioned in the response
      - `id` string, uuid, required — Competitor ID
      - `name` string, required — Competitor name
      - `url` string, required — Competitor URL
      - `position` integer, required — Position/rank of competitor mention in the response

## Other responses

- `400` — Bad request - Invalid parameters
- `401` — Unauthorized - Invalid or missing API key
- `403` — Forbidden - You don't have access to this website, prompts, or competitors
- `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/versions/6c5d71622cb9/schema)