Run a visibility check

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

Authorization

AuthorizationBearer token · headerrequired

API key sent as Authorization: Bearer <key>. A key belongs to one workspace, has scopes, and can be limited to some brands.

AuthorizationOAuth2 access token · headerrequired

OAuth 2.1 sign-in (authorization code with PKCE) used by AI assistants that connect through the Zaraftis MCP server. Discovery URLs are at https://api.zaraftis.com/api/auth.

Header parameters

Idempotency-Keystringrequired

A new value, such as a UUID, for each new request. Send the same value to retry a request safely; see https://docs.zaraftis.com/conventions#safe-retries-with-idempotency-key.

min length 1 · max length 64

Request body

requiredapplication/json

Any of:

object

setup_idstring<uuid>required

matches ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$

prompt_selectionobject

Show properties

Any of:

object

modestringrequired

object

modestringrequired

prompt_idsstring<uuid>[]required

min items 1 · max items 150

platform_selectionobject

Show properties

Any of:

object

modestringrequired

object

modestringrequired

platform_idsstring[]required

min items 1 · max items 20

response_detailstring

Allowed:compactdetailed

object

brand_idstring<uuid>required

matches ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$

countrystringrequired

min length 2 · max length 2

languagestringrequired

min length 2 · max length 10

platform_idsstring[]required

min items 1 · max items 12

promptsobject[]required

min items 1 · max items 150

Show properties

Array of object

textstringrequired

min length 1 · max length 500

topic_titlestring | null

Show properties

Any of:

string

string

null

null

competitorsobject[]

max items 20

Show properties

Array of object

namestringrequired

min length 1 · max length 200

urlstring<uri>required

response_detailstring

Allowed:compactdetailed

object

new_brandobjectrequired

Show properties

urlstring<uri>required

namestring | null

Show properties

Any of:

string

string

null

null

aliasesstring[]

max items 50

countrystring

min length 2 · max length 2

languagestring

min length 2 · max length 10

countrystringrequired

min length 2 · max length 2

languagestringrequired

min length 2 · max length 10

platform_idsstring[]required

min items 1 · max items 12

promptsobject[]required

min items 1 · max items 150

Show properties

Array of object

textstringrequired

min length 1 · max length 500

topic_titlestring | null

Show properties

Any of:

string

string

null

null

competitorsobject[]

max items 20

Show properties

Array of object

namestringrequired

min length 1 · max length 200

urlstring<uri>required

response_detailstring

Allowed:compactdetailed

Responses

200

Completed check (compact projection; observations added with response_detail detailed)

successbooleanrequired

dataVisibilityCheckObjectrequired

Show properties

scan_idstring<uuid>required

matches ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$

brand_idstring<uuid>required

matches ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$

brand_namestringrequired

min length 1

statusstringrequired

Allowed:queuedrunningcompletedfailed

triggered_bystring | nullrequired

Show properties

Any of:

string

string

null

null

created_atstring<date-time>required

matches ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d:[0-5]\d(?:\.\d+)?(?:Z))$

completed_atstring<date-time> | nullrequired

Show properties

Any of:

string<date-time>

string<date-time>

null

null

countrystringrequired

min length 2 · max length 2

languagestringrequired

min length 2 · max length 10

platformsstring[]required

prompt_countinteger | nullrequired

Show properties

Any of:

integer

integer

null

null

requestedinteger | nullrequired

Show properties

Any of:

integer

integer

null

null

completedinteger | nullrequired

Show properties

Any of:

integer

integer

null

null

failedintegerrequired

min 0 · max 9007199254740991

setup_idstring<uuid> | nullrequired

Show properties

Any of:

string<uuid>

string<uuid>

null

null

setup_version_idstring<uuid> | nullrequired

Show properties

Any of:

string<uuid>

string<uuid>

null

null

setup_checksumstring | nullrequired

Show properties

Any of:

string

string

null

null

metricsScanMetricsFieldMaprequired

started_atstring<date-time> | nullrequired

Show properties

Any of:

string<date-time>

string<date-time>

null

null

error_messagestring | nullrequired

task_idstring<uuid> | nullrequired

Show properties

Any of:

string<uuid>

string<uuid>

null

null

task_urlstring | nullrequired

Show properties

Any of:

string

string

null

null

billingBillingObject | nullrequired

Show properties

Any of:

BillingObject

operationstringrequired

Allowed:ai_platform_querysite_auditauto_visibility_setup

credit_catalog_versionstringrequired

min length 1

quantity_requestedintegerrequired

