GET /v1/brands/{brand_id}/prompts

List brand prompts

Every prompt the brand tracks in a Scheduled Report or ran in a one-off report, one row per prompt text, with its runs, visibility, best position, visibility on the last 12 days it was answered and the Google keyword behind it. Every answer of the selected runs counts: platform_results gives the answers, mentions and the brand's mean position per engine, brands_named the brands those answers name (the brand where brand_appears is true, a registered competitor under its canonical name) and domains_cited the domains they cite, each with its answers and mean first place, most answers first, then the better position, then the name.

Filters compose with AND: scheduled_report_id, tracking (active: in a running schedule, paused: scheduled but not running, one_off: never scheduled, or not in the one scheduled_report_id names), type (brand, competitor, organic) and intent (of the mapped keyword, unmapped for none), each repeatable for several, category (the prompt's current category: its tracked one, else the one it ran under; repeat for several), search (a substring of the text) and prompt_hash (one prompt text). brands_named and domains_cited come only with detail=true, the costly part, at most 100 rows a page. The Visibility filters report_id (repeat for several), platform (repeat for several engines), date_from and date_to narrow the answers each row counts to those reports, engines and period, by the date of each answer.

facets counts the prompts by type, intent and category across every page, each count under every filter but its own, so it says what picking that value would return.

sort: runs (default, most run first), visibility (highest first), recent (last run first) or text (alphabetical). tz (an IANA zone, default UTC) is the zone the trend's days are counted in. Offset paginated via limit (1-500) and offset.

Path parameters

brand_id string required

Brand UUID.

Query parameters

tracking string optional

active, paused or one_off; repeat the parameter for several.
type string optional

brand, competitor or organic; repeat the parameter for several.
intent string optional

Search intent of the mapped keyword, unmapped for prompts without one; repeat the parameter for several.
search string optional

Only prompts containing this text (case-insensitive).
prompt_hash string optional

Only this prompt text (its prompt_hash).
detail boolean optional

true adds brands_named and domains_cited, a slower read capped at 100 rows a page. Default false.

default: false
sort string (enum) optional

Order of the rows. Default runs.

one of runs, visibility, recent, text · default: runs
limit integer optional

Prompts per page (1-500, default 100).

default: 100
offset integer optional

Prompts to skip from the start.

default: 0
tz string optional

IANA time zone the days are counted in, e.g. America/New_York. Default UTC.

default: UTC
report_id string optional

Only these reports (UUIDs); repeat the parameter for several.
scheduled_report_id string optional

Only the runs of this Scheduled Report (UUID).
platform string optional

Only answers from these engines; repeat the parameter for several.
date_from string optional

Only answers from this moment on (ISO-8601).
date_to string optional

Only answers before this moment, exclusive (ISO-8601).
category string optional

Only answers to prompts of these categories; repeat the parameter for several.
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 brand prompts application/json

Type: BrandPromptList

data array of BrandPrompt required
has_more boolean required

True when more items exist past this page. Fetch them with a larger offset.
limit integer required

Page size that was applied.

min: 1
offset integer required

Number of items skipped before this page.

min: 0
total integer required

Total number of items matching the query, across all pages.

min: 0
facets BrandPromptFacets (nullable) nullable

Counts by type, intent and category across every page; null when none came back.
object string

default: `list`

Example response

{
  "data": [
    {
      "best_rank": 2,
      "brands_named": [
        {
          "answers": 21,
          "category": "my_brand",
          "name": "adidas",
          "position": 2
        },
        {
          "answers": 21,
          "category": "direct_competitor",
          "name": "Nike",
          "position": 2.4
        }
      ],
      "category": "Marathon",
      "difficulty": 62,
      "domains_cited": [
        {
          "answers": 17,
          "domain": "runnersworld.com",
          "position": 1.5
        }
      ],
      "head_keyword": "marathon running shoes",
      "intent": "commercial",
      "languages": [
        "English"
      ],
      "last_run_at": "2026-09-20T08:15:00+00:00",
      "mentions": 21,
      "object": "brand_prompt",
      "one_off_runs": 1,
      "platform_results": [
        {
          "mentions": 4,
          "platform": "chatgpt",
          "position": 2.3,
          "results": 9
        }
      ],
      "platforms": [
        "chatgpt",
        "gemini",
        "perplexity"
      ],
      "prompt_hash": "6f1ed002ab5595859014ebf0951522d9c47f3ab1",
      "prompt_text": "Which running shoes are best for a first marathon?",
      "prompt_type": "organic",
      "results": 54,
      "runs": 9,
      "tracked": [
        {
          "active": true,
          "country": "United States",
          "id": "018e7c2c-33ab-7df1-b1cd-2ac3a8f9112d",
          "language": "English",
          "region_config_id": "2a3b4c5d-6e7f-4a8b-9c0d-1e2f3a4b5c6e",
          "region_name": "United States",
          "scheduled_report_id": "7b1d4c2e-5a6f-4e8b-9c0d-1e2f3a4b5c6d",
          "scheduled_report_name": "Weekly US tracking"
        }
      ],
      "tracked_active": true,
      "trend": [
        {
          "day": "2026-09-13",
          "visibility": 33.3
        },
        {
          "day": "2026-09-20",
          "visibility": 44.4
        }
      ],
      "visibility": 38.9,
      "volume": 12100
    }
  ],
  "facets": {
    "categories": [
      {
        "category": "Marathon",
        "mentions": 118,
        "prompts": 12,
        "results": 324,
        "tracked": 9
      }
    ],
    "intent": {
      "commercial": 21,
      "informational": 18,
      "unmapped": 13
    },
    "object": "brand_prompt_facets",
    "type": {
      "brand": 4,
      "competitor": 11,
      "organic": 37
    }
  },
  "has_more": false,
  "limit": 100,
  "object": "list",
  "offset": 0,
  "total": 1
}

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/prompts?tracking=your_tracking_here&type=your_type_here&intent=your_intent_here&search=your_search_here&prompt_hash=your_prompt_hash_here&detail=false&sort=runs&limit=100&offset=0&tz=UTC&report_id=your_report_id_here&scheduled_report_id=your_scheduled_report_id_here&platform=your_platform_here&date_from=your_date_from_here&date_to=your_date_to_here&category=your_category_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/prompts?tracking=your_tracking_here&type=your_type_here&intent=your_intent_here&search=your_search_here&prompt_hash=your_prompt_hash_here&detail=false&sort=runs&limit=100&offset=0&tz=UTC&report_id=your_report_id_here&scheduled_report_id=your_scheduled_report_id_here&platform=your_platform_here&date_from=your_date_from_here&date_to=your_date_to_here&category=your_category_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/prompts"

querystring = {"tracking":"your_tracking_here","type":"your_type_here","intent":"your_intent_here","search":"your_search_here","prompt_hash":"your_prompt_hash_here","detail":"false","sort":"runs","limit":"100","offset":"0","tz":"UTC","report_id":"your_report_id_here","scheduled_report_id":"your_scheduled_report_id_here","platform":"your_platform_here","date_from":"your_date_from_here","date_to":"your_date_to_here","category":"your_category_here","dry_run":"false"}

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

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

print(response.json())