API Reference

Read-only HTTP API for reading your workspace's brand, prompt, and mention data.

Introduction

The Rankr API gives programmatic access to your workspace's data — brands, prompts, mentions, and rollup summaries. It's read-only and designed for building integrations and AI agents (MCP, Zapier, custom dashboards).

Base URL

https://api.rankr.so/v1

Authentication

Every authenticated request carries an API key in the Authorization header. Keys are scoped to a workspace — create them under Settings → API Keys. The plaintext is shown once at creation; store it somewhere safe.

bash

curl 'https://api.rankr.so/v1/brands' \
  -H 'Authorization: Bearer rnkr_live_…'

Rate limits

Each API key is limited to 60 requests per minute and 1,000 requests per hour. When you exceed a limit you'll get a 429 with a Retry-After header.

Errors

Errors use standard HTTP status codes and a consistent body shape.

json

{
  "error": {
    "code": "not_found",
    "message": "Brand not found"
  }
}

unauthorized — missing, invalid, revoked, or expired key.
bad_request — malformed parameters.
not_found — resource doesn't exist or isn't in your workspace.
rate_limited — too many requests, back off and retry.
internal — our bug, please contact support.

Brands

GET/v1/brands#list-brands

List brands

Returns every brand in the workspace the API key belongs to.

Requires API key

Parameters

Name	In	Type	Description
limit	query	integer	Max items to return. Default 50, max 200.

Request

bash

curl -X GET 'https://api.rankr.so/v1/brands' \
  -H 'Authorization: Bearer YOUR_API_KEY'

Response 200

json

{
  "data": [
    {
      "id": "9a7e1d92-7c5a-4a2c-8d3b-e5a1f3c7b9a0",
      "name": "Acme",
      "website": "https://acme.com",
      "description": "Enterprise widget platform.",
      "industry": "SaaS",
      "favicon_url": "https://www.google.com/s2/favicons?domain=acme.com&sz=64",
      "created_at": "2026-03-01T12:04:22Z"
    }
  ]
}

GET/v1/brands/{brand_id}#get-brand

Get a brand

Full brand profile, including positioning, offerings, and pain points.

Requires API key

Parameters

Name	In	Type	Description
brand_idrequired	path	uuid	ID from the list endpoint.

Request

bash

curl -X GET 'https://api.rankr.so/v1/brands/:brand_id' \
  -H 'Authorization: Bearer YOUR_API_KEY'

Response 200

json

{
  "data": {
    "id": "9a7e1d92-7c5a-4a2c-8d3b-e5a1f3c7b9a0",
    "name": "Acme",
    "website": "https://acme.com",
    "description": "Enterprise widget platform.",
    "detailed_description": "Acme builds widgets for large enterprises …",
    "industry": "SaaS",
    "positioning": "The fastest widget platform for regulated industries.",
    "target_audience": [
      "IT ops",
      "Security engineers"
    ],
    "offerings": [
      {
        "name": "Widget API",
        "description": "Programmable widgets."
      }
    ],
    "pain_points": [
      {
        "pain": "Slow widgets",
        "solution": "Edge caching."
      }
    ],
    "favicon_url": "https://www.google.com/s2/favicons?domain=acme.com&sz=64",
    "onboarding_completed": true,
    "created_at": "2026-03-01T12:04:22Z"
  }
}

GET/v1/brands/{brand_id}/prompts#list-brand-prompts

List tracked prompts

The prompts Rankr sends to AI models when checking this brand's visibility.

Requires API key

Parameters

Name	In	Type	Description
brand_idrequired	path	uuid	Brand to fetch prompts for.
status	query	string	Filter by prompt status. `activepausedsuggestedall`
category	query	string	Filter by prompt category. `discoverycomparisonrecommendationproblem_solvingcustom`

Request

bash

curl -X GET 'https://api.rankr.so/v1/brands/:brand_id/prompts' \
  -H 'Authorization: Bearer YOUR_API_KEY'

Response 200

json

{
  "data": [
    {
      "id": "f0b6c8e1-2d3a-44a9-b0c7-8e4f1a9c7d01",
      "text": "best enterprise widget platform",
      "category": "discovery",
      "is_active": true,
      "status": "active",
      "created_at": "2026-03-02T09:11:00Z"
    }
  ]
}

GET/v1/brands/{brand_id}/mentions#list-brand-mentions

List mentions

Every time a brand or competitor was mentioned in a scrape run, with sentiment and provider attribution.

Requires API key

Parameters

Name	In	Type	Description
brand_idrequired	path	uuid	Brand to fetch mentions for.
since	query	ISO-8601	Only mentions created at or after this timestamp.
until	query	ISO-8601	Only mentions created at or before this timestamp.
provider	query	string	Repeatable. Filter by AI provider. `openaianthropicgeminiperplexitygoogle_ai_overview`
entity_type	query	string	Only your brand or only competitors. `brandcompetitor`
prompt_id	query	uuid	Only mentions from scrape runs for this prompt.
limit	query	integer	Max items to return. Default 50, max 200.
cursor	query	ISO-8601	Pass the previous response's next_cursor to paginate.

