API Reference

Auto-generated

Ai Visibility

API reference for ai visibility endpoints.

Auto-generated

This page was generated from the OpenAPI spec. Runmake generate-docs to refresh after spec changes.

POST /api/v1/ai-visibility/check

POST

/api/v1/ai-visibility/check

Check brand visibility in AI answers (logged-out engines only)

Parameters

Name	Type	Required	Description
prompts	`string[]`	Required	Prompts
brand	`string`	Required	Brand
competitors	`string[]`	Optional	Competitors
engines	`string[]`	Required	Engines
country	`string`	Optional	country
runs_per_prompt	`integer`	Optional	Runs Per PromptDefault: `1`
brand_domains	`string[]`	Optional	Brand Domains
quote_only	`boolean`	Optional	Quote OnlyDefault: `False`
hard_cap_microcents	`integer`	Optional	hard_cap_microcents

Request Example

Bash

curl -X POST https://api.alterlab.io/api/v1/ai-visibility/check \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "prompts": [],
    "brand": "example_brand",
    "engines": []
  }'

Response Example

JSON

{
  "run_id": "example",
  "brand": "example",
  "status": "example",
  "answers": [],
  "aggregates": [],
  "total_cost_microcents": 0
}

POST /api/v1/ai-visibility/quote

POST

/api/v1/ai-visibility/quote

Quote an AI visibility check without running or billing it

Parameters

Name	Type	Required	Description
prompts	`string[]`	Required	Prompts
brand	`string`	Required	Brand
competitors	`string[]`	Optional	Competitors
engines	`string[]`	Required	Engines
country	`string`	Optional	country
runs_per_prompt	`integer`	Optional	Runs Per PromptDefault: `1`
brand_domains	`string[]`	Optional	Brand Domains
quote_only	`boolean`	Optional	Quote OnlyDefault: `False`
hard_cap_microcents	`integer`	Optional	hard_cap_microcents

Request Example

Bash

curl -X POST https://api.alterlab.io/api/v1/ai-visibility/quote \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "prompts": [],
    "brand": "example_brand",
    "engines": []
  }'

Response Example

JSON

{
  "brand": "example",
  "runs_per_prompt": 0,
  "quote": "example",
  "hard_cap_microcents": "example",
  "within_hard_cap": true
}

GET /api/v1/ai-visibility/runs/{run_id}

GET

/api/v1/ai-visibility/runs/{run_id}

Status and billing of an AI visibility run

Parameters

Name	Type	Required	Description
run_id	`string`	Required	run_id

Request Example

Bash

curl -X GET https://api.alterlab.io/api/v1/ai-visibility/runs/<run_id> \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json"

Response Example

JSON

{
  "run_id": "example",
  "brand": "example",
  "status": "example",
  "answers_total": 0,
  "answers_success": 0,
  "billing": "example"
}

GET /api/v1/ai-visibility/runs/{run_id}/results

GET

/api/v1/ai-visibility/runs/{run_id}/results

Stored answers of an AI visibility run

Parameters

Name	Type	Required	Description
run_id	`string`	Required	run_id

Request Example

Bash

curl -X GET https://api.alterlab.io/api/v1/ai-visibility/runs/<run_id>/results \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json"

Response Example

JSON

{
  "run_id": "example",
  "brand": "example",
  "status": "example",
  "answers": [],
  "aggregates": [],
  "total_cost_microcents": 0
}

POST /api/v1/ai-visibility/schedules

POST

/api/v1/ai-visibility/schedules

Create a recurring AI visibility check

Parameters

Name	Type	Required	Description
name	`string`	Required	Name
frequency	`"daily" \| "weekly"`	Optional	FrequencyDefault: `weekly`
config	`object`	Required	AIVisibilityCheckRequest
hard_cap_microcents	`integer`	Optional	hard_cap_microcents

Request Example

Bash

curl -X POST https://api.alterlab.io/api/v1/ai-visibility/schedules \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "example_name",
    "frequency": "...",
    "config": "..."
  }'

Response Example

JSON

{
  "status": "ok"
}

GET /api/v1/ai-visibility/schedules

GET

/api/v1/ai-visibility/schedules

List AI visibility schedules

Parameters

Name	Type	Required	Description
limit	`integer`	Optional	limitDefault: `20`
offset	`integer`	Optional	offsetDefault: `0`

Request Example

Bash

curl -X GET https://api.alterlab.io/api/v1/ai-visibility/schedules \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json"

Response Example

JSON

{
  "schedules": [],
  "total": 0
}

GET /api/v1/ai-visibility/schedules/{schedule_id}

GET

/api/v1/ai-visibility/schedules/{schedule_id}

Get an AI visibility schedule

Parameters

Name	Type	Required	Description
schedule_id	`string`	Required	schedule_id

