List Sources (by root domain)

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, which returns the same data grouped per URL (one row per cited page) instead of per root domain. Ownership and source tags use the centralized URL-pattern rules. Domain summaries consider whole-host rules only; path and query rules apply to page-level results. Explicit www hosts remain separate when their matching rules differ from the apex.

POST /api/v1/sources

List Sources (by root domain)

cURL

curl --request POST \
  --url https://api.athenahq.ai/api/v1/sources \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: <api-key>' \
  --data '
{
  "website_id": "123e4567-e89b-12d3-a456-426614174000",
  "filters": {
    "start_date": "2024-01-01T00:00:00.000Z",
    "end_date": "2024-01-31T23:59:59.999Z"
  },
  "page_size": 30,
  "sort_field": "citation_percentage",
  "sort_direction": "desc"
}
'

200

Example

{
  "sources": [
    {
      "root_domain": "wikipedia.org",
      "total_mentions": 124,
      "response_count": 86,
      "estimated_impressions": 18400,
      "domain_count": 31,
      "mention_percentage": 12.3,
      "citation_percentage": 14.1,
      "competitor_mention_percentage": 3.2,
      "brand_mention_percentage": 8.9,
      "mentions_count": 47,
      "responses_mentioned_count": 39,
      "competitor_ids": [],
      "default_source_type": "third_party",
      "source_type_ids": [],
      "first_seen": "2024-01-04"
    }
  ],
  "pagination": {
    "page_num": 0,
    "page_size": 30,
    "total": 142
  }
}

Authorizations

x-api-key · string · header · required

API key for authentication. You can create one here.

Body

application/json

Request body for listing domain-grouped sources.

website_id · string<uuid> · required

The website to list sources for.

Example:

"123e4567-e89b-12d3-a456-426614174000"

filters · object · required

Filters for querying responses and metrics. Pass location filters in the JSON body as filters.location_ids.

Show child attributes

page_num · integer · default: 0

Zero-indexed page number.

Required range: x >= 0

page_size · integer · default: 30

Number of rows per page (1–100).

Required range: 1 <= x <= 100

sort_field · enum<string> · default: citation_percentage

Column to sort by.

Available options: citation_percentage, mention_percentage, competitor_mention_percentage, brand_mention_percentage, estimated_impressions, total_mentions, domain_count, mentions_count, root_domain, response_count, first_seen

sort_direction · enum<string> · default: desc

Available options: asc, desc

search · string | null

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 · enum<string>

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.

Available options: yes, no

competitors_mentioned · enum<string>

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.

Available options: yes, no

source_tags · (string<uuid> | enum<string>)[]

Source tags to filter by, matching the Source Tag filter in the app. Each value is a tag ID from the source_tags__list MCP tool (built-in tags such as Media or PR Wire, and the website's custom tags), owned, competitor, other (sources the Tags column badges Other: classified outside every built-in category) or untagged (sources with no tag). Omit for all sources.

source_tags_operator · enum<string> · default: is_any_of

How source_tags combine: is_any_of keeps sources carrying any listed tag, is_not_any_of drops them, has_all_of keeps only sources carrying every listed tag.

Available options: is_any_of, is_not_any_of, has_all_of

Response

200

application/json

Successful response with the page of sources.

sources · object[] · required

Show child attributes

pagination · object · 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.

Show child attributes