min 0 · max 9007199254740991

unit_creditsinteger | nullrequired

Show properties

Any of:

integer

integer

null

null

maximum_creditsintegerrequired

min 0 · max 9007199254740991

reserved_creditsintegerrequired

min 0 · max 9007199254740991

billing_statusstringrequired

Allowed:reserveddeductedreleased

credits_deductedinteger

min 0 · max 9007199254740991

credits_releasedinteger

min 0 · max 9007199254740991

wallet_history_idstring | nullrequired

Show properties

Any of:

string

string

null

null

null

null

observationsObservationItem[]

Show properties

Array of ObservationItem

observation_idstring<uuid>required

matches ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$

prompt_idstring<uuid>required

matches ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$

prompt_textstringrequired

min length 1

platformstringrequired

min length 1

countrystringrequired

min length 2 · max length 2

languagestringrequired

min length 2 · max length 10

answer_typestringrequired

Allowed:normalrefusal

collected_atstring<date-time>required

brandobjectrequired

Show properties

mentionedbooleanrequired

citedbooleanrequired

mention_positioninteger | nullrequired

Show properties

Any of:

integer

integer

null

null

sentimentstring | nullrequired

Show properties

Any of:

string

string

null

null

mention_countintegerrequired

min 0 · max 9007199254740991

citation_countintegerrequired

min 0 · max 9007199254740991

mentionsBrandMentionItem[]required

Show properties

Array of BrandMentionItem

name_in_answerstringrequired

min length 1

brand_namestringrequired

min length 1

brand_typestringrequired

min length 1

url_in_answerstring | nullrequired

Show properties

Any of:

string

string

null

null

request_idstringrequired

min length 1

202

Accepted check continuing in background

successbooleanrequired

dataAcceptedScanObjectrequired

Show properties

scan_idstring<uuid>required

matches ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$

brand_idstring<uuid>required

matches ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$

statusstringrequired

Allowed:queuedrunningcompletedpartialcancelledfailed

status_urlstringrequired

min length 1

task_idstring<uuid> | nullrequired

Show properties

Any of:

string<uuid>

string<uuid>

null

null

task_urlstring | nullrequired

Show properties

Any of:

string

string

null

null

setupobjectrequired

Show properties

setup_idstring<uuid> | nullrequired

Show properties

Any of:

string<uuid>

string<uuid>

null

null

setup_version_idstring<uuid> | nullrequired

Show properties

Any of:

string<uuid>

string<uuid>

null

null

setup_checksumstring | nullrequired

Show properties

Any of:

string

string

null

null

requested_query_countintegerrequired

min 0 · max 9007199254740991

queriesobjectrequired

Show properties

requestedintegerrequired

min 0 · max 9007199254740991

completedintegerrequired

min 0 · max 9007199254740991

failedintegerrequired

min 0 · max 9007199254740991

skippedintegerrequired

min 0 · max 9007199254740991

billingBillingObject | nullrequired

Show properties

Any of:

BillingObject

operationstringrequired

Allowed:ai_platform_querysite_auditauto_visibility_setup

credit_catalog_versionstringrequired

min length 1

quantity_requestedintegerrequired

min 0 · max 9007199254740991

unit_creditsinteger | nullrequired

Show properties

Any of:

integer

integer

null

null

maximum_creditsintegerrequired

min 0 · max 9007199254740991

reserved_creditsintegerrequired

min 0 · max 9007199254740991

billing_statusstringrequired

Allowed:reserveddeductedreleased

credits_deductedinteger

min 0 · max 9007199254740991

credits_releasedinteger

min 0 · max 9007199254740991

wallet_history_idstring | nullrequired

Show properties

Any of:

string

string

null

null

null

null

request_idstringrequired

min length 1

400

bad_request or validation_failed

successbooleanrequired

errorobjectrequired

Show properties

codestringrequired

messagestringrequired

retryablebooleanrequired

detailsobject

field_errorsobject[]

Show properties

Array of object

fieldstringrequired

codestringrequired

Allowed:requiredformattoo_smalltoo_largeunrecognized_keyinvalid

messagestringrequired

request_idRequestIdrequired

402

wallet_not_activated, insufficient_credits, or payment_action_required

successbooleanrequired

errorobjectrequired

Show properties

codestringrequired

messagestringrequired

retryablebooleanrequired

detailsobject

field_errorsobject[]

Show properties

Array of object

fieldstringrequired

codestringrequired

Allowed:requiredformattoo_smalltoo_largeunrecognized_keyinvalid