Request Example

Bash

curl -X GET https://api.alterlab.io/api/v1/ai-visibility/schedules/<schedule_id> \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json"

Response Example

JSON

{
  "id": "example",
  "name": "example",
  "frequency": "example",
  "config": {},
  "hard_cap_microcents": "example",
  "is_active": true
}

PATCH /api/v1/ai-visibility/schedules/{schedule_id}

PATCH

/api/v1/ai-visibility/schedules/{schedule_id}

Update an AI visibility schedule

Parameters

Name	Type	Required	Description
schedule_id	`string`	Required	schedule_id
name	`string`	Optional	name
frequency	`"daily" \| "weekly"`	Optional	frequency
config	`object`	Optional	AIVisibilityCheckRequest
hard_cap_microcents	`integer`	Optional	hard_cap_microcents

Request Example

Bash

curl -X PATCH https://api.alterlab.io/api/v1/ai-visibility/schedules/<schedule_id> \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json"

Response Example

JSON

{
  "id": "example",
  "name": "example",
  "frequency": "example",
  "config": {},
  "hard_cap_microcents": "example",
  "is_active": true
}

DELETE /api/v1/ai-visibility/schedules/{schedule_id}

DELETE

/api/v1/ai-visibility/schedules/{schedule_id}

Delete an AI visibility schedule (history is kept)

Parameters

Name	Type	Required	Description
schedule_id	`string`	Required	schedule_id

Request Example

Bash

curl -X DELETE https://api.alterlab.io/api/v1/ai-visibility/schedules/<schedule_id> \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json"

Response Example

JSON

{
  "status": "ok"
}

POST /api/v1/ai-visibility/schedules/{schedule_id}/pause

POST

/api/v1/ai-visibility/schedules/{schedule_id}/pause

Pause an AI visibility schedule

Parameters

Name	Type	Required	Description
schedule_id	`string`	Required	schedule_id

Request Example

Bash

curl -X POST https://api.alterlab.io/api/v1/ai-visibility/schedules/<schedule_id>/pause \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json"

Response Example

JSON

{
  "id": "example",
  "name": "example",
  "frequency": "example",
  "config": {},
  "hard_cap_microcents": "example",
  "is_active": true
}

POST /api/v1/ai-visibility/schedules/{schedule_id}/resume

POST

/api/v1/ai-visibility/schedules/{schedule_id}/resume

Resume a paused AI visibility schedule

Parameters

Name	Type	Required	Description
schedule_id	`string`	Required	schedule_id

Request Example

Bash

curl -X POST https://api.alterlab.io/api/v1/ai-visibility/schedules/<schedule_id>/resume \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json"

Response Example

JSON

{
  "id": "example",
  "name": "example",
  "frequency": "example",
  "config": {},
  "hard_cap_microcents": "example",
  "is_active": true
}

POST /api/v1/ai-visibility/schedules/{schedule_id}/run

POST

/api/v1/ai-visibility/schedules/{schedule_id}/run

Run an AI visibility schedule now (next_run_at is unchanged)

Parameters

Name	Type	Required	Description
schedule_id	`string`	Required	schedule_id

Request Example

Bash

curl -X POST https://api.alterlab.io/api/v1/ai-visibility/schedules/<schedule_id>/run \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json"

Response Example

JSON

{
  "outcome": "example",
  "run_id": "example"
}

GET /api/v1/ai-visibility/schedules/{schedule_id}/runs

GET

/api/v1/ai-visibility/schedules/{schedule_id}/runs

Run history of an AI visibility schedule

Parameters

Name	Type	Required	Description
schedule_id	`string`	Required	schedule_id
limit	`integer`	Optional	limitDefault: `20`
offset	`integer`	Optional	offsetDefault: `0`

Request Example

Bash

curl -X GET https://api.alterlab.io/api/v1/ai-visibility/schedules/<schedule_id>/runs \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json"

Response Example

JSON

{
  "runs": [],
  "total": 0
}

GET /api/v1/ai-visibility/schedules/{schedule_id}/trend

GET

/api/v1/ai-visibility/schedules/{schedule_id}/trend

Mention rate and share of voice over time for a schedule

Parameters

Name	Type	Required	Description
schedule_id	`string`	Required	schedule_id
days	`integer`	Optional	daysDefault: `30`
engine	`"google_ai_overview" \| "google_ai_mode" \| "chatgpt" \| "perplexity" \| "gemini" \| "copilot"`	Optional	engine

Request Example

Bash

curl -X GET https://api.alterlab.io/api/v1/ai-visibility/schedules/<schedule_id>/trend \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json"

Response Example

JSON

{
  "schedule_id": "example",
  "brand": "example",
  "engine": "example",
  "days": 0,
  "points": []
}

Last updated: June 2026

