POST /v1/reports

Create a report

scope write:reports cost 2 RU idempotent required

Create a report in draft status. No analysis is dispatched yet, so you can edit prompts before spending credits.

Workflow: 0. Required before step 3: POST /v1/brands/{brand_id}/facts to research the brand asynchronously, or PATCH /v1/brands/{brand_id}/facts with {"description": "..."} to set them manually.

POST /v1/reports (this endpoint): returns a draft.
POST /v1/reports/{id}/prompts: seed prompts (manual or auto-generated).
POST /v1/reports/{id}/runs: dispatch the analysis (returns job_id).
GET /v1/jobs/{job_id}: poll until completed.
GET /v1/reports/{id}: read the final report (prompts + results inlined).

Requires the brand to have name and website set; returns 422 validation_error otherwise.

Header parameters

Idempotency-Keystring optional

Request body

application/json required

Type:ReportCreate

brand_idstringrequired
Brand to attach the report to (UUID).
ai_platformsarray of enum (nullable)nullable
AI platforms to query. 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. Defaults to the brand's configured platforms.
countrystring (nullable)nullable
Country the report targets.
languagestring (nullable)nullable
Primary language. Accepts English name (English) or ISO 639-1 code (en).
locationstring (nullable)nullable
namestring (nullable)nullable
Optional human-readable report name. Defaults to <brand_name> Report.
region_config_idstring (nullable)nullable
Optional region configuration to associate (UUID).

Responses

Draft report created.application/json

Type:Report

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`
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",
  "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 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"
}

Request body did not match the expected schemaapplication/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": "body_validation_error",
    "message": "Request body did not match the expected schema"
  },
  "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 POST \
  --url https://api.rankprompt.com/v1/reports \
  --header 'Authorization: Bearer rp_live_<YOUR_API_KEY>' \
  --header 'Content-Type: application/json' \
  --header 'Idempotency-Key: <UNIQUE_KEY>' \
  --data '{}'

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

const url = 'https://api.rankprompt.com/v1/reports';
const options = {
  method: 'POST',
  headers: {
    Authorization: 'Bearer rp_live_<YOUR_API_KEY>',
    'Idempotency-Key': '<UNIQUE_KEY>',
    'Content-Type': 'application/json'
  },
  body: '{}'
};

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"

payload = {}
headers = {
    "Authorization": "Bearer rp_live_<YOUR_API_KEY>",
    "Idempotency-Key": "<UNIQUE_KEY>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.json())