GET /v1/brands/{brand_id}/citations

List citations

scope read:citations cost 2 RU idempotent required

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.
domain_authority: highest-authority sources first.

Filters (domain_category, page_category, min_domain_authority, min_rankprompt_score, has_backlink, is_actionable, has_contact, report_id) compose with AND.

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

Path parameters

brand_idstring required
Brand UUID.

Query parameters

sortstring (enum) optional
Sort key (descending). Default created_at.

one of created_at, rankprompt_score, domain_authority · default: created_at
domain_categorystring optional
Restrict to a single domain_category bucket.
page_categorystring optional
Restrict to a single page_category bucket.
min_domain_authoritystring optional
Minimum Moz domain_authority (0-100).
min_rankprompt_scorestring optional
Minimum rankprompt_score (0-100).
has_backlinkstring optional
Filter on whether the page backlinks to a brand domain.
is_actionablestring optional
Filter on the convenience is_actionable flag.
has_contactstring optional
Only return citations with a linked contact in the CRM.
report_idstring optional
Restrict to citations that appeared in a specific report.
limitinteger optional
Page size (default 20, max 100).

default: 20
cursorstring optional
Continuation token from a previous response's next_cursor.

Header parameters

Idempotency-Keystring optional

Responses

Returned citationsapplication/json

Type:CitationList

dataarray of Citationrequired
has_morebooleanrequired
next_cursorstring (nullable)nullable
Opaque continuation token. Pass back as ?cursor= to fetch the next page. null when has_more is false.
objectstring
default: `list`

Example response

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

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/brands/your_brand_id_here/citations?sort=created_at&domain_category=your_domain_category_here&page_category=your_page_category_here&min_domain_authority=your_min_domain_authority_here&min_rankprompt_score=your_min_rankprompt_score_here&has_backlink=your_has_backlink_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' \
  --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/brands/your_brand_id_here/citations?sort=created_at&domain_category=your_domain_category_here&page_category=your_page_category_here&min_domain_authority=your_min_domain_authority_here&min_rankprompt_score=your_min_rankprompt_score_here&has_backlink=your_has_backlink_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';
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/brands/your_brand_id_here/citations"

querystring = {"sort":"created_at","domain_category":"your_domain_category_here","page_category":"your_page_category_here","min_domain_authority":"your_min_domain_authority_here","min_rankprompt_score":"your_min_rankprompt_score_here","has_backlink":"your_has_backlink_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"}

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

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

print(response.json())