API Reference

Auto-generated

Ai Visibility

API reference for ai visibility endpoints.

Auto-generated

This page was generated from the OpenAPI spec. Runmake generate-docs to refresh after spec changes.

POST /api/v1/ai-visibility/check

POST

/api/v1/ai-visibility/check

Check brand visibility in AI answers (logged-out engines only)

Parameters

Name	Type	Required	Description
prompts	`string[]`	Required	Prompts
brand	`string`	Required	Brand
competitors	`string[]`	Optional	Competitors
engines	`string[]`	Required	Engines
country	`string`	Optional	country
runs_per_prompt	`integer`	Optional	Runs Per PromptDefault: `1`
brand_domains	`string[]`	Optional	Brand Domains
quote_only	`boolean`	Optional	Quote OnlyDefault: `False`
hard_cap_microcents	`integer`	Optional	hard_cap_microcents

Request Example

Bash

curl -X POST https://api.alterlab.io/api/v1/ai-visibility/check \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "prompts": [],
    "brand": "example_brand",
    "engines": []
  }'

Response Example

JSON

{
  "run_id": "example",
  "brand": "example",
  "status": "example",
  "answers": [],
  "aggregates": [],
  "total_cost_microcents": 0
}

POST /api/v1/ai-visibility/quote

POST

/api/v1/ai-visibility/quote

Quote an AI visibility check without running or billing it

Parameters

Name	Type	Required	Description
prompts	`string[]`	Required	Prompts
brand	`string`	Required	Brand
competitors	`string[]`	Optional	Competitors
engines	`string[]`	Required	Engines
country	`string`	Optional	country
runs_per_prompt	`integer`	Optional	Runs Per PromptDefault: `1`
brand_domains	`string[]`	Optional	Brand Domains
quote_only	`boolean`	Optional	Quote OnlyDefault: `False`
hard_cap_microcents	`integer`	Optional	hard_cap_microcents

Request Example

Bash

curl -X POST https://api.alterlab.io/api/v1/ai-visibility/quote \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "prompts": [],
    "brand": "example_brand",
    "engines": []
  }'

Response Example

JSON

{
  "brand": "example",
  "runs_per_prompt": 0,
  "quote": "example",
  "hard_cap_microcents": "example",
  "within_hard_cap": true
}

GET /api/v1/ai-visibility/runs/{run_id}

GET

/api/v1/ai-visibility/runs/{run_id}

Status and billing of an AI visibility run

Parameters

Name	Type	Required	Description
run_id	`string`	Required	run_id

Request Example

Bash

curl -X GET https://api.alterlab.io/api/v1/ai-visibility/runs/<run_id> \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json"

Response Example

JSON

{
  "run_id": "example",
  "brand": "example",
  "status": "example",
  "answers_total": 0,
  "answers_success": 0,
  "billing": "example"
}

GET /api/v1/ai-visibility/runs/{run_id}/results

GET

/api/v1/ai-visibility/runs/{run_id}/results

Stored answers of an AI visibility run

Parameters

Name	Type	Required	Description
run_id	`string`	Required	run_id

Request Example

Bash

curl -X GET https://api.alterlab.io/api/v1/ai-visibility/runs/<run_id>/results \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json"

Response Example

JSON

{
  "run_id": "example",
  "brand": "example",
  "status": "example",
  "answers": [],
  "aggregates": [],
  "total_cost_microcents": 0
}

POST /api/v1/ai-visibility/schedules

POST

/api/v1/ai-visibility/schedules

Create a recurring AI visibility check

Parameters

Name	Type	Required	Description
name	`string`	Required	Name
frequency	`"daily" \| "weekly"`	Optional	FrequencyDefault: `weekly`
config	`object`	Required	AIVisibilityCheckRequest
hard_cap_microcents	`integer`	Optional	hard_cap_microcents

Request Example

Bash

curl -X POST https://api.alterlab.io/api/v1/ai-visibility/schedules \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "example_name",
    "frequency": "...",
    "config": "..."
  }'

Response Example

JSON

{
  "status": "ok"
}

GET /api/v1/ai-visibility/schedules

GET

/api/v1/ai-visibility/schedules

List AI visibility schedules

Parameters

Name	Type	Required	Description
limit	`integer`	Optional	limitDefault: `20`
offset	`integer`	Optional	offsetDefault: `0`

Request Example

Bash

curl -X GET https://api.alterlab.io/api/v1/ai-visibility/schedules \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json"

Response Example

JSON

{
  "schedules": [],
  "total": 0
}

GET /api/v1/ai-visibility/schedules/{schedule_id}

GET

/api/v1/ai-visibility/schedules/{schedule_id}

Get an AI visibility schedule

Parameters

Name	Type	Required	Description
schedule_id	`string`	Required	schedule_id

