GET /v1/reports/{report_id}

Retrieve a report

Return a single report with its prompts and per-platform prompts[*].results inlined. One call covers everything you need to render the full report. No follow-up requests required.

Each result carries the engine's full answer in response, which is most of the payload. Pass include_responses=false to leave it out when you only need who appeared, the ranks and the citations.

Path parameters

report_id string required

Report UUID.

Query parameters

include_responses boolean optional

false leaves out each result's full answer text (response is null).

default: true
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 a report application/json

Type: ReportDetail

brand_id string required

Owning brand id (UUID).
created_at string required

ISO-8601 timestamp when the report was created.

format: `date-time`
id string required

Stable report identifier (UUID).
name string required

Human-readable report label (defaults to Untitled Report).
status enum required

Report lifecycle status.
ai_platforms array of string

AI platforms the report runs against. An open set: results recorded before an engine was retired keep it (chatgpt_search, claude_search). Each prompt costs 1 credit per 3 engines, rounded up: 1 to 3 engines cost 1 credit, 4 to 6 cost 2.
batch_id string (nullable) nullable

Batch id grouping reports from the same scheduled run; null for manual runs.
build_phase enum (nullable) nullable

Where a running report is: queued, answering (the engines answer), resolving (the businesses the answers name are resolved) or finishing; null when it is not running.
cells_permanently_failed integer

Cells that permanently failed after retries.

min: 0 · default: `0`
country string (nullable) nullable

Country the report was scoped to.
degraded_cells_count integer

Cells that returned degraded/partial data in this report.

min: 0 · default: `0`
failure_reason string (nullable) nullable

Human-readable reason when status == 'failed'.
language string (nullable) nullable

Primary language (English name like English, Spanish).
location string (nullable) nullable

Free-form location string used for queries.
object string

Always report.

default: `report`
progress ReportProgress (nullable) nullable

Cells answered and failed while the report runs; null when it is not running.
prompts array of ReportDetailPrompt

Every prompt attached to the report (capped at MAX_PROMPTS_PER_REPORT = 50), each with its per-platform results inlined under results.
ranked_prompts integer

Prompt-platform results that surfaced the brand. Always ≤ total_results.

min: 0 · default: `0`
region_config_id string (nullable) nullable

Region configuration used for this report, when applicable.
scheduled_report_id string (nullable) nullable

Schedule id when the report was triggered by a schedule; null for manual runs.
total_results integer

Total prompt-platform results materialised by the run

min: 0 · default: `0`
visibility_score number (nullable) nullable

Aggregate brand visibility score (0-100). Null until the report completes.

Example response

{
  "ai_platforms": [
    "chatgpt",
    "claude",
    "ai_overviews"
  ],
  "brand_id": "3f9c7e8a-1b6a-4d8e-92cf-7d9c8b1e2a04",
  "cells_permanently_failed": 0,
  "country": "United States",
  "created_at": "2024-09-01T11:00:00+00:00",
  "degraded_cells_count": 0,
  "id": "8a72d9f1-c4b5-4e6d-9b1f-0e3a2c6d8b04",
  "language": "en",
  "location": "United States",
  "name": "adidas weekly visibility, Sept 2024",
  "object": "report",
  "prompts": [
    {
      "brand_id": "3f9c7e8a-1b6a-4d8e-92cf-7d9c8b1e2a04",
      "category": "Running Shoes",
      "created_at": "2026-04-01T11:00:00+00:00",
      "id": "018e7c2c-33ab-7df1-b1cd-2ac3a8f9112d",
      "object": "prompt",
      "prompt_text": "What are the best running shoes for a first marathon?",
      "report_id": "8a72d9f1-c4b5-4e6d-9b1f-0e3a2c6d8b04",
      "results": [
        {
          "ai_platform": "chatgpt",
          "brand_appears": true,
          "businesses_categorized": [
            {
              "category": "direct_competitor",
              "mentioned_as": "Asics",
              "name": "ASICS",
              "object": "business_categorized",
              "reason": "Running shoe brand frequently cited alongside the brand."
            },
            {
              "category": "indirect_competitor",
              "name": "Brooks Running",
              "object": "business_categorized",
              "reason": "Running shoe brand mentioned in the same answer."
            }
          ],
          "citations": [
            {
              "object": "citation",
              "snippet": "The adidas Adizero Boston 12 earns high marks as a marathon trainer...",
              "source_name": "Runner's World",
              "title": "The Best Running Shoes of 2026",
              "url": "https://www.runnersworld.com/gear/a20865766/best-running-shoes/"
            },
            {
              "object": "citation",
              "title": "The Best Running Shoes",
              "url": "https://www.nytimes.com/wirecutter/reviews/best-running-shoes/"
            }
          ],
          "created_at": "2026-04-01T11:42:11.117+00:00",
          "id": "018e7c30-33ab-7df1-b1cd-2ac3a8f9112d",
          "model_version": "gpt-6-luna",
          "object": "report_result",
          "prompt_id": "018e7c2c-33ab-7df1-b1cd-2ac3a8f9112d",
          "rank": 2,
          "response": "For a first marathon, the adidas Adizero Boston 12 is frequently recommended alongside ..."
        }
      ]
    }
  ],
  "ranked_prompts": 17,
  "region_config_id": "018e7c2e-33ab-7df1-b1cd-2ac3a8f9112d",
  "status": "completed",
  "total_results": 60,
  "visibility_score": 42.7
}

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/reports/your_report_id_here?include_responses=true&dry_run=false' \
  --header 'Authorization: Bearer rp_live_<YOUR_API_KEY>'

const fetch = require('node-fetch');

const url = 'https://api.rankprompt.com/v1/reports/your_report_id_here?include_responses=true&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/reports/your_report_id_here"

querystring = {"include_responses":"true","dry_run":"false"}

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

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

print(response.json())