Know which document or source gets most hits via API

There are few ways to get this information:

1. If by “hits” you mean documents that were cited in answers: Yes, you can compute this today via the Conversations API. Each assistant message includes a citations array of IDs; aggregate those per document to find most‑cited vs never‑cited (orphans).
2. If by “hits” you mean end‑user clicks on citation links: There isn’t a public API endpoint for citation click events. The official “Reports & Analytics” endpoints cover traffic, queries, and conversations—but not per‑citation click metrics, so you’d need to instrument clicks yourself on the frontend (see Workarounds below).

What the API gives you

1. Messages (with citations):
   1. Retrieve messages in a conversation. The response includes messages.data[] items (type PromptHistory ) and, crucially, an integer array citations for each assistant message. That’s your signal that “this message used these document(s).”
2. Resolve a citation → document metadata (URL/title):
   1. For each ID in citations, call Get Citation to receive PageMetadata { id, url, title, … }.
   2. List all documents in the agent (to find orphans):
      1. Call List Pages; this returns every page (Page) the agent has indexed. Comparing this full set to your “ever‑cited” set yields the orphaned docs.
3. (Optional) Segmentation by channel/source:
   1. Each message includes metadata such as request_source (e.g., web, api, sdk, etc.), which you can use to break out “hits” by channel.

Note on built‑in analytics: The Reports API covers overall traffic, queries, conversations, and graph‑ready time series—handy for totals and trends—but it does not expose doc‑level citation counts.