GET /v1/brands/{brand_id}/prompt-discoveries

List discovered prompts

Questions and keywords worth tracking from one free source: google_demand (the site's Search Console queries of the last 28 days joined with the keywords its domain ranks for, one row per query, Search Console's order first; origin says which side reports it), search_console (every query the site gets impressions for, most impressions first, read live from Google and kept five minutes; on a very large site the first read can take a minute or more, and a retry a minute later is served from the kept copy), ranking (the keywords the brand's domain ranks for in Google, from the stored overview), competitors (prompts whose answers name a competitor and not the brand, the most such answers first), fanouts (the web searches the engines ran) or copilot (the grounding queries in the queries file of the newest period the brand uploaded from Bing's AI Performance, the most citations of its site first, with citations and Bing's intent). Every row carries tracked_as_prompt and tracked_as_keyword, so what is already tracked can be skipped. note says why a source, or half of google_demand, is empty and how to fill it. search_console and copilot also need the read:analytics scope, ranking the read:seo scope and google_demand both.

Offset paginated via limit (1-100) and offset. Research and page reads cost credits: POST on this path.

Path parameters

Query parameters

  • source string (enum) required

    The source to read.

    one of google_demand, search_console, ranking, competitors, fanouts, copilot

  • limit integer optional

    Rows per page (1-100, default 25).

    default: 25

  • offset integer optional

    Rows to skip from the start.

    default: 0

  • 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 discovered prompts application/json
Type: DiscoveredPromptList
  • data array of DiscoveredPrompt 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

  • cached boolean

    A paid source answered from its cache, for nothing.

    default: `false`

  • Credits this call spent (0 for the free sources).

    min: 0 · default: `0`

  • note string (nullable) nullable

    Why a source has nothing yet and how to fill it.

  • object string

    default: `list`

  • pending boolean

    The source is still building its list for this brand: ask again in a minute.

    default: `false`

Example response
{
  "cached": false,
  "credits_charged": 0,
  "data": [
    {
      "answers": 12,
      "brand_answers": 2,
      "competitors": [
        "Nike",
        "ASICS",
        "Brooks"
      ],
      "kind": "question",
      "lost_answers": 9,
      "object": "discovered_prompt",
      "platforms": [
        "chatgpt",
        "gemini",
        "perplexity"
      ],
      "source": "competitors",
      "text": "Which running shoe brands would you recommend for a first marathon?",
      "tracked_as_keyword": false,
      "tracked_as_prompt": false
    }
  ],
  "has_more": false,
  "limit": 25,
  "object": "list",
  "offset": 0,
  "pending": false,
  "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).

  • 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).

  • 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).

  • 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).

  • 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).

  • 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).

  • 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).

  • 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).

  • 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"
}