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

  • Idempotency-Key string required

    Required with an API key, else 400 idempotency_key_required: a new value per operation (a UUID works). A retry with the same key and body within 24 hours replays the first response instead of running again. Ignored with dry_run=true.

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. Engines: chatgpt, claude, ai_overviews, grok, perplexity, gemini. Each prompt costs 1 credit per 3 engines, rounded up: 1 to 3 engines cost 1 credit, 4 to 6 cost 2. Any other value, retired ones included (chatgpt_search, claude_search), answers ai_platform_unsupported. Defaults to ["chatgpt", "claude", "ai_overviews"], or to the region config's engines when region_config_id is set (a retired engine there runs as its replacement).

  • 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). The report takes the config's market: any of country, location, language and ai_platforms you leave out comes from the config.

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. 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.

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