Request

bash

curl -X GET 'https://api.rankr.so/v1/brands/:brand_id/mentions' \
  -H 'Authorization: Bearer YOUR_API_KEY'

Response 200

json

{
  "data": [
    {
      "id": "aa11bb22-cc33-4455-66dd-7788eeff9900",
      "scrape_run_id": "b2c3d4e5-f6a7-48b9-0c1d-2e3f4a5b6c7d",
      "brand_id": "9a7e1d92-7c5a-4a2c-8d3b-e5a1f3c7b9a0",
      "entity_type": "brand",
      "entity_name": "Acme",
      "entity_website": "https://acme.com",
      "mentioned": true,
      "sentiment_score": 78,
      "mention_char_position": 412,
      "created_at": "2026-04-19T06:05:14Z",
      "scrape_run": {
        "id": "b2c3d4e5-f6a7-48b9-0c1d-2e3f4a5b6c7d",
        "prompt_id": "f0b6c8e1-2d3a-44a9-b0c7-8e4f1a9c7d01",
        "provider": "openai",
        "sentiment": "positive",
        "created_at": "2026-04-19T06:05:12Z"
      }
    }
  ],
  "next_cursor": "2026-04-19T06:05:14Z"
}

If next_cursor is non-null, pass it as ?cursor= on the next request to continue paging.

GET/v1/brands/{brand_id}/summary#get-brand-summary

Summary rollup

One-call snapshot for a time window — visibility %, average sentiment, mentions per provider, top competitors. Designed so an agent can answer "how is my brand doing" in a single tool call.

Requires API key

Parameters

Name	In	Type	Description
brand_idrequired	path	uuid	Brand to summarize.
window	query	string	Rollup window. Default 30d. `7d30d90d`

Request

bash

curl -X GET 'https://api.rankr.so/v1/brands/:brand_id/summary' \
  -H 'Authorization: Bearer YOUR_API_KEY'

Response 200

json

{
  "window": "30d",
  "visibility_pct": 62,
  "avg_sentiment": 74,
  "total_mentions": 412,
  "mentions_by_provider": {
    "openai": 181,
    "anthropic": 104,
    "gemini": 78,
    "perplexity": 49
  },
  "top_competitors": [
    {
      "name": "Globex",
      "mentions": 57,
      "sentiment": 68
    },
    {
      "name": "Initech",
      "mentions": 41,
      "sentiment": 72
    }
  ],
  "prompts_tracked": 24,
  "generated_at": "2026-04-20T09:32:00Z"
}

GET/v1/brands/{brand_id}/answers/{answer_id}#get-answer

Get an AI answer

Fetch the full text of what an AI model answered for one of the tracked prompts, plus the URLs it cited.

Requires API key

Parameters

