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

# Citation Rank by domain (with deltas)

> Build the Citation Rank leaderboard — domains sorted by share, with the per-row pp change vs the previous period.

The "Citation Rank" / "Citation Share by Domain" panel in the Profound app
is the citations endpoint grouped by `root_domain`, sorted by
`citation_share` descending, with each row showing the change in share
vs the previous window. Two calls (current + prior), merge by domain,
diff the shares.

## How this example works

1. **`dimensions: ["root_domain"]`** — one row per cited domain in each
   call. Run both the current and prior windows.
2. **Merge by domain.** For each current-window row, look up the
   previous-window share (default 0 if missing) and diff.
3. **Sort by current `citation_share` descending** to match the UI.

<Note>
  **`count` and `citation_share` measure different things.** `count` is the
  raw number of citations to that domain in the window. `citation_share`
  is `count / total_citations` **per AI model, then averaged across
  models**. A domain cited heavily on a low-volume model (e.g. Perplexity)
  can have a higher share than a domain with more total citations spread
  across high-volume models — the two columns won't sort in lockstep.
  Pick the one that matches the question you're answering and sort on it.
</Note>

<RequestExample>
  ```python Python theme={null}
  import os
  from datetime import date, timedelta
  from profound import Profound

  client = Profound(api_key=os.environ["PROFOUND_API_KEY"])

  # What to fetch — replace with your own values.
  CATEGORY_NAME = "<your-category-name>"
  DAYS          = 7
  INCLUSIVE_END = date(2026, 5, 11)    # the last day of your current window
  TOP_N         = 10


  def get_domain_shares(category_id, start, end):
      """Return {domain: share} for every cited domain in the window."""
      res = client.reports.citations(
          category_id=category_id,
          start_date=start.isoformat(),
          end_date=end.isoformat(),
          metrics=["count", "citation_share"],
          dimensions=["root_domain"],
          filters=[{"field": "prompt_type", "operator": "is", "value": "visibility"}],
          pagination={"limit": 50000, "offset": 0},
      )
      m = res.info.query["metrics"]
      d = res.info.query["dimensions"]
      i_count  = m.index("count")
      i_share  = m.index("citation_share")
      i_domain = d.index("root_domain")
      return {
          row.dimensions[i_domain]: {
              "count": row.metrics[i_count],
              "share": row.metrics[i_share],
          }
          for row in res.data
      }


  def current_and_prior_windows(inclusive_end, days):
      """Two (start, end_exclusive) pairs of equal length, back-to-back."""
      current = (
          inclusive_end - timedelta(days=days - 1),
          inclusive_end + timedelta(days=1),     # +1 day → exclusive end
      )
      prior = (current[0] - timedelta(days=days), current[0])
      return current, prior


  def find_category_id(name):
      """Return the UUID of the category whose name matches (case-insensitive)."""
      for c in client.organizations.categories.list():
          if c.name.lower() == name.lower():
              return c.id
      raise ValueError(f"No category named {name!r}")


  # Resolve name → ID, run current + prior, then build the leaderboard with deltas.
  category_id    = find_category_id(CATEGORY_NAME)
  current, prior = current_and_prior_windows(INCLUSIVE_END, DAYS)

  current_domains = get_domain_shares(category_id, *current)
  prior_domains   = get_domain_shares(category_id, *prior)

  rows = sorted(
      (
          {
              "domain":    name,
              "count":     d["count"],
              "share":     d["share"],
              "delta_pp":  (d["share"] - prior_domains.get(name, {"share": 0})["share"]) * 100,
          }
          for name, d in current_domains.items()
      ),
      key=lambda r: r["share"],
      reverse=True,
  )[:TOP_N]

  for rank, r in enumerate(rows, start=1):
      sign = "+" if r["delta_pp"] >= 0 else "−"
      delta_str = f"{sign}{abs(r['delta_pp']):.1f} pp"
      print(f"{rank:>2}. {r['domain']:<32} {r['share']:>6.1%}  {delta_str}")
  ```

  ```bash curl theme={null}
  export PROFOUND_API_KEY=your_api_key_here

  # Current window
  curl -X POST "https://api.tryprofound.com/v1/reports/citations" \
    -H "X-API-Key: $PROFOUND_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "category_id": "your-category-uuid",
      "start_date": "2026-05-05",
      "end_date": "2026-05-12",
      "metrics": ["count", "citation_share"],
      "dimensions": ["root_domain"],
      "filters": [{"field": "prompt_type", "operator": "is", "value": "visibility"}],
      "pagination": {"limit": 50000, "offset": 0}
    }'

  # Previous window — same body, prior dates. Merge by root_domain client-side
  # to compute the per-row share delta.
  curl -X POST "https://api.tryprofound.com/v1/reports/citations" \
    -H "X-API-Key: $PROFOUND_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "category_id": "your-category-uuid",
      "start_date": "2026-04-28",
      "end_date": "2026-05-05",
      "metrics": ["count", "citation_share"],
      "dimensions": ["root_domain"],
      "filters": [{"field": "prompt_type", "operator": "is", "value": "visibility"}],
      "pagination": {"limit": 50000, "offset": 0}
    }'
  ```
</RequestExample>

## Page-level breakdown

Swap `root_domain` for `url` in `dimensions` to get the top citing **pages**
(one row per URL) instead of the top citing domains.