Request Example

Bash

curl -X GET https://api.alterlab.io/api/v1/ai-visibility/schedules/<schedule_id> \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json"

Response Example

JSON

{
  "id": "example",
  "name": "example",
  "frequency": "example",
  "config": {},
  "hard_cap_microcents": "example",
  "is_active": true
}

PATCH /api/v1/ai-visibility/schedules/{schedule_id}

PATCH

/api/v1/ai-visibility/schedules/{schedule_id}

Update an AI visibility schedule

Parameters

Name	Type	Required	Description
schedule_id	`string`	Required	schedule_id
name	`string`	Optional	name
frequency	`"daily" \| "weekly"`	Optional	frequency
config	`object`	Optional	AIVisibilityCheckRequest
hard_cap_microcents	`integer`	Optional	hard_cap_microcents

Request Example

Bash

curl -X PATCH https://api.alterlab.io/api/v1/ai-visibility/schedules/<schedule_id> \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json"

Response Example

JSON

{
  "id": "example",
  "name": "example",
  "frequency": "example",
  "config": {},
  "hard_cap_microcents": "example",
  "is_active": true
}

DELETE /api/v1/ai-visibility/schedules/{schedule_id}

DELETE

/api/v1/ai-visibility/schedules/{schedule_id}

Delete an AI visibility schedule (history is kept)

Parameters

Name	Type	Required	Description
schedule_id	`string`	Required	schedule_id

Request Example

Bash

curl -X DELETE https://api.alterlab.io/api/v1/ai-visibility/schedules/<schedule_id> \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json"

Response Example

JSON

{
  "status": "ok"
}

POST /api/v1/ai-visibility/schedules/{schedule_id}/pause

POST

/api/v1/ai-visibility/schedules/{schedule_id}/pause

Pause an AI visibility schedule

Parameters

Name	Type	Required	Description
schedule_id	`string`	Required	schedule_id

Request Example

Bash

curl -X POST https://api.alterlab.io/api/v1/ai-visibility/schedules/<schedule_id>/pause \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json"

Response Example

JSON

{
  "id": "example",
  "name": "example",
  "frequency": "example",
  "config": {},
  "hard_cap_microcents": "example",
  "is_active": true
}

POST /api/v1/ai-visibility/schedules/{schedule_id}/resume

POST

/api/v1/ai-visibility/schedules/{schedule_id}/resume

Resume a paused AI visibility schedule

Parameters

Name	Type	Required	Description
schedule_id	`string`	Required	schedule_id

Request Example

Bash

curl -X POST https://api.alterlab.io/api/v1/ai-visibility/schedules/<schedule_id>/resume \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json"

Response Example

JSON

{
  "id": "example",
  "name": "example",
  "frequency": "example",
  "config": {},
  "hard_cap_microcents": "example",
  "is_active": true
}

POST /api/v1/ai-visibility/schedules/{schedule_id}/run

POST

/api/v1/ai-visibility/schedules/{schedule_id}/run

Run an AI visibility schedule now (next_run_at is unchanged)

Parameters

Name	Type	Required	Description
schedule_id	`string`	Required	schedule_id

Request Example

Bash

curl -X POST https://api.alterlab.io/api/v1/ai-visibility/schedules/<schedule_id>/run \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json"

Response Example

JSON

{
  "outcome": "example",
  "run_id": "example"
}

GET /api/v1/ai-visibility/schedules/{schedule_id}/runs

GET

/api/v1/ai-visibility/schedules/{schedule_id}/runs

Run history of an AI visibility schedule

Parameters

Name	Type	Required	Description
schedule_id	`string`	Required	schedule_id
limit	`integer`	Optional	limitDefault: `20`
offset	`integer`	Optional	offsetDefault: `0`

Request Example

Bash

curl -X GET https://api.alterlab.io/api/v1/ai-visibility/schedules/<schedule_id>/runs \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json"

Response Example

JSON

{
  "runs": [],
  "total": 0
}

GET /api/v1/ai-visibility/schedules/{schedule_id}/trend

GET

/api/v1/ai-visibility/schedules/{schedule_id}/trend

Mention rate and share of voice over time for a schedule

Parameters

Name	Type	Required	Description
schedule_id	`string`	Required	schedule_id
days	`integer`	Optional	daysDefault: `30`
engine	`"google_ai_overview" \| "google_ai_mode" \| "chatgpt" \| "perplexity" \| "gemini" \| "copilot"`	Optional	engine

Request Example

Bash

curl -X GET https://api.alterlab.io/api/v1/ai-visibility/schedules/<schedule_id>/trend \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json"

Response Example

JSON

{
  "schedule_id": "example",
  "brand": "example",
  "engine": "example",
  "days": 0,
  "points": []
}

Last updated: June 2026