---
title: "List Sources (by root domain)"
method: POST
path: "/api/v1/sources"
tags: ["Sources"]
---

# List Sources (by root domain)

`POST /api/v1/sources`

Returns the top cited sources for a website, grouped by root domain. Each row carries citation, mention, brand-mention, and impression metrics for the requested date range, plus a `default_source_type` classification (`owned` / `competitor` / `partner` / `third_party`).

Companion to [POST /api/v1/source-pages](/api-reference/sources/list-source-pages), which returns the same data grouped per URL (one row per cited page) instead of per root domain.

## Request body

- SourcesListRequest — Request body for listing domain-grouped sources.
  - `website_id` string, uuid, required — The website to list sources 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 — Zero-indexed page number.
  - `page_size` integer — Number of rows per page (1–100).
  - `sort_field` 'citation_percentage' | 'mention_percentage' | 'competitor_mention_percentage' | 'brand_mention_percentage' | 'estimated_impressions' | 'total_mentions' | 'domain_count' | 'mentions_count' | 'root_domain' | 'response_count' | 'first_seen' — Column to sort by.
  - `sort_direction` 'asc' | 'desc'
  - `search` string, nullable — Substring filter on `normalized_root_domain`. Protocol (`https://`), `www.`, path, query, and fragment are stripped before matching, so a full URL like `https://www.example.com/foo` collapses to `example.com`.
  - `mentioned` 'yes' | 'no' — If `yes`, only count sources where your brand was mentioned in the citing response. If `no`, only count sources where your brand was NOT mentioned. Omit the field to count every cited source.
  - `competitors_mentioned` 'yes' | 'no' — If `yes`, only count sources where your brand was mentioned in the citing response. If `no`, only count sources where your brand was NOT mentioned. Omit the field to count every cited source.

## Response `200`

Successful response with the page of sources.

- SourcesListResponse
  - `sources` SourceItem[], required
    - `root_domain` string, required — The cited root domain (display form).
    - `total_mentions` number, required — Total citations of this domain (one per citing response) in the date range.
    - `response_count` number, required — Distinct AI responses citing this domain.
    - `estimated_impressions` number, required — Estimated impressions attributable to this domain across the date range.
    - `domain_count` number, required — Distinct subdomain count rolled up under this root domain.
    - `mention_percentage` number, required — Citations of this domain as a percentage of all matching responses.
    - `citation_percentage` number, required — Same numerator as `mention_percentage`. Kept for backward compatibility with the existing dashboard wire shape.
    - `competitor_mention_percentage` number, required — Of the responses citing this domain, the percentage that also mention a tracked competitor.
    - `brand_mention_percentage` number, required — Of the responses citing this domain, the percentage that mention the website's brand.
    - `mentions_count` number, required — Per-URL rollup: count of cited URLs on this domain where the brand was mentioned.
    - `responses_mentioned_count` number, required — Count of citing responses where the brand was mentioned.
    - `competitor_ids` string[], required — Tracked competitors mentioned in responses that cite this domain.
    - `default_source_type` 'owned' | 'competitor' | 'partner' | 'third_party', required — How the source row is classified relative to the website. `owned` covers the website's own domains (including configured url-pattern owned domains). `competitor` matches tracked competitor root domains. `partner` matches configured affiliate domains. `third_party` is the residual bucket (Wikipedia, news, etc.). Per-website source-type overrides can promote/demote individual domains or URLs.
    - `source_type_ids` string[], required — Custom source-type tag UUIDs attached to this domain (in addition to `default_source_type`).
    - `first_seen` string, required — Earliest citation date for this domain in the date range.
  - `pagination` SourcesPagination, required — Pagination metadata. Unlike `Pagination` (which uses `has_more` lookahead), the sources surfaces expose a precise `total` count — the underlying ClickHouse query computes it as a window function in the same scan, so there's no extra round-trip cost.
    - `page_num` integer, required — Zero-indexed page number returned.
    - `page_size` integer, required — Maximum items per page.
    - `total` integer, required — Total number of rows matching the filters (across all pages).

## Other responses

- `400` — Bad request — invalid parameters.
- `401` — Unauthorized — invalid or missing API key.
- `403` — Forbidden — you don't have access to this website, or a sub-resource ID (`prompt_ids`, `competitor_ids`, `location_ids`) belongs to another 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)