GET /v1/brands/{brand_id}/citations

List citations

Cursor-paginated list of citations discovered for the brand across recent reports.

Sort options (descending):

created_at (default): newest first.
rankprompt_score: highest-impact opportunities first.

Filters (page_category, min_rankprompt_score, has_backlink, brand_mentioned, unlinked, backlink_status, is_actionable, has_contact, report_id) compose with AND. To narrow by site_type or relation, use /citations/pages.

Cursors are bound to the sort they were issued for; restart pagination with cursor=null when changing sort.

Path parameters

brand_id string required

Brand UUID.

Query parameters

sort string (enum) optional

Sort key (descending). Default created_at.

one of created_at, rankprompt_score · default: created_at
page_category string optional

Restrict to a single page_category bucket.
min_rankprompt_score string optional

Minimum rankprompt_score (0-100).
has_backlink string optional

Filter on whether the page backlinks to a brand domain. false returns only pages an Analyze or a backlink check has read; pages nobody read have has_backlink: null and match neither value.
brand_mentioned string optional

Filter on whether the page names the brand; only pages an Analyze read match either value.
unlinked string optional

true: pages that name the brand without linking to it, the easiest backlink to ask for. Only pages an Analyze read.
backlink_status string optional

What the newest weekly re-read of a won backlink found; lost lists the links that disappeared (those no longer count as has_backlink). Pages never re-read match no value.
is_actionable string optional

Filter on the convenience is_actionable flag.
has_contact string optional

Only return citations with a linked contact in the CRM.
report_id string optional

Restrict to citations that appeared in a specific report.
limit integer optional

Page size (default 20, max 100).

default: 20
cursor string optional

Continuation token from a previous response's next_cursor.
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 citations application/json

Type: CitationList

data array of Citation required
has_more boolean required
next_cursor string (nullable) nullable

Opaque continuation token. Pass back as ?cursor= to fetch the next page. null when has_more is false.
object string

default: `list`

Example response

{
  "data": [
    {
      "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/"
    }
  ],
  "has_more": false,
  "object": "list"
}

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/brands/your_brand_id_here/citations?sort=created_at&page_category=your_page_category_here&min_rankprompt_score=your_min_rankprompt_score_here&has_backlink=your_has_backlink_here&brand_mentioned=your_brand_mentioned_here&unlinked=your_unlinked_here&backlink_status=your_backlink_status_here&is_actionable=your_is_actionable_here&has_contact=your_has_contact_here&report_id=your_report_id_here&limit=20&cursor=your_cursor_here&dry_run=false' \
  --header 'Authorization: Bearer rp_live_<YOUR_API_KEY>'

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

const url = 'https://api.rankprompt.com/v1/brands/your_brand_id_here/citations?sort=created_at&page_category=your_page_category_here&min_rankprompt_score=your_min_rankprompt_score_here&has_backlink=your_has_backlink_here&brand_mentioned=your_brand_mentioned_here&unlinked=your_unlinked_here&backlink_status=your_backlink_status_here&is_actionable=your_is_actionable_here&has_contact=your_has_contact_here&report_id=your_report_id_here&limit=20&cursor=your_cursor_here&dry_run=false';
const options = {method: 'GET', headers: {Authorization: 'Bearer rp_live_<YOUR_API_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/brands/your_brand_id_here/citations"

querystring = {"sort":"created_at","page_category":"your_page_category_here","min_rankprompt_score":"your_min_rankprompt_score_here","has_backlink":"your_has_backlink_here","brand_mentioned":"your_brand_mentioned_here","unlinked":"your_unlinked_here","backlink_status":"your_backlink_status_here","is_actionable":"your_is_actionable_here","has_contact":"your_has_contact_here","report_id":"your_report_id_here","limit":"20","cursor":"your_cursor_here","dry_run":"false"}

headers = {"Authorization": "Bearer rp_live_<YOUR_API_KEY>"}

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

print(response.json())