---
search:
  tags:
    - Visibility
    - POST
seo:
  description: >-
    Measures one prompt on one or more platforms and waits for the answers.…
    Reference for the POST /visibility/checks endpoint in the Zaraftis Public
    API.
sidebar:
  label: Run a visibility check
  badge: POST
title: Run a visibility check
type: openapi-operation
---
Measures one prompt on one or more platforms and waits for the answers. Returns 200 with the result when every query finishes within the sync deadline (checks_sync_deadline_seconds in GET /v1/capabilities). Otherwise returns 202 with the scan, task, and billing references while the work continues. Both carry task_id and task_url. A retry with the same Idempotency-Key never starts or charges the check again.

`POST /visibility/checks`

**Request body** (`application/json`, required)

Request body example:

```json
{
  "setup_id": "223e7533-659b-4438-b6f4-f841a5d7dfa9",
  "prompt_selection": {
    "mode": "all"
  },
  "platform_selection": {
    "mode": "all"
  },
  "response_detail": "compact"
}
```

**Responses**

- `200` — Completed check (compact projection; observations added with response\_detail detailed)
- `202` — Accepted check continuing in background
- `400` — bad\_request or validation\_failed
- `402` — wallet\_not\_activated, insufficient\_credits, or payment\_action\_required
- `409` — conflict, duplicate\_url, or idempotency\_conflict
- `429` — rate\_limited: wait the Retry-After seconds

Response example, 200:

```json
{
  "success": true,
  "data": {
    "scan_id": "9a59f0f5-5572-476d-a7fc-c960ef43a5af",
    "brand_id": "1bb61461-e5e3-4ebb-8cc6-5b0c37f1b7da",
    "brand_name": "string",
    "status": "queued",
    "triggered_by": "string",
    "created_at": "2019-08-24T14:15:22Z",
    "completed_at": "2019-08-24T14:15:22Z",
    "country": "st",
    "language": "string",
    "platforms": [
      "string"
    ],
    "prompt_count": 0,
    "requested": 0,
    "completed": 0,
    "failed": 0,
    "setup_id": "223e7533-659b-4438-b6f4-f841a5d7dfa9",
    "setup_version_id": "46e86b42-ef3c-4109-b8e4-2fc5ae51285c",
    "setup_checksum": "string",
    "metrics": {
      "property1": {
        "value": 0,
        "quality": "complete",
        "method_version": "string"
      },
      "property2": {
        "value": 0,
        "quality": "complete",
        "method_version": "string"
      }
    },
    "started_at": "2019-08-24T14:15:22Z",
    "error_message": "string",
    "task_id": "736fde4d-9029-4915-8189-01353d6982cb",
    "task_url": "string",
    "billing": {
      "operation": "ai_platform_query",
      "credit_catalog_version": "string",
      "quantity_requested": 0,
      "unit_credits": 0,
      "maximum_credits": 0,
      "reserved_credits": 0,
      "billing_status": "reserved",
      "credits_deducted": 0,
      "credits_released": 0,
      "wallet_history_id": "string"
    },
    "observations": [
      {
        "observation_id": "d5b663f3-1b87-4f94-9f66-dbd8d5553132",
        "prompt_id": "24783230-27c2-455c-9de9-95bbdbb78c3d",
        "prompt_text": "string",
        "platform": "string",
        "country": "st",
        "language": "string",
        "answer_type": "normal",
        "collected_at": "2019-08-24T14:15:22Z",
        "brand": {
          "mentioned": true,
          "cited": true,
          "mention_position": 1,
          "sentiment": "string"
        },
        "mention_count": 0,
        "citation_count": 0,
        "mentions": [
          {
            "name_in_answer": "string",
            "brand_name": "string",
            "brand_type": "string",
            "url_in_answer": "string"
          }
        ]
      }
    ]
  },
  "request_id": "string"
}
```