> ## Documentation Index
> Fetch the complete documentation index at: https://docs.usequotable.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Domains AI answers cite

> Rank the domains AI answers cite most for a brand's prompts, and find where your own site stands.

AI engines cite pages when they answer your prompts. The domains they cite most are the ones shaping the answer. This recipe pages through every cited source for a brand, rolls them up by domain, and prints a leaderboard with your own domain highlighted.

## What you need

| Requirement | Value |
| - | - |
| Scopes | `read:projects`, `read:visibility` |
| Endpoints | `GET /projects/{project_id}`, `GET /projects/{project_id}/citations` |
| Environment | `QUOTABLE_API_KEY`, `QUOTABLE_PROJECT_ID` |
| Requests per run | 1, plus 1 per 100 cited URLs |

## How it works

1. `GET /projects/{project_id}` returns the brand's `domain`, so the script can spot your own pages.
2. `GET /projects/{project_id}/citations?limit=100` returns cited URLs, most cited first. The script follows `next_cursor` until it's `null`.
3. Each URL has `times_cited` (how often answers cited it) and `times_retrieved` (how often an engine's web search retrieved it, cited or not). The script sums both per domain.

## Code

```javascript cited-domains.mjs theme={"system"}
// Node.js 20+. Run: node cited-domains.mjs
const API = "https://app.usequotable.com/api/v1";
const KEY = process.env.QUOTABLE_API_KEY;
const PROJECT_ID = process.env.QUOTABLE_PROJECT_ID;
const TOP = 15;

async function get(path) {
  for (let attempt = 0; ; attempt++) {
    const res = await fetch(`${API}${path}`, {
      headers: { Authorization: `Bearer ${KEY}` },
    });
    if (res.status === 429 && attempt < 3) {
      const wait = Number(res.headers.get("retry-after") ?? "1");
      await new Promise((r) => setTimeout(r, wait * 1000));
      continue;
    }
    if (!res.ok) throw new Error(`${res.status} ${await res.text()}`);
    return res.json();
  }
}

async function* paginate(path) {
  let cursor = null;
  do {
    const sep = path.includes("?") ? "&" : "?";
    const page = await get(`${path}${sep}limit=100${cursor ? `&cursor=${encodeURIComponent(cursor)}` : ""}`);
    yield* page.data;
    cursor = page.next_cursor;
  } while (cursor);
}

const bare = (domain) => domain.toLowerCase().replace(/^www\./, "");

const brand = await get(`/projects/${PROJECT_ID}`);
const ownDomain = bare(brand.domain);
const isOwn = (domain) => domain === ownDomain || domain.endsWith(`.${ownDomain}`);

const byDomain = new Map();
let urls = 0;
for await (const source of paginate(`/projects/${PROJECT_ID}/citations`)) {
  urls++;
  const domain = bare(source.domain);
  const row = byDomain.get(domain) ?? { domain, urls: 0, cited: 0, retrieved: 0 };
  row.urls += 1;
  row.cited += source.times_cited;
  row.retrieved += source.times_retrieved;
  byDomain.set(domain, row);
}

const ranked = [...byDomain.values()].sort((a, b) => b.cited - a.cited || b.retrieved - a.retrieved);
const totalCited = ranked.reduce((sum, r) => sum + r.cited, 0);

console.log(`${brand.name}: ${urls} cited URLs across ${ranked.length} domains\n`);
console.log("Rank  Domain                         URLs   Cited  Share  Retrieved");
ranked.slice(0, TOP).forEach((r, i) => {
  const share = totalCited ? ((r.cited / totalCited) * 100).toFixed(1) + "%" : "-";
  const mark = isOwn(r.domain) ? " ← you" : "";
  console.log(
    `${String(i + 1).padStart(4)}  ${r.domain.padEnd(30)} ${String(r.urls).padStart(4)}  ${String(r.cited).padStart(6)}  ${share.padStart(5)}  ${String(r.retrieved).padStart(9)}${mark}`,
  );
});

const ownRank = ranked.findIndex((r) => isOwn(r.domain));
console.log(
  ownRank === -1
    ? `\n${ownDomain} isn't cited yet.`
    : `\n${ownDomain} ranks #${ownRank + 1} of ${ranked.length} domains.`,
);
```

```python cited_domains.py theme={"system"}
# Python 3.10+, pip install requests. Run: python cited_domains.py
import os
import time

import requests

