GET /v1/citations/{citation_id}

Retrieve a citation

scope read:citations cost 1 RU idempotent required

Fetch a single citation by id, including domain metadata, Rank Prompt score, and the report context where it was discovered.

Cross-brand requests return 404 not_found (instead of 403) to avoid leaking citation existence across tenants.

Path parameters

citation_idstring required
Citation id (UUID).

Header parameters

Idempotency-Keystring optional

Responses

Returned a citationapplication/json

Type:Citation

brand_idstringrequired
Owning brand id (UUID).
created_atstringrequired
When the citation was first ingested.

format: `date-time`
idstringrequired
Citation id (UUID).
updated_atstringrequired
When the citation row was last updated.

format: `date-time`
urlstringrequired
Normalised page URL. Unique per (brand_id, citation_url).
ai_overviews_countinteger
Times this URL appeared in Google AI Overviews.

min: 0 · default: `0`
backlink_anchor_textstring (nullable)nullable
Anchor text of the backlink, when present.
backlink_is_nofollowboolean (nullable)nullable
backlink_is_sponsoredboolean (nullable)nullable
backlink_is_ugcboolean (nullable)nullable
brand_mention_sentimentenum (nullable)nullable
Polarity of the brand mention. Pinned to the DB CHECK constraint valid_brand_mention_sentiment: positive, neutral, negative, or null when no mention was found.
brand_mentionedboolean (nullable)nullable
True when the analyzer found a textual brand mention.
categorization_statusstring (nullable)nullable
Categorizer pipeline state. null = uncategorized (not yet queued), pending = in flight, completed = analyzer wrote results, failed = analyzer raised.
categorized_atstring (nullable)nullable
When the categorizer last finished.

format: `date-time`
chatgpt_countinteger
Times this URL was cited by ChatGPT for the brand.

min: 0 · default: `0`
domainstring (nullable)nullable
Bare domain extracted from url (e.g. example.com).
domain_authorityinteger (nullable)nullable
Moz domain authority (0-100).
domain_categoryenum (nullable)nullable
Coarse domain category emitted by the citation categorizer (see prompts/10-categorize-citations.md).OWNED (page hosted on a brand-owned domain), EDITORIAL_MEDIA, SOCIAL_UGC, REVIEW_DIRECTORY, DIRECTORY_MARKETPLACE, INSTITUTIONAL, REFERENCE, REFERENCE_DOCS, MARKETPLACE, OTHER, or null while uncategorized.
external_linksinteger (nullable)nullable
Total outbound links from the page to external domains (Moz metric).
has_backlinkboolean (nullable)nullable
True when the page links back to a brand-owned domain.
is_actionableboolean (nullable)nullable
True when the page is worth pursuing for outreach.
linking_root_domainsinteger (nullable)nullable
Unique root domains linking to the page.
mention_prominenceenum (nullable)nullable
Where on the page the brand mention appears. Pinned to the DB CHECK constraint valid_mention_prominence: headline, body, sidebar, footnote, comparison, or null when no mention was found.
objectstring
Always citation.

default: `citation`
page_authorityinteger (nullable)nullable
Moz page authority (0-100).
page_categoryenum (nullable)nullable
Coarse page category emitted by the citation categorizer (see prompts/10-categorize-citations.md).HOMEPAGE, PRODUCT_PAGE, ARTICLE, GUIDE_HOWTO, GUIDE_TUTORIAL, LISTICLE_COMPARISON, REVIEW_ROUNDUP, NEWS_ARTICLE, BLOG_POST, DIRECTORY_LISTING, DOCS_SUPPORT, DOCUMENTATION, OTHER, or null while uncategorized.
page_summarystring (nullable)nullable
LLM-generated one-paragraph summary of the page.
page_titlestring (nullable)nullable
<title> of the page.
perplexity_countinteger
Times this URL was cited by Perplexity for the brand.

min: 0 · default: `0`
rankprompt_scoreinteger (nullable)nullable
0-100 outreach opportunity score (higher is better).
report_idsarray of string
Report ids (UUIDs) where this citation appeared.
spam_scoreinteger (nullable)nullable
Moz spam score (0-100; lower is better).

