GET /v1/brands/{brand_id}/content-opportunities

List content opportunities

scope read:content cost 3 RU idempotent required

Report-driven content ideas for the brand: prompts where the brand is absent from AI answers (missed_prompt) plus competitors cited in its place (competitor), each pre-classified to a content format and pre-filled with topic, keywords, and context.

Ranked with not-yet-covered opportunities first, then by impact. Bounded by limit (1-50, default 24); this list is not cursor-paginated. The summary block reports totals across the analyzed reports.

Path parameters

brand_id string required

Brand UUID.

Query parameters

limit integer optional

Number of opportunities to return (1-50, default 24).

default: 24
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 content opportunities application/json

Type: ContentOpportunityList

data array of ContentOpportunity required
summary ContentOpportunitySummary required

Aggregate counts for the opportunity set.
Show fields

Type: ContentOpportunitySummary
- actionable integer required
  
  Returned opportunities not yet covered by an existing brief.
  
  min: 0
- competitors integer required
  
  Distinct competitors cited where the brand is absent.
  
  min: 0
- missed_prompts integer required
  
  Distinct prompts where the brand is absent from AI answers.
  
  min: 0
- opportunities integer required
  
  Opportunities returned in data (bounded by limit).
  
  min: 0
- prompts_analyzed integer required
  
  Prompts actually examined across those reports.
  
  min: 0
- prompts_truncated boolean required
  
  true when the brand has more prompts than one pass can scan, so only the most recent prompts_analyzed were considered and older prompts were excluded. The other counts in this summary describe that subset, not the brand's full history.
- reports_analyzed integer required
  
  Recent reports scanned to build these opportunities.
  
  min: 0
- computed_at string (nullable) nullable
  
  When this set was last computed.
- object string
  
  Always content_opportunity_summary.
  
  default: `content_opportunity_summary`
- refresh_available boolean
  
  true when the data the set was built from has moved since computed_at (a new report, a Search Console or keyword gap refresh, tracked keywords or articles changed).
  
  default: `false`
object string

default: `list`

Example response

{
  "data": [
    {
      "competitor": "Asana",
      "content_context": {
        "listSize": 7,
        "listTheme": "project management tools for agencies"
      },
      "content_type": "ranked_list",
      "has_existing_brief": false,
      "id": "prompt:9a17c4f8-4e31-92fa-7d1e-3b5c8b2a9a17",
      "kind": "missed_prompt",
      "object": "content_opportunity",
      "platforms_missed": [
        "ChatGPT",
        "Perplexity"
      ],
      "reason": "You are absent on ChatGPT, Perplexity; Asana is cited instead.",
      "score": 71,
      "score_reasons": [
        "1,900 searches a month",
        "Absent on 2 of 3 AI engines",
        "Asana is cited instead"
      ],
      "source": "Missed prompt",
      "target_keywords": [
        "best project management tools for agencies"
      ],
      "title": "best project management tools for agencies",
      "topic": "What are the best project management tools for agencies?"
    }
  ],
  "object": "list",
  "summary": {
    "actionable": 21,
    "competitors": 6,
    "missed_prompts": 42,
    "object": "content_opportunity_summary",
    "opportunities": 24,
    "prompts_analyzed": 137,
    "prompts_truncated": false,
    "reports_analyzed": 10
  }
}

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/content-opportunities?limit=24&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/brands/your_brand_id_here/content-opportunities?limit=24&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/brands/your_brand_id_here/content-opportunities"

querystring = {"limit":"24","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())