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_id string required

Citation id (UUID).

Query parameters

dry_run boolean optional

Preview the call without executing it. Runs auth, scope, eligibility and body validation, then returns 200 with a dry_run object reporting the request-unit and credit cost plus a non-consuming quota snapshot. Nothing is debited, reserved, dispatched or mutated. An invalid body still returns 422.

default: false

Header parameters

Idempotency-Key string optional

Responses

Returned a citation application/json

Type: Citation

brand_id string required

Owning brand id (UUID).
created_at string required

When the citation was first ingested.

format: `date-time`
id string required

Citation id (UUID).
updated_at string required

When the citation row was last updated.

format: `date-time`
url string required

Normalised page URL. Unique per (brand_id, citation_url).
ai_overviews_count integer

Times this URL appeared in Google AI Overviews.

min: 0 · default: `0`
backlink_anchor_text string (nullable) nullable

Anchor text of the backlink, when present.
backlink_is_nofollow boolean (nullable) nullable
backlink_is_sponsored boolean (nullable) nullable
backlink_is_ugc boolean (nullable) nullable
brand_mention_sentiment enum (nullable) nullable

Polarity of the brand mention. One of positive, neutral, negative, or null when no mention was found.
brand_mentioned boolean (nullable) nullable

True when the page contains a textual brand mention.
categorization_status string (nullable) nullable

Categorization state. null = not yet queued, pending = in progress, completed = categorization finished, failed = categorization errored.
categorized_at string (nullable) nullable

When categorization last finished.

format: `date-time`
chatgpt_count integer

Times this URL was cited by ChatGPT (gpt-5.6-luna + web_search).

min: 0 · default: `0`
chatgpt_search_count integer

Times this URL was cited by ChatGPT Search (gpt-5.6-terra + web_search).

min: 0 · default: `0`
claude_count integer

Times this URL was cited by Claude (knowledge-only, no web search). Typically 0.

min: 0 · default: `0`
claude_search_count integer

Times this URL was cited by Claude Search (Anthropic + web_search).

min: 0 · default: `0`
domain string (nullable) nullable

Bare domain extracted from url (e.g. example.com).
domain_category enum (nullable) nullable

Coarse domain category. One of 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.
gemini_count integer

Times this URL was cited by Gemini with Google Search grounding.

min: 0 · default: `0`
grok_count integer

Times this URL was cited by Grok (xAI Agent Tools web_search).

min: 0 · default: `0`
has_backlink boolean (nullable) nullable

True when the page links back to a brand-owned domain.
is_actionable boolean (nullable) nullable

True when the page is worth pursuing for outreach.
mention_prominence enum (nullable) nullable

Where on the page the brand mention appears. One of headline, body, sidebar, footnote, comparison, or null when no mention was found.
object string

Always citation.

default: `citation`
page_category enum (nullable) nullable

Coarse page category. One of 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_summary string (nullable) nullable

LLM-generated one-paragraph summary of the page.
page_title string (nullable) nullable

<title> of the page.
perplexity_count integer

Times this URL was cited by Perplexity for the brand.

min: 0 · default: `0`
rankprompt_score integer (nullable) nullable

0-100 outreach opportunity score (higher is better).
report_ids array of string

Report ids (UUIDs) where this citation appeared.

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,
  "chatgpt_search_count": 2,
  "claude_count": 0,
  "claude_search_count": 1,
  "created_at": "2026-04-15T10:00:00Z",
  "domain": "example.com",
  "domain_category": "EDITORIAL_MEDIA",
  "gemini_count": 1,
  "grok_count": 0,
  "has_backlink": true,
  "id": "5b9c7e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f",
  "is_actionable": true,
  "mention_prominence": "headline",
  "object": "citation",
  "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"
  ],
  "updated_at": "2026-04-15T10:30:00Z",
  "url": "https://example.com/best-coffee-makers-2026"
}

Request validation failed application/json

Type: ApiError

error object required
Show fields
- code string required
  
  Stable machine-readable error code from the catalog.
- message string required
  
  Human-readable description suitable for logging.
- details object
  
  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_id string

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 credentials application/json

Type: ApiError

error object required
Show fields
- code string required
  
  Stable machine-readable error code from the catalog.
- message string required
  
  Human-readable description suitable for logging.
- details object
  
  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_id string

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 resource application/json

Type: ApiError

error object required
Show fields
- code string required
  
  Stable machine-readable error code from the catalog.
- message string required
  
  Human-readable description suitable for logging.
- details object
  
  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_id string

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 found application/json

Type: ApiError

error object required
Show fields
- code string required
  
  Stable machine-readable error code from the catalog.
- message string required
  
  Human-readable description suitable for logging.
- details object
  
  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_id string

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 conflict application/json

Type: ApiError

error object required
Show fields
- code string required
  
  Stable machine-readable error code from the catalog.
- message string required
  
  Human-readable description suitable for logging.
- details object
  
  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_id string

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 exceeded application/json

Type: ApiError

error object required
Show fields
- code string required
  
  Stable machine-readable error code from the catalog.
- message string required
  
  Human-readable description suitable for logging.
- details object
  
  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_id string

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 occurred application/json

Type: ApiError

error object required
Show fields
- code string required
  
  Stable machine-readable error code from the catalog.
- message string required
  
  Human-readable description suitable for logging.
- details object
  
  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_id string

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 retry application/json

Type: ApiError

error object required
Show fields
- code string required
  
  Stable machine-readable error code from the catalog.
- message string required
  
  Human-readable description suitable for logging.
- details object
  
  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_id string

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?dry_run=false' \
  --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?dry_run=false';
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"

querystring = {"dry_run":"false"}

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

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

print(response.json())