AI Visibility API

The AI Visibility API exports the latest stored platform responses for one Wheremore buyer configuration.

Endpoints

POST https://app.wheremore.com/api/v2/exports/visibility
GET  https://app.wheremore.com/api/v2/exports/{export_id}

POST is free. The first successful GET costs 0.5 credits per returned conversation containing responses. Repeat GETs return the same immutable export for free. Exports expire after seven days.

Authentication and idempotency

Send X-API-Key: sk_live_...  or Authorization: Bearer sk_live_... .

Every POST requires an Idempotency-Key . Retry the identical POST with the same key to receive the same export ID; use a new key for a different logical export. Unknown JSON fields are rejected.

JSON fields

Provide exactly one of config_id  or config_name .

Supported platform  identifiers are:

• chatgpt , chatgpt-web , chatgpt-adaptive
• claude , claude-web , claude-adaptive
• gemini , gemini-web , gemini-adaptive
• perplexity , perplexity-web , perplexity-adaptive
• google-ai-mode

Omit platform  or phase  to include all saved values available in the selected configuration.

Create the export

curl -X POST "https://app.wheremore.com/api/v2/exports/visibility" \
  -H "X-API-Key: sk_live_your_key_here" \
  -H "Idempotency-Key: visibility-export-2026-08-25-001" \
  -H "Content-Type: application/json" \
  -d '{
    "workspace_id": "ws_your_workspace_id",
    "config_id": 42,
    "platform": "google-ai-mode",
    "phase": "consideration"
  }'

HTTP 201 means the immutable snapshot is ready. HTTP 202 means it is pending. POST never consumes credits.

Retrieve the export

curl "https://app.wheremore.com/api/v2/exports/exp_0123456789abcdef0123456789abcdef" \
  -H "X-API-Key: sk_live_your_key_here"

A pending GET returns HTTP 202 for free. A ready GET returns HTTP 200. The first retrieval charges for the number of conversations in the saved payload. Later GETs return identical data with billing_status: "already_deducted"  and credits_used: 0 .

An optional callback contains only export-ready metadata, never AI response data.

Response

{
  "success": true,
  "export": {
    "id": "exp_0123456789abcdef0123456789abcdef",
    "type": "visibility",
    "status": "ready",
    "created_at": "2026-08-25T18:00:00Z",
    "ready_at": "2026-08-25T18:00:00Z",
    "expires_at": "2026-09-01T18:00:00Z",
    "status_url": "/api/v2/exports/exp_0123456789abcdef0123456789abcdef"
  },
  "credits_used": 0.5,
  "balance": 999.5,
  "billing_status": "deducted",
  "data": {
    "workspace_id": "ws_your_workspace_id",
    "config_name": "CMO — SaaS, B2B, E-commerce",
    "config_id": 26,
    "filters": {
      "platform": "chatgpt-web",
      "phase": "consideration"
    },
    "conversations": [
      {
        "conversation_id": 1001,
        "query": "Which platforms should a UK CMO compare?",
        "phase": "consideration",
        "responses": [
          {
            "platform": "chatgpt-web",
            "text": "Example monitored response",
            "date": "2026-07-26",
            "recorded_at": "2026-07-26T09:30:00Z",
            "citations": [
              {
                "title": "Example source",
                "url": "https://example.org/source",
                "snippet": "Supporting source extract"
              }
            ]
          }
        ]
      }
    ],
    "total_conversations": 1
  },
  "meta": {
    "request_id": "req_example",
    "api_version": "v2",
    "data_contract": "2026-08-25",
    "duration_ms": 140.79
  }
}

Response objects can include further stored analysis and provider metadata. Build integrations to tolerate additional fields under future data-contract versions.

Interpreting the data

• A conversation is one monitored question associated with the configuration.
• responses  contains the latest matching saved response records for the selected platform scope.
• phase  describes the conversation’s customer-journey phase.
• A citation is reported only when the saved platform result contains one.
• Citation URLs can be provider redirect URLs where that is what the provider returned.
• A missing citation does not prove that the answer was unsupported; it means no usable citation was saved for that response.
• Platform answers can vary between runs even when the monitored question is unchanged.

Cost control

The endpoint costs 0.5 credits per returned conversation. To make an export smaller:

• Select one platform .
• Select one customer-journey phase .
• Create separate exports for distinct reporting needs.

The first paid response reports total_conversations , credits_used  and the remaining shared balance. Repeat GETs return balance: null  so a historic balance is not mistaken for the current ledger.

Important limitations

• The endpoint returns stored monitoring results, not a live AI request.
• Results depend on the configuration’s selected conversations, platforms and processing schedule.
• Disabled configurations are not newly scheduled.
• Edited questions and context affect future monitoring; completed historical records remain historical.
• Deleted or archived configuration content may no longer be available through the active configuration scope.
• Search-enabled and non-search platform variants are different identifiers.
• Provider citations, response structure and availability differ by platform.
• An AI mention, recommendation or citation is evidence from the monitored output, not proof of buyer behaviour or commercial impact.
• Workspace access is checked again whenever the saved export is retrieved.

Errors

Troubleshooting

The configuration is not found

• Confirm its project belongs to the supplied workspace.
• Prefer config_id .
• Confirm the configuration has not been deleted.
• Copy the public ws_...  workspace ID from API Access.

The configuration name is ambiguous

More than one configuration in the workspace has the same case-insensitive name. Use config_id .

No completed responses match

• Remove the platform  or phase  filter temporarily.
• Confirm the selected platform is enabled in the configuration.
• Confirm the conversation belongs to the selected phase.
• Allow the scheduled monitoring and raw-response processing to finish.
• Confirm the configuration is active.

The charge is higher than expected

The charge is based on returned conversations, not platform-response rows. Narrow the request with platform  and phase .

Citations are absent or use redirect links

Citation data reflects what the provider supplied and what Wheremore stored. Some search platforms return opaque redirect URLs, and some responses contain no citations.

A repeat retrieval

Repeat GET requests return the same saved responses for free with billing_status: "already_deducted"  and balance: null .

Security

• Keep API keys server-side and out of URLs.
• Store keys in a protected secret manager.
• Revoke exposed or unused keys.
• Accept callbacks only over HTTPS.
• Validate the callback event , workspace and configuration before retrieving.
• Make callback processing idempotent because delivery can be retried.
• Escape response text and validate citation URLs before displaying them in another interface.