API = "https://app.usequotable.com/api/v1"
PROJECT_ID = os.environ["QUOTABLE_PROJECT_ID"]
TOP = 15

session = requests.Session()
session.headers["Authorization"] = f"Bearer {os.environ['QUOTABLE_API_KEY']}"

def get(path, params=None):
    for attempt in range(4):
        res = session.get(f"{API}{path}", params=params, timeout=30)
        if res.status_code == 429 and attempt < 3:
            time.sleep(int(res.headers.get("Retry-After", "1")))
            continue
        res.raise_for_status()
        return res.json()

def paginate(path, **params):
    cursor = None
    while True:
        page = get(path, {**params, "limit": 100, **({"cursor": cursor} if cursor else {})})
        yield from page["data"]
        cursor = page["next_cursor"]
        if not cursor:
            return

def bare(domain):
    domain = domain.lower()
    return domain[4:] if domain.startswith("www.") else domain

brand = get(f"/projects/{PROJECT_ID}")
own_domain = bare(brand["domain"])
is_own = lambda d: d == own_domain or d.endswith("." + own_domain)

by_domain = {}
urls = 0
for source in paginate(f"/projects/{PROJECT_ID}/citations"):
    urls += 1
    domain = bare(source["domain"])
    row = by_domain.setdefault(domain, {"domain": domain, "urls": 0, "cited": 0, "retrieved": 0})
    row["urls"] += 1
    row["cited"] += source["times_cited"]
    row["retrieved"] += source["times_retrieved"]

ranked = sorted(by_domain.values(), key=lambda r: (-r["cited"], -r["retrieved"]))
total_cited = sum(r["cited"] for r in ranked)

print(f"{brand['name']}: {urls} cited URLs across {len(ranked)} domains\n")
print("Rank  Domain                         URLs   Cited  Share  Retrieved")
for i, r in enumerate(ranked[:TOP], start=1):
    share = f"{r['cited'] / total_cited * 100:.1f}%" if total_cited else "-"
    mark = " ← you" if is_own(r["domain"]) else ""
    print(f"{i:>4}  {r['domain']:<30} {r['urls']:>4}  {r['cited']:>6}  {share:>5}  {r['retrieved']:>9}{mark}")

own_rank = next((i for i, r in enumerate(ranked, start=1) if is_own(r["domain"])), None)
print(f"\n{own_domain} isn't cited yet." if own_rank is None
      else f"\n{own_domain} ranks #{own_rank} of {len(ranked)} domains.")
```

## Expected output

```text theme={"system"}
Acme Analytics: 236 cited URLs across 16 domains

Rank  Domain                         URLs   Cited  Share  Retrieved
   1  g2.com                           38     412  18.4%        769
   2  en.wikipedia.org                 21     377  16.9%        822
   3  reddit.com                       44     301  13.5%        721
   4  capterra.com                     19     198   8.9%        405
   5  acme.com                         12     173   7.7%        413 ← you
   6  gartner.com                       9     141   6.3%        248
   7  blog.globex.io                   15     128   5.7%        299
   8  forbes.com                       11      96   4.3%        241
   9  youtube.com                      17      88   3.9%        167
  10  initech.com                       8      77   3.4%        149
  11  trustradius.com                  10      64   2.9%        163
  12  medium.com                       14      52   2.3%        118
  13  techradar.com                     6      47   2.1%        111
  14  zapier.com                        5      39   1.7%         85
  15  docs.acme.com                     4      31   1.4%         71 ← you

acme.com ranks #5 of 16 domains.
```

## Read the results

* **Share** is the domain's portion of all citations for this brand's prompts. A few domains with a large share are where you should aim to be cited, through PR, reviews or partnerships.
* **Retrieved much higher than cited** means engines find that domain's pages but rarely use them in answers. Compare their content with the pages that do get cited.
* **Your own rank** is the quickest health check for content work. Track it over time by saving each run's output.

## Variations

> [accordion] Only one domain's pages
>
> Pass `domain=` to filter server-side, for example `GET /projects/{project_id}/citations?domain=acme.com`. The filter is a case-insensitive substring match, so it also matches subdomains such as `blog.acme.com`.

> [accordion] Your most cited pages
>
> Filter with `domain=` set to your own domain and print each `url` with its `times_cited`. These are the pages AI engines already trust.

> [accordion] Recently active sources
>
> Each source has `first_seen` and `last_seen`. Keep only sources with a `last_seen` in the last 30 days to see who is cited now, not historically.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.