messagestringrequired

request_idRequestIdrequired

409

conflict, duplicate_url, or idempotency_conflict

successbooleanrequired

errorobjectrequired

Show properties

codestringrequired

messagestringrequired

retryablebooleanrequired

detailsobject

field_errorsobject[]

Show properties

Array of object

fieldstringrequired

codestringrequired

Allowed:requiredformattoo_smalltoo_largeunrecognized_keyinvalid

messagestringrequired

request_idRequestIdrequired

429

rate_limited: wait the Retry-After seconds

successbooleanrequired

errorobjectrequired

Show properties

codestringrequired

messagestringrequired

retryablebooleanrequired

detailsobject

field_errorsobject[]

Show properties

Array of object

fieldstringrequired

codestringrequired

Allowed:requiredformattoo_smalltoo_largeunrecognized_keyinvalid

messagestringrequired

request_idRequestIdrequired

Request

curl -X POST 'https://api.zaraftis.com/v1/visibility/checks' \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  -H 'Idempotency-Key: string' \
  -H 'Accept: application/json' \
  -H 'Content-Type: application/json' \
  -d '{
  "setup_id": "223e7533-659b-4438-b6f4-f841a5d7dfa9",
  "prompt_selection": {
    "mode": "all"
  },
  "platform_selection": {
    "mode": "all"
  },
  "response_detail": "compact"
}'

const response = await fetch("https://api.zaraftis.com/v1/visibility/checks", {
  method: "POST",
  headers: {
    "Authorization": "Bearer YOUR_TOKEN",
    "Idempotency-Key": "string",
    "Accept": "application/json",
    "Content-Type": "application/json"
  },
  body: "{\n  \"setup_id\": \"223e7533-659b-4438-b6f4-f841a5d7dfa9\",\n  \"prompt_selection\": {\n    \"mode\": \"all\"\n  },\n  \"platform_selection\": {\n    \"mode\": \"all\"\n  },\n  \"response_detail\": \"compact\"\n}"
});

import requests

response = requests.post(
    "https://api.zaraftis.com/v1/visibility/checks",
    headers={
        "Authorization": "Bearer YOUR_TOKEN",
        "Idempotency-Key": "string",
        "Accept": "application/json",
        "Content-Type": "application/json"
    },
    data="{\n  \"setup_id\": \"223e7533-659b-4438-b6f4-f841a5d7dfa9\",\n  \"prompt_selection\": {\n    \"mode\": \"all\"\n  },\n  \"platform_selection\": {\n    \"mode\": \"all\"\n  },\n  \"response_detail\": \"compact\"\n}",
)

Response

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

{
  "success": true,
  "data": {
    "scan_id": "9a59f0f5-5572-476d-a7fc-c960ef43a5af",
    "brand_id": "1bb61461-e5e3-4ebb-8cc6-5b0c37f1b7da",
    "status": "queued",
    "status_url": "string",
    "task_id": "736fde4d-9029-4915-8189-01353d6982cb",
    "task_url": "string",
    "setup": {
      "setup_id": "223e7533-659b-4438-b6f4-f841a5d7dfa9",
      "setup_version_id": "46e86b42-ef3c-4109-b8e4-2fc5ae51285c",
      "setup_checksum": "string"
    },
    "requested_query_count": 0,
    "queries": {
      "requested": 0,
      "completed": 0,
      "failed": 0,
      "skipped": 0
    },
    "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"
    }
  },
  "request_id": "string"
}

{
  "success": false,
  "error": {
    "code": "string",
    "message": "string",
    "retryable": true,
    "details": {},
    "field_errors": [
      {
        "field": "string",
        "code": "required",
        "message": "string"
      }
    ]
  },
  "request_id": "string"
}

{
  "success": false,
  "error": {
    "code": "string",
    "message": "string",
    "retryable": true,
    "details": {},
    "field_errors": [
      {
        "field": "string",
        "code": "required",
        "message": "string"
      }
    ]
  },
  "request_id": "string"
}

{
  "success": false,
  "error": {
    "code": "string",
    "message": "string",
    "retryable": true,
    "details": {},
    "field_errors": [
      {
        "field": "string",
        "code": "required",
        "message": "string"
      }
    ]
  },
  "request_id": "string"
}

{
  "success": false,
  "error": {
    "code": "string",
    "message": "string",
    "retryable": true,
    "details": {},
    "field_errors": [
      {
        "field": "string",
        "code": "required",
        "message": "string"
      }
    ]
  },
  "request_id": "string"
}