POST /v1/brands/{brand_id}/audits

Run a brand audit

scope write:brand-audits cost 8 RU · 10 credits rate-limit 10/minute · key idempotent required

Run a new AI-visibility brand audit for a market (country + language). The audit runs the analysis inline and can take a while, so allow a long timeout. Costs credits, charged to the account this API key belongs to. Returns the completed audit.

Path parameters

brand_idstring required
Brand UUID.

Header parameters

Idempotency-Keystring optional

Request body

application/json required

Type:BrandAuditCreate

countrystringrequired
Country to audit visibility for (e.g. United States).

min length: 1 · max length: 100
languagestringrequired
Language to run the audit in (e.g. English).

min length: 1 · max length: 50
locationstring (nullable)nullable
Optional finer-grained location within the country.

Responses

Run a brand auditapplication/json

Type:BrandAudit

brand_idstringrequired
Owning brand id (UUID).
countrystringrequired
Country the audit was run for.
created_atstringrequired
When the audit was created.

format: `date-time`
idstringrequired
Brand audit id (UUID).
languagestringrequired
Language the audit prompt was run in.
promptstringrequired
Generated brand-visibility prompt sent to the AI platforms.
statusenumrequired
Audit lifecycle state. One of processing, completed, failed.
citation_analysisobject (nullable)nullable
Per-page citation analysis rollup, when any pages have been analyzed.
error_messagestring (nullable)nullable
User-facing failure reason when status is failed.
key_themesobject | array of any
Recurring themes detected across AI responses.
knowledge_resultsobject (nullable)nullable
Per-platform knowledge (no-web-search) results (keyed by provider).
locationstring (nullable)nullable
Optional finer-grained location.
objectstring
Always brand_audit.

default: `brand_audit`
recommendationsobject (nullable)nullable
Generated recommendations payload, when recommendations have been produced.
reputation_knowledge_resultsobject (nullable)nullable
Per-platform reputation knowledge results (keyed by provider).
reputation_promptstring (nullable)nullable
Generated brand-reputation prompt, when a reputation pass was run.
reputation_web_search_resultsobject (nullable)nullable
Per-platform reputation web-search results (keyed by provider).
updated_atstring (nullable)nullable
When the audit row was last updated.

format: `date-time`
web_search_resultsobject (nullable)nullable
Per-platform web-search results (keyed by provider).

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

Not enough credits to complete this operationapplication/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": "insufficient_credits",
    "message": "Not enough credits to complete this operation"
  },
  "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"
}

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/brands/your_brand_id_here/audits \
  --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/brands/your_brand_id_here/audits';
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/brands/your_brand_id_here/audits"

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())