GET /v1/reports/{report_id}

Retrieve a report

scope read:reports cost 3 RU idempotent required

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.

Path parameters

report_idstring required
Report UUID.

Header parameters

Idempotency-Keystring optional

Responses

Returned a reportapplication/json

Type:ReportDetail

brand_idstringrequired
Owning brand id (UUID).
created_atstringrequired
ISO-8601 timestamp when the report was created.

format: `date-time`
idstringrequired
Stable report identifier (UUID).
namestringrequired
Human-readable report label (defaults to Untitled Report).
statusenumrequired
Report lifecycle status.
ai_platformsarray of string
AI platforms the report runs against. Standard tier (bundled, 1 credit per prompt total): chatgpt, perplexity, ai_overviews, claude. Premium tier (1 credit per platform per prompt, additive): chatgpt_search, claude_search, gemini, grok.
batch_idstring (nullable)nullable
Batch id grouping reports from the same scheduled run; null for manual runs.
countrystring (nullable)nullable
Country the report was scoped to.
failure_reasonstring (nullable)nullable
Human-readable reason when status == 'failed'.
languagestring (nullable)nullable
Primary language (English name like English, Spanish).
locationstring (nullable)nullable
Free-form location string used for queries.
objectstring
Always report.

default: `report`
promptsarray 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_promptsinteger
Prompt-platform results that surfaced the brand. Always ≤ total_results.

min: 0 · default: `0`
region_config_idstring (nullable)nullable
Region configuration used for this report, when applicable.
scheduled_report_idstring (nullable)nullable
Schedule id when the report was triggered by a schedule; null for manual runs.
total_resultsinteger
Total prompt-platform results materialised by the run

min: 0 · default: `0`
visibility_scorenumber (nullable)nullable
Aggregate brand visibility score (0-100). Null until the report completes.

Example response

{
  "ai_platforms": [
    "chatgpt",
    "perplexity"
  ],
  "brand_id": "3f9c7e8a-1b6a-4d8e-92cf-7d9c8b1e2a04",
  "country": "United States",
  "created_at": "2024-09-01T11:00:00.000Z",
  "id": "8a72d9f1-c4b5-4e6d-9b1f-0e3a2c6d8b04",
  "language": "en",
  "location": "United States",
  "name": "Acme weekly visibility, Sept 2024",
  "object": "report",
  "prompts": [
    {
      "brand_id": "3f9c7e8a-1b6a-4d8e-92cf-7d9c8b1e2a04",
      "category": "Specialty Coffee",
      "created_at": "2026-04-01T11:00:00.000Z",
      "id": "018e7c2c-33ab-7df1-b1cd-2ac3a8f9112d",
      "object": "prompt",
      "prompt_text": "What are the best specialty coffee roasters in Brooklyn?",
      "report_id": "8a72d9f1-c4b5-4e6d-9b1f-0e3a2c6d8b04",
      "results": [
        {
          "ai_platform": "chatgpt",
          "brand_appears": true,
          "businesses_categorized": [
            {
              "category": "direct_competitor",
              "name": "Devocion",
              "object": "business_categorized",
              "reason": "Specialty coffee roaster in Brooklyn frequently cited alongside the brand."
            },
            {
              "category": "indirect_competitor",
              "name": "Sey",
              "object": "business_categorized",
              "reason": "Roaster mentioned in the same answer."
            }
          ],
          "created_at": "2026-04-01T11:42:11.117Z",
          "id": "018e7c30-33ab-7df1-b1cd-2ac3a8f9112d",
          "object": "report_result",
          "prompt_id": "018e7c2c-33ab-7df1-b1cd-2ac3a8f9112d",
          "rank": 2,
          "response": "For specialty coffee roasters in Brooklyn, Acme Coffee Roasters is frequently cited alongside ...",
          "sources": [
            "https://example.com/best-roasters-brooklyn",
            "https://example.com/specialty-coffee-guide"
          ]
        }
      ]
    }
  ],
  "ranked_prompts": 17,
  "region_config_id": "018e7c2e-33ab-7df1-b1cd-2ac3a8f9112d",
  "status": "completed",
  "total_results": 60,
  "visibility_score": 42.7
}

Request validation failedapplication/json

Type:ApiError

errorobjectrequired
Show fields
- codestringrequired
  Stable machine-readable error code from the catalog.
- messagestringrequired
  Human-readable description suitable for logging.
- detailsobject
  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_idstring
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 credentialsapplication/json

Type:ApiError

errorobjectrequired
Show fields
- codestringrequired
  Stable machine-readable error code from the catalog.
- messagestringrequired
  Human-readable description suitable for logging.
- detailsobject
  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_idstring
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 resourceapplication/json

Type:ApiError

errorobjectrequired
Show fields
- codestringrequired
  Stable machine-readable error code from the catalog.
- messagestringrequired
  Human-readable description suitable for logging.
- detailsobject
  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_idstring
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 foundapplication/json

Type:ApiError

errorobjectrequired
Show fields
- codestringrequired
  Stable machine-readable error code from the catalog.
- messagestringrequired
  Human-readable description suitable for logging.
- detailsobject
  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_idstring
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 conflictapplication/json

Type:ApiError

errorobjectrequired
Show fields
- codestringrequired
  Stable machine-readable error code from the catalog.
- messagestringrequired
  Human-readable description suitable for logging.
- detailsobject
  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_idstring
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 exceededapplication/json

Type:ApiError

errorobjectrequired
Show fields
- codestringrequired
  Stable machine-readable error code from the catalog.
- messagestringrequired
  Human-readable description suitable for logging.
- detailsobject
  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_idstring
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 occurredapplication/json

Type:ApiError

errorobjectrequired
Show fields
- codestringrequired
  Stable machine-readable error code from the catalog.
- messagestringrequired
  Human-readable description suitable for logging.
- detailsobject
  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_idstring
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 retryapplication/json

Type:ApiError

errorobjectrequired
Show fields
- codestringrequired
  Stable machine-readable error code from the catalog.
- messagestringrequired
  Human-readable description suitable for logging.
- detailsobject
  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_idstring
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 \
  --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/reports/your_report_id_here';
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/reports/your_report_id_here"

headers = {
    "Authorization": "Bearer rp_live_<YOUR_API_KEY>",
    "Idempotency-Key": "<UNIQUE_KEY>"
}

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

print(response.json())