API docs v1
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.

  1. POST /v1/reports (this endpoint): returns a draft.
  2. POST /v1/reports/{id}/prompts: seed prompts (manual or auto-generated).
  3. POST /v1/reports/{id}/runs: dispatch the analysis (returns job_id).
  4. GET /v1/jobs/{job_id}: poll until completed.
  5. 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.

Query parameters

  • 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

Header parameters

Request body

application/json required
Type: ReportCreate
  • brand_id string required

    Brand to attach the report to (UUID).

  • ai_platforms array 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 ["chatgpt", "perplexity"] — the same set the run is billed for, and the set recorded on the created report.

  • country string (nullable) nullable

    Country the report targets.

  • language string (nullable) nullable

    Primary language. Accepts English name (English) or ISO 639-1 code (en).

  • location string (nullable) nullable

    Free-form location used to scope queries, e.g. New York, NY or California. More specific than country.

  • name string (nullable) nullable

    Optional human-readable report name. Defaults to <brand_name> Report.

  • region_config_id string (nullable) nullable

    Optional region configuration to associate (UUID).

Responses

Draft report created. application/json
Type: Report
  • 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. 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_id string (nullable) nullable

    Batch id grouping reports from the same scheduled run; null for manual runs.

  • 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`

  • 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",
    "perplexity"
  ],
  "brand_id": "3f9c7e8a-1b6a-4d8e-92cf-7d9c8b1e2a04",
  "cells_permanently_failed": 0,
  "country": "United States",
  "created_at": "2024-09-01T11:00:00.000Z",
  "degraded_cells_count": 0,
  "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 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 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"
}
Request body did not match the expected schema 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": "body_validation_error",
    "message": "Request body did not match the expected schema"
  },
  "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"
}