Example response

{
  "ai_overviews_count": 0,
  "backlink_anchor_text": "Acme Coffee",
  "backlink_is_nofollow": false,
  "backlink_is_sponsored": false,
  "backlink_is_ugc": false,
  "brand_id": "3f9c7e8a-1b6a-4d8e-92cf-7d9c8b1e2a04",
  "brand_mention_sentiment": "positive",
  "brand_mentioned": true,
  "categorization_status": "completed",
  "categorized_at": "2026-04-15T10:30:00Z",
  "chatgpt_count": 3,
  "created_at": "2026-04-15T10:00:00Z",
  "domain": "example.com",
  "domain_authority": 72,
  "domain_category": "EDITORIAL_MEDIA",
  "external_links": 92,
  "has_backlink": true,
  "id": "5b9c7e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f",
  "is_actionable": true,
  "linking_root_domains": 1840,
  "mention_prominence": "headline",
  "object": "citation",
  "page_authority": 45,
  "page_category": "LISTICLE_COMPARISON",
  "page_summary": "Roundup of premium drip and pod machines for home use.",
  "page_title": "The 10 best coffee makers of 2026",
  "perplexity_count": 1,
  "rankprompt_score": 78,
  "report_ids": [
    "c4f8b6a2-9a17-4e31-92fa-7d1e3b5c8b2a"
  ],
  "spam_score": 1,
  "updated_at": "2026-04-15T10:30:00Z",
  "url": "https://example.com/best-coffee-makers-2026"
}

Request validation failedapplication/json

Type:ApiError

errorobjectrequired
Show fields
- codestringrequired
  Stable machine-readable error code from the catalog.
- messagestringrequired
  Human-readable description suitable for logging.
- detailsobject
  Optional, code-specific context (e.g. errors array for validation_error, retry_after for service_unavailable). Shape depends on error.code; treat as opaque otherwise.
  
  Show fields
  Empty object (no properties).
request_idstring
Server-generated correlation id for the request. Mirrors the X-Correlation-ID response header. Include this when contacting support.

format: `uuid`

Example response

{
  "error": {
    "code": "validation_error",
    "message": "Request validation failed"
  },
  "request_id": "9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"
}

Missing or invalid credentialsapplication/json

Type:ApiError

errorobjectrequired
Show fields
- codestringrequired
  Stable machine-readable error code from the catalog.
- messagestringrequired
  Human-readable description suitable for logging.
- detailsobject
  Optional, code-specific context (e.g. errors array for validation_error, retry_after for service_unavailable). Shape depends on error.code; treat as opaque otherwise.
  
  Show fields
  Empty object (no properties).
request_idstring
Server-generated correlation id for the request. Mirrors the X-Correlation-ID response header. Include this when contacting support.

format: `uuid`

Example response

{
  "error": {
    "code": "unauthorized",
    "message": "Missing or invalid credentials"
  },
  "request_id": "9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"
}

You do not have permission to access this resourceapplication/json

Type:ApiError

errorobjectrequired
Show fields
- codestringrequired
  Stable machine-readable error code from the catalog.
- messagestringrequired
  Human-readable description suitable for logging.
- detailsobject
  Optional, code-specific context (e.g. errors array for validation_error, retry_after for service_unavailable). Shape depends on error.code; treat as opaque otherwise.
  
  Show fields
  Empty object (no properties).
request_idstring
Server-generated correlation id for the request. Mirrors the X-Correlation-ID response header. Include this when contacting support.

format: `uuid`

Example response

{
  "error": {
    "code": "forbidden",
    "message": "You do not have permission to access this resource"
  },
  "request_id": "9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"
}

Resource not foundapplication/json

Type:ApiError

errorobjectrequired
Show fields
- codestringrequired
  Stable machine-readable error code from the catalog.
- messagestringrequired
  Human-readable description suitable for logging.
- detailsobject
  Optional, code-specific context (e.g. errors array for validation_error, retry_after for service_unavailable). Shape depends on error.code; treat as opaque otherwise.
  
  Show fields
  Empty object (no properties).
