API docs v1
GET /v1/reports

List reports

scope read:reports cost 1 RU idempotent required

List reports under a brand (newest first). Cursor-paginated.

Filters compose with AND: status, search (case-insensitive on name), scheduled_report_id, batch_id.

Query parameters

  • statusstring optional

    Filter by report lifecycle status.

  • scheduled_report_idstring optional

    Filter to reports generated by a specific schedule (UUID).

  • batch_idstring optional

    Filter to reports from a specific scheduled-run batch (UUID).

  • limitinteger optional

    Page size (default 20, max 100).

    default: 20

  • cursorstring optional

    Continuation token from a previous response's next_cursor.

  • brand_idstring required

    Brand UUID to scope the listing.

Header parameters

Responses

Returned reportsapplication/json
Type:ReportList
  • dataarray of Reportrequired
  • has_morebooleanrequired
  • next_cursorstring (nullable)nullable

    Opaque continuation token. Pass back as ?cursor= to fetch the next page. null when has_more is false.

  • objectstring

    default: `list`

Example response 
{
  "data": [
    {
      "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
    }
  ],
  "has_more": false,
  "object": "list"
}
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"
}
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"
}