Name	In	Type	Description
brand_idrequired	path	uuid	Brand UUID.
answer_idrequired	path	uuid	Answer UUID (from a mention's `answer.id`).

Request

bash

curl -X GET 'https://api.rankr.so/v1/brands/:brand_id/answers/:answer_id' \
  -H 'Authorization: Bearer YOUR_API_KEY'

Response 200

json

{
  "data": {
    "id": "b2c3d4e5-f6a7-48b9-0c1d-2e3f4a5b6c7d",
    "brand_id": "9a7e1d92-7c5a-4a2c-8d3b-e5a1f3c7b9a0",
    "prompt_id": "f0b6c8e1-2d3a-44a9-b0c7-8e4f1a9c7d01",
    "provider": "openai",
    "answer": "For enterprise widget platforms, Acme is often recommended…",
    "sources": [
      "https://techcrunch.com/…",
      "https://reddit.com/r/…/comments/…"
    ],
    "brand_mentioned": true,
    "sentiment": "positive",
    "sentiment_score": 78,
    "created_at": "2026-04-19T06:05:12Z",
    "prompt": {
      "id": "f0b6c8e1-2d3a-44a9-b0c7-8e4f1a9c7d01",
      "text": "best enterprise widget platform",
      "category": "discovery"
    }
  }
}

GET/v1/brands/{brand_id}/sources#list-sources

Most-cited sources

Aggregate URLs that AI providers cited when answering tracked prompts, with counts — answers "which websites are most influential when AI assistants talk about my space".

Requires API key

Parameters

Name	In	Type	Description
brand_idrequired	path	uuid	Brand UUID.
window	query	string	Aggregation window. Default 30d. `7d30d90d`
provider	query	string	Repeatable. Restrict to these providers. `openaianthropicgeminiperplexitygoogle_ai_overview`
limit	query	integer	Max unique sources to return (default 50, max 200).

Request

bash

curl -X GET 'https://api.rankr.so/v1/brands/:brand_id/sources' \
  -H 'Authorization: Bearer YOUR_API_KEY'

Response 200

json

{
  "window": "30d",
  "data": [
    {
      "url": "https://techcrunch.com/...",
      "count": 47,
      "providers": [
        "openai",
        "perplexity"
      ]
    },
    {
      "url": "https://reddit.com/r/.../comments/...",
      "count": 22,
      "providers": [
        "perplexity"
      ]
    }
  ]
}

GET/v1/brands/{brand_id}/blog-articles#list-blog-articles

List blog articles cited by AI

Blog posts that AI providers cited when answering tracked prompts, with title, description, author, and publish date.

Requires API key

Parameters

Name	In	Type	Description
brand_idrequired	path	uuid
limit	query	integer	Default 50, max 200.
cursor	query	ISO-8601	Pass next_cursor to paginate.

Request

bash

curl -X GET 'https://api.rankr.so/v1/brands/:brand_id/blog-articles' \
  -H 'Authorization: Bearer YOUR_API_KEY'

Response 200

json

{
  "data": [
    {
      "id": "aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee",
      "url": "https://techcrunch.com/2026/02/widgets-at-scale",
      "domain": "techcrunch.com",
      "title": "Widgets at Scale",
      "description": "How enterprise widget platforms are evolving …",
      "og_image": "https://...",
      "author": "Jane Doe",
      "published_at": "2026-02-14T10:00:00Z",
      "last_fetched_at": "2026-04-19T06:05:22Z",
      "created_at": "2026-03-01T12:04:22Z"
    }
  ],
  "next_cursor": null
}

GET/v1/brands/{brand_id}/youtube-videos#list-youtube-videos

List YouTube videos cited by AI

YouTube videos cited by AI providers, with channel, view/like/comment counts, and publish date.

Requires API key

Parameters

Name	In	Type
brand_idrequired	path	uuid
limit	query	integer
cursor	query	ISO-8601

Request

bash

curl -X GET 'https://api.rankr.so/v1/brands/:brand_id/youtube-videos' \
  -H 'Authorization: Bearer YOUR_API_KEY'

Response 200

json

{
  "data": [
    {
      "id": "abcd1234-....",
      "video_id": "dQw4w9WgXcQ",
      "url": "https://www.youtube.com/watch?v=dQw4w9WgXcQ",
      "title": "Best widget platforms in 2026",
      "channel_name": "TechReviewer",
      "channel_id": "UC123",
      "channel_subscribers": 412000,
      "thumbnail_url": "https://i.ytimg.com/...",
      "view_count": 182400,
      "like_count": 5430,
      "comment_count": 211,
      "duration": "PT12M34S",
      "published_at": "2026-03-22T15:00:00Z",
      "last_fetched_at": "2026-04-19T06:05:22Z",
      "created_at": "2026-03-23T08:01:00Z"
    }
  ],
  "next_cursor": null
}

GET/v1/brands/{brand_id}/reddit-posts#list-reddit-posts

List Reddit posts cited by AI

Reddit threads cited by AI providers, with subreddit, score, comment count, and full self-text.

Requires API key

Parameters

Name	In	Type
brand_idrequired	path	uuid
limit	query	integer
cursor	query	ISO-8601

Request

bash

curl -X GET 'https://api.rankr.so/v1/brands/:brand_id/reddit-posts' \
  -H 'Authorization: Bearer YOUR_API_KEY'

Response 200

json

{
  "data": [
    {
      "id": "abcd1234-....",
      "post_id": "abcde1",
      "url": "https://www.reddit.com/r/saas/comments/abcde1/...",
      "title": "Which widget platform do you use?",
      "subreddit": "saas",
      "author": "u/example",
      "score": 142,
      "num_comments": 48,
      "selftext": "We've been evaluating several widget platforms …",
      "created_utc": "2026-03-15T19:00:00Z",
      "last_fetched_at": "2026-04-19T06:05:22Z",
      "created_at": "2026-03-16T08:01:00Z"
    }
  ],
  "next_cursor": null
}

GET/v1/brands/{brand_id}/competitors#list-competitors

List tracked competitors

Competitors being tracked alongside this brand.

Requires API key

Parameters

Name	In	Type	Description
brand_idrequired	path	uuid

Request

bash

curl -X GET 'https://api.rankr.so/v1/brands/:brand_id/competitors' \
  -H 'Authorization: Bearer YOUR_API_KEY'

Response 200

json

{
  "data": [
    {
      "id": "c0c0c0c0-....",
      "name": "Globex",
      "website": "https://globex.com",
      "favicon_url": "https://www.google.com/s2/favicons?domain=globex.com&sz=64",
      "description": "Enterprise widget alternative.",
      "created_at": "2026-03-01T12:05:00Z"
    }
  ]
}