request_idstring
Server-generated correlation id for the request. Mirrors the X-Correlation-ID response header. Include this when contacting support.

format: `uuid`

Example response

{
  "error": {
    "code": "not_found",
    "message": "Resource not found"
  },
  "request_id": "9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"
}

Resource conflictapplication/json

Type:ApiError

errorobjectrequired
Show fields
- codestringrequired
  Stable machine-readable error code from the catalog.
- messagestringrequired
  Human-readable description suitable for logging.
- detailsobject
  Optional, code-specific context (e.g. errors array for validation_error, retry_after for service_unavailable). Shape depends on error.code; treat as opaque otherwise.
  
  Show fields
  Empty object (no properties).
request_idstring
Server-generated correlation id for the request. Mirrors the X-Correlation-ID response header. Include this when contacting support.

format: `uuid`

Example response

{
  "error": {
    "code": "conflict",
    "message": "Resource conflict"
  },
  "request_id": "9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"
}

Per-minute rate limit exceededapplication/json

Type:ApiError

errorobjectrequired
Show fields
- codestringrequired
  Stable machine-readable error code from the catalog.
- messagestringrequired
  Human-readable description suitable for logging.
- detailsobject
  Optional, code-specific context (e.g. errors array for validation_error, retry_after for service_unavailable). Shape depends on error.code; treat as opaque otherwise.
  
  Show fields
  Empty object (no properties).
request_idstring
Server-generated correlation id for the request. Mirrors the X-Correlation-ID response header. Include this when contacting support.

format: `uuid`

Example response

{
  "error": {
    "code": "rate_limit_exceeded",
    "message": "Per-minute rate limit exceeded"
  },
  "request_id": "9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"
}

An unexpected error occurredapplication/json

Type:ApiError

errorobjectrequired
Show fields
- codestringrequired
  Stable machine-readable error code from the catalog.
- messagestringrequired
  Human-readable description suitable for logging.
- detailsobject
  Optional, code-specific context (e.g. errors array for validation_error, retry_after for service_unavailable). Shape depends on error.code; treat as opaque otherwise.
  
  Show fields
  Empty object (no properties).
request_idstring
Server-generated correlation id for the request. Mirrors the X-Correlation-ID response header. Include this when contacting support.

format: `uuid`

Example response

{
  "error": {
    "code": "internal_error",
    "message": "An unexpected error occurred"
  },
  "request_id": "9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"
}

Service temporarily unavailable, please retryapplication/json

Type:ApiError

errorobjectrequired
Show fields
- codestringrequired
  Stable machine-readable error code from the catalog.
- messagestringrequired
  Human-readable description suitable for logging.
- detailsobject
  Optional, code-specific context (e.g. errors array for validation_error, retry_after for service_unavailable). Shape depends on error.code; treat as opaque otherwise.
  
  Show fields
  Empty object (no properties).
request_idstring
Server-generated correlation id for the request. Mirrors the X-Correlation-ID response header. Include this when contacting support.

format: `uuid`

Example response

{
  "error": {
    "code": "service_unavailable",
    "message": "Service temporarily unavailable, please retry"
  },
  "request_id": "9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"
}

Request example

curl --request GET \
  --url https://api.rankprompt.com/v1/citations/your_citation_id_here \
  --header 'Authorization: Bearer rp_live_<YOUR_API_KEY>' \
  --header 'Idempotency-Key: <UNIQUE_KEY>'

const fetch = require('node-fetch');

const url = 'https://api.rankprompt.com/v1/citations/your_citation_id_here';
const options = {
  method: 'GET',
  headers: {
    Authorization: 'Bearer rp_live_<YOUR_API_KEY>',
    'Idempotency-Key': '<UNIQUE_KEY>'
  }
};

try {
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error(error);
}

import requests

url = "https://api.rankprompt.com/v1/citations/your_citation_id_here"

headers = {
    "Authorization": "Bearer rp_live_<YOUR_API_KEY>",
    "Idempotency-Key": "<UNIQUE_KEY>"
}

response = requests.get(url, headers=headers)

print(response.json())