> ## 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.
# Citations
Which domains and pages AI answers cite, ranked most-cited first. Group by
`page` for URL-level rows; use `scope: "owned"` to see only domains you own.
* **Metrics:** `count` (raw citations), `citation_share` (per-model average share), `rank`, `first_cited_at` (pages only).
* **`group_by`:** `page`, `date`, `model`, `topic`, `region`, `persona`, `prompt`.
* **No `sort`:** rows are always ranked most-cited first.
* **Citation-layer filters:** `domain` (subdomain-aware), `page`, `analysis_type` (`visibility`·`sentiment`·`factcheck`·`all`), `citation_category` (`owned`·`competition`·`social`·`earned_media`·`earned_institutions`·`pr_wire`·`other`·custom), `citation_tag` (your custom tags — list them with [Get Citation Tags](/api-reference/organization/get-category-citation-tags)).
`citation_category` and `citation_tag` are both top-level `and` leaves
accepting `is` / `in`; values in one `in` are OR'd, so
`{"field": "citation_tag", "op": "in", "value": ["Editorial", "Docs"]}`
matches URLs carrying either tag.
`count` and `citation_share` measure different things: `citation_share` is
averaged per AI model, so it won't sort in lockstep with raw `count`.
New to the v2 reports? See [Filtering & concepts](/rest-api/reports/reports-v2-overview) for the shared request shape, filter tree, grouping, and pagination.
`POST /v2/reports/citations/stream` takes the **same request body** and
returns [Server-Sent Events](https://developer.mozilla.org/docs/Web/API/Server-sent_events):
one `summary` event (the `info` block), then one `result` event per row.
`limit`/`cursor` are ignored; it returns everything by default. Pass
`max_results` to cap.
```text Response (text/event-stream) theme={null}
event: summary
data: { ...the info block... }
event: result ← one per row, same shape as data[] above
data: {"domain": "reddit.com", "rank": 1, "count": 13940, "citation_share": 0.040}
```
```bash cURL theme={null}
curl -X POST https://api.tryprofound.com/v2/reports/citations \
-H "X-API-Key: " \
-H "Content-Type: application/json" \
-d '{
"category_id": "182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e",
"start_date": "2026-06-09",
"end_date": "2026-06-15"
}'
```
```bash cURL (filter by citation tag) theme={null}
curl -X POST https://api.tryprofound.com/v2/reports/citations \
-H "X-API-Key: " \
-H "Content-Type: application/json" \
-d '{
"category_id": "182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e",
"start_date": "2026-06-09",
"end_date": "2026-06-15",
"filter": {
"field": "citation_tag",
"op": "in",
"value": ["Editorial", "Docs"]
}
}'
```
```json 200 theme={null}
{
"info": {
"total_results": 11662,
"count": 10,
"next_cursor": "Z0FBQUFBQnFQcWdrbDRiSHpGaktVNm5N...",
"scope": "all",
"models": ["ChatGPT", "Google Gemini", "Perplexity", "Claude", "..."],
"metrics": ["count", "citation_share", "rank"],
"analysis_types": ["visibility"],
"start_date": "2026-06-09",
"end_date": "2026-06-15",
"filter": null
},
"data": [
{ "domain": "reddit.com", "rank": 1, "count": 13940, "citation_share": 0.040 },
{ "domain": "youtube.com", "rank": 2, "count": 16287, "citation_share": 0.037 },
{ "domain": "tryprofound.com", "rank": 3, "count": 10414, "citation_share": 0.029 }
// ...7 more rows in this page (count: 10, total_results: 11662); paginate with next_cursor
]
}
```
## OpenAPI
````yaml POST /v2/reports/citations
openapi: 3.1.0
info:
title: External API
version: c2f5e9726bee64ff80842cf9fe8002df9c276c0a
servers:
- url: https://api.tryprofound.com
description: Production Server
security: []
paths:
/v2/reports/citations:
post:
tags:
- Reports
- Reports
summary: Query Citations V2
operationId: query_citations_v2_v2_reports_citations_post
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/CitationsV2Query'
required: true
responses:
'200':
description: Successful Response
content:
application/json:
schema:
$ref: '#/components/schemas/CitationsV2Response'
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
security:
- APIKeyHeader: []
- BearerAuth: []
x-codeSamples:
- lang: JavaScript
source: |-
import Profound from '@profoundai/client';
const client = new Profound({
apiKey: process.env['PROFOUND_API_KEY'], // This is the default and can be omitted
});
const response = await client.reports.queryCitations({
category_id: '182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e',
end_date: 'end_date',
start_date: 'start_date',
});
console.log(response.data);
- lang: Python
source: |-
import os
from profound import Profound
client = Profound(
api_key=os.environ.get("PROFOUND_API_KEY"), # This is the default and can be omitted
)
response = client.reports.query_citations(
category_id="182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e",
end_date="end_date",
start_date="start_date",
)
print(response.data)
components:
schemas:
CitationsV2Query:
properties:
category_id:
type: string
format: uuid
title: Category Id
start_date:
type: string
title: Start Date
description: YYYY-MM-DD, ET, inclusive
end_date:
type: string
title: End Date
description: YYYY-MM-DD, ET, inclusive
entity:
type: string
enum:
- domain
- page
- citation_category
title: Entity
description: >-
What each row represents: `domain` (default), `page`, or
`citation_category`. Legacy: `group_by: ["page"]` (with `entity`
omitted) is still accepted and is equivalent to `entity: "page"`.
`citation_category` uses the dashboard split view: a citation counts
under both its page-level and domain-level category, so category
shares can sum to more than 100%.
default: domain
group_by:
items:
type: string
enum:
- page
- date
- model
- topic
- region
- persona
- prompt
type: array
title: Group By
metrics:
anyOf:
- items:
type: string
enum:
- count
- citation_share
- rank
- first_cited_at
type: array
- type: 'null'
title: Metrics
interval:
type: string
enum:
- day
- week
- month
title: Interval
default: day
scope:
type: string
enum:
- all
- owned
title: Scope
description: >-
`all` (every cited domain) or `owned` (only your owned domains).
Applies to `entity=domain`.
default: all
filter:
anyOf:
- $ref: '#/components/schemas/FilterNode'
- type: 'null'
description: >-
`citation_category` filters on a cited URL's single category;
`citation_tag` filters on the custom citation tags a URL carries (a
URL can carry several). List the category's tags with `GET
/v1/org/categories/{category_id}/citation-tags`.
limit:
anyOf:
- type: integer
maximum: 50
exclusiveMinimum: 0
- type: 'null'
title: Limit
description: Page size; default 10, max 50.
max_results:
anyOf:
- type: integer
exclusiveMinimum: 0
- type: 'null'
title: Max Results
description: >-
Stream endpoint only: cap the number of streamed rows (default:
all).
cursor:
anyOf:
- type: string
- type: 'null'
title: Cursor
additionalProperties: false
type: object
required:
- category_id
- start_date
- end_date
title: CitationsV2Query
CitationsV2Response:
properties:
info:
$ref: '#/components/schemas/CitationsV2Info'
data:
items:
$ref: '#/components/schemas/CitationRow'
type: array
title: Data
type: object
required:
- info
- data
title: CitationsV2Response
HTTPValidationError:
properties:
detail:
items:
$ref: '#/components/schemas/ValidationError'
type: array
title: Detail
type: object
title: HTTPValidationError
FilterNode:
properties:
and:
anyOf:
- items:
$ref: '#/components/schemas/FilterNode'
type: array
- type: 'null'
title: And
or:
anyOf:
- items:
$ref: '#/components/schemas/FilterNode'
type: array
- type: 'null'
title: Or
not:
anyOf:
- $ref: '#/components/schemas/FilterNode'
- type: 'null'
field:
anyOf:
- type: string
- type: 'null'
title: Field
op:
anyOf:
- type: string
- type: 'null'
title: Op
value:
title: Value
additionalProperties: false
type: object
title: FilterNode
description: A leaf (`field`/`op`/`value`) or an `and`/`or`/`not` group.
CitationsV2Info:
properties:
total_results:
anyOf:
- type: integer
- type: 'null'
title: Total Results
description: >-
Total rows matching the query before pagination (null when not
computed).
count:
type: integer
title: Count
description: Number of rows returned in `data` for this page.
next_cursor:
anyOf:
- type: string
- type: 'null'
title: Next Cursor
description: Opaque cursor for the next page; null on the last page.
models:
items:
type: string
type: array
title: Models
description: Display names of the models the report covers.
start_date:
type: string
title: Start Date
description: Echoed request start date (YYYY-MM-DD, ET).
end_date:
type: string
title: End Date
description: Echoed request end date (YYYY-MM-DD, ET).
filter:
anyOf:
- additionalProperties: true
type: object
- type: 'null'
title: Filter
description: Echoed normalized filter tree, or null when no filter was sent.
scope:
type: string
title: Scope
description: 'Citation scope: `all` or `owned`.'
metrics:
items:
type: string
type: array
title: Metrics
description: Metrics returned per row.
analysis_types:
items:
type: string
type: array
title: Analysis Types
description: Analysis types the citations were drawn from.
additionalProperties: true
type: object
required:
- count
- models
- start_date
- end_date
- scope
- metrics
- analysis_types
title: CitationsV2Info
CitationRow:
properties:
domain:
anyOf:
- type: string
- type: 'null'
title: Domain
page:
anyOf:
- type: string
- type: 'null'
title: Page
rank:
anyOf:
- type: integer
- type: 'null'
title: Rank
date:
anyOf:
- type: string
- type: 'null'
title: Date
model:
anyOf:
- $ref: '#/components/schemas/DimensionRef'
- type: 'null'
topic:
anyOf:
- $ref: '#/components/schemas/DimensionRef'
- type: 'null'
region:
anyOf:
- $ref: '#/components/schemas/DimensionRef'
- type: 'null'
persona:
anyOf:
- $ref: '#/components/schemas/DimensionRef'
- type: 'null'
prompt:
anyOf:
- $ref: '#/components/schemas/DimensionRef'
- type: 'null'
count:
anyOf:
- type: integer
- type: 'null'
title: Count
citation_share:
anyOf:
- type: number
- type: 'null'
title: Citation Share
first_cited_at:
anyOf:
- type: string
- type: 'null'
title: First Cited At
description: Pages only.
additionalProperties: true
type: object
title: CitationRow
description: >-
One (source x group) row. Each row carries `domain` or `page`; group
dims/metrics vary.
ValidationError:
properties:
loc:
items:
anyOf:
- type: string
- type: integer
type: array
title: Location
msg:
type: string
title: Message
type:
type: string
title: Error Type
input:
title: Input
ctx:
type: object
title: Context
type: object
required:
- loc
- msg
- type
title: ValidationError
DimensionRef:
properties:
id:
anyOf:
- type: string
- type: 'null'
title: Id
name:
anyOf:
- type: string
- type: 'null'
title: Name
type: object
title: DimensionRef
description: An ``{id, name}`` reference for a grouped dimension value.
securitySchemes:
APIKeyHeader:
type: apiKey
in: header
name: X-API-Key
BearerAuth:
type: http
scheme: bearer
````