API docs v1
GET /v1/citations/{citation_id}

Retrieve a citation

scope read:citations cost 1 RU

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

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

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).

  • relation enum required

    The page's relation to the brand: owned (the brand's own site), competitor (the site of an active direct or indirect competitor in the brand's registry) or none.

  • 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 Mode (AI Overviews) answers.

    min: 0 · default: `0`

  • analyzed_at string (nullable) nullable

    When a paid Analyze read the page for its contacts, its backlink and the brands it names, or when a user recorded by hand whether the page names the brand. null = not analyzed.

    format: `date-time`

  • author string (nullable) nullable

    The person the page names as its author, null when it names none or was not read yet.

  • backlink_anchor_text string (nullable) nullable

    Anchor text of the backlink, when present.

  • 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

    Whether the page names the brand, as read by an Analyze of the page or set by a user. null until the page is analyzed: a page that was not read is never reported as not naming the brand.

  • categorization_status string (nullable) nullable

    Categorization state. Pages are categorized automatically a few minutes after the report that cites them, at no cost. null = not started yet, pending = being categorized, completed = categorized, failed = not categorized for good (three failed attempts, a URL too long, or an older failure).

  • categorized_at string (nullable) nullable

    When categorization last finished.

    format: `date-time`

  • chatgpt_count integer

    Times this URL was cited by ChatGPT.

    min: 0 · default: `0`

  • chatgpt_search_count integer

    Times this URL was cited by ChatGPT Search, retired from new runs; past answers keep it.

    min: 0 · default: `0`

  • claude_count integer

    Times this URL was cited by Claude.

    min: 0 · default: `0`

  • claude_search_count integer

    Times this URL was cited by Claude Search, retired from new runs; past answers keep it.

    min: 0 · default: `0`

  • domain string (nullable) nullable

    Bare domain extracted from url (e.g. runnersworld.com).

  • 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`

  • image_url string (nullable) nullable

    The page's preview image (og:image or the engine's thumbnail), null until the page is read.

  • 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.

  • modified_at string (nullable) nullable

    When the page says it was last updated (article:modified_time, og:updated_time or JSON-LD dateModified), null when it does not say or was not read yet.

    format: `date-time`

  • object string

    Always citation.

    default: `citation`

  • page_category enum (nullable) nullable

    Coarse page category. One of HOMEPAGE, PRODUCT_PAGE, LISTICLE_COMPARISON, REVIEW_ROUNDUP, NEWS_ARTICLE, BLOG_POST, GUIDE_TUTORIAL, DOCUMENTATION, DIRECTORY_LISTING, 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`

  • published_at string (nullable) nullable

    When the page says it was published, null when it does not say or was not read yet.

    format: `date-time`

  • rankprompt_score integer (nullable) nullable

    Outreach score, 0-100 (higher is better): how much the engines cite the page (0-40), whether it names the brand's competitors and not the brand (0-25), how reachable the site is (-30 to 20) and how well the page fits (0-15). 0 for the brand's own site, a competitor's site and a page that already links to the brand. Recomputed whenever one of its signals changes.

  • report_ids array of string

    Report ids (UUIDs) where this citation appeared.

  • schema_types array of string (nullable) nullable

    The Schema.org types the page's JSON-LD declares (e.g. Article, FAQPage, Product), sorted, the first 20 when it declares more; null when it declares none or was not read yet.

  • site_name string (nullable) nullable

    The site's own name (og:site_name, e.g. The Verge), null when unknown.

  • site_type string (nullable) nullable

    What the whole site is, an open set (new values can appear): reddit, youtube, linkedin, wikipedia, qa_forum, social, news, reviews, reference, institutional, company, marketplace, google_place, google_product or other; null while the site is still being classified.

Example response 
{
  "ai_overviews_count": 0,
  "analyzed_at": "2026-04-16T09:12:00+00:00",
  "author": "Amanda Furrer",
  "backlink_anchor_text": "adidas Adizero Boston 12",
  "backlink_is_nofollow": false,
  "backlink_is_sponsored": false,
  "backlink_is_ugc": false,
  "backlink_method": "parser",
  "brand_id": "3f9c7e8a-1b6a-4d8e-92cf-7d9c8b1e2a04",
  "brand_mention_sentiment": "positive",
  "brand_mentioned": true,
  "categorization_status": "completed",
  "categorized_at": "2026-04-15T10:30:00+00:00",
  "chatgpt_count": 3,
  "chatgpt_search_count": 2,
  "claude_count": 0,
  "claude_search_count": 1,
  "created_at": "2026-04-15T10:00:00+00:00",
  "domain": "runnersworld.com",
  "gemini_count": 1,
  "grok_count": 0,
  "has_backlink": true,
  "id": "5b9c7e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f",
  "image_url": "https://hips.hearstapps.com/best-running-shoes.jpg",
  "is_actionable": true,
  "mention_prominence": "headline",
  "object": "citation",
  "page_category": "LISTICLE_COMPARISON",
  "page_summary": "Tested picks of road and trail running shoes for every budget.",
  "page_title": "The Best Running Shoes of 2026",
  "perplexity_count": 1,
  "published_at": "2026-05-14T12:00:00+00:00",
  "rankprompt_score": 78,
  "relation": "none",
  "report_ids": [
    "c4f8b6a2-9a17-4e31-92fa-7d1e3b5c8b2a"
  ],
  "site_name": "Runner's World",
  "site_type": "news",
  "updated_at": "2026-04-15T10:30:00+00:00",
  "url": "https://www.runnersworld.com/gear/a20865766/best-running-shoes/"
}
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"
}