{
  "openapi": "3.0.1",
  "info": {
    "title": "AI Brand Visibility Tracker: ChatGPT, Perplexity & Gemini",
    "description": "Check if ChatGPT, Perplexity & Gemini mention your brand. Visibility %, share of voice, sources, run-over-run trends and an HTML report. Pay per check, no subscription.",
    "version": "0.1",
    "x-build-id": "pTbtbB9uAJmqKZmHk"
  },
  "servers": [
    {
      "url": "https://api.apify.com/v2"
    }
  ],
  "paths": {
    "/acts/tan_carrel_h1q~ai-search-brand-visibility-monitor/run-sync-get-dataset-items": {
      "post": {
        "operationId": "run-sync-get-dataset-items-tan_carrel_h1q-ai-search-brand-visibility-monitor",
        "x-openai-isConsequential": false,
        "summary": "Executes an Actor, waits for its completion, and returns Actor's dataset items in response.",
        "tags": [
          "Run Actor"
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/inputSchema"
              }
            }
          }
        },
        "parameters": [
          {
            "name": "token",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Enter your Apify token here"
          }
        ],
        "responses": {
          "200": {
            "description": "OK"
          }
        }
      }
    },
    "/acts/tan_carrel_h1q~ai-search-brand-visibility-monitor/runs": {
      "post": {
        "operationId": "runs-sync-tan_carrel_h1q-ai-search-brand-visibility-monitor",
        "x-openai-isConsequential": false,
        "summary": "Executes an Actor and returns information about the initiated run in response.",
        "tags": [
          "Run Actor"
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/inputSchema"
              }
            }
          }
        },
        "parameters": [
          {
            "name": "token",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Enter your Apify token here"
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/runsResponseSchema"
                }
              }
            }
          }
        }
      }
    },
    "/acts/tan_carrel_h1q~ai-search-brand-visibility-monitor/run-sync": {
      "post": {
        "operationId": "run-sync-tan_carrel_h1q-ai-search-brand-visibility-monitor",
        "x-openai-isConsequential": false,
        "summary": "Executes an Actor, waits for completion, and returns the OUTPUT from Key-value store in response.",
        "tags": [
          "Run Actor"
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/inputSchema"
              }
            }
          }
        },
        "parameters": [
          {
            "name": "token",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Enter your Apify token here"
          }
        ],
        "responses": {
          "200": {
            "description": "OK"
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "inputSchema": {
        "type": "object",
        "required": [
          "brandName",
          "prompts"
        ],
        "properties": {
          "brandName": {
            "title": "Brand name",
            "type": "string",
            "description": "The brand you want to track, exactly as people write it (e.g. \"Notion\"). Matching is case-insensitive and respects word boundaries."
          },
          "brandAliases": {
            "title": "Brand aliases",
            "type": "array",
            "description": "Other names that count as a mention of your brand: product names, abbreviations, common misspellings, legal names.",
            "default": [],
            "items": {
              "type": "string"
            }
          },
          "brandDomain": {
            "title": "Brand domain",
            "type": "string",
            "description": "Your website domain (e.g. notion.com). A mention of the domain counts as a brand mention, and sources on this domain count as \"cited\"."
          },
          "competitors": {
            "title": "Competitors",
            "type": "array",
            "description": "Competing brands to compare against (share of voice). Plain names work; for aliases and a domain use \"Name | alias one, alias two | domain.com\". A bare domain like \"coda.io\" also works.",
            "default": [],
            "items": {
              "type": "string"
            }
          },
          "prompts": {
            "title": "Prompts (buyer questions)",
            "type": "array",
            "description": "Questions a buyer might ask an AI assistant, without naming your brand (e.g. \"What is the best CRM for a small agency?\"). Each prompt is sent to every selected engine.",
            "items": {
              "type": "string"
            }
          },
          "engines": {
            "title": "AI engines to query",
            "type": "array",
            "description": "Which official APIs to query. Engines without an available API key are skipped with a warning.",
            "items": {
              "type": "string",
              "enum": [
                "openai",
                "perplexity",
                "gemini"
              ],
              "enumTitles": [
                "OpenAI (ChatGPT models, with web search)",
                "Perplexity (Sonar, always searches the web)",
                "Google Gemini"
              ]
            },
            "default": [
              "openai",
              "perplexity",
              "gemini"
            ]
          },
          "runsPerPrompt": {
            "title": "Runs per prompt",
            "minimum": 1,
            "maximum": 10,
            "type": "integer",
            "description": "AI answers vary from run to run. Run each prompt several times per engine to get a more stable visibility %. Each run is a separate billed check.",
            "default": 1
          },
          "country": {
            "title": "Country (optional)",
            "type": "string",
            "description": "Two-letter ISO country code (e.g. US, GB, DE). Used as a location hint for web search and added to the prompt context."
          },
          "language": {
            "title": "Answer language (optional)",
            "type": "string",
            "description": "Language the AI should answer in (e.g. English, German, Español)."
          },
          "geminiGrounding": {
            "title": "Gemini: ground answers with Google Search (premium)",
            "type": "boolean",
            "description": "Gives Gemini live Google Search results and returns the cited sources. Google bills this per search, so these checks use the higher-priced \"grounded Gemini check\" event. With your own Gemini key it is billed as a regular own-key check.",
            "default": false
          },
          "openaiWebSearch": {
            "title": "OpenAI: allow web search",
            "type": "boolean",
            "description": "Lets the OpenAI model use its web search tool (closer to how ChatGPT answers, and returns cited sources). Turn off for answers from the model's training knowledge only.",
            "default": true
          },
          "openaiModel": {
            "title": "OpenAI model",
            "enum": [
              "gpt-4o-mini",
              "gpt-4.1-mini"
            ],
            "type": "string",
            "description": "Model used with the built-in key. Use your own key and the custom models field below for any other model.",
            "default": "gpt-4o-mini"
          },
          "perplexityModel": {
            "title": "Perplexity model",
            "enum": [
              "perplexity/sonar"
            ],
            "type": "string",
            "description": "Model used with the built-in key.",
            "default": "perplexity/sonar"
          },
          "geminiModel": {
            "title": "Gemini model",
            "enum": [
              "gemini-3.5-flash-lite",
              "gemini-3.8-flash"
            ],
            "type": "string",
            "description": "Model used with the built-in key.",
            "default": "gemini-3.5-flash-lite"
          },
          "openaiApiKey": {
            "title": "Your OpenAI API key (optional)",
            "type": "string",
            "description": "Bring your own key: OpenAI usage is billed to your OpenAI account and checks are billed at the lower \"own key\" rate. Stored encrypted by Apify; never logged. Required on a free Apify plan; paid plans may omit it."
          },
          "perplexityApiKey": {
            "title": "Your Perplexity API key (optional)",
            "type": "string",
            "description": "Bring your own key: Perplexity usage is billed to your account and checks use the lower \"own key\" rate. Stored encrypted by Apify; never logged. Required on a free Apify plan; paid plans may omit it."
          },
          "geminiApiKey": {
            "title": "Your Google Gemini API key (optional)",
            "type": "string",
            "description": "Bring your own key: Gemini usage is billed to your Google account and checks use the lower \"own key\" rate. Stored encrypted by Apify; never logged. Required on a free Apify plan; paid plans may omit it."
          },
          "customModels": {
            "title": "Custom models (own keys only)",
            "type": "object",
            "description": "Override the model per engine, e.g. {\"openai\": \"gpt-4.1\", \"gemini\": \"gemini-3.8-flash\"}. Only applied to engines where you supplied your own API key.",
            "default": {}
          },
          "systemPrompt": {
            "title": "Custom system prompt (optional)",
            "type": "string",
            "description": "Replaces the neutral built-in instruction sent to every engine. Leave empty unless you know you need it; do not mention your brand here or you will bias the results."
          },
          "maxChecks": {
            "title": "Maximum checks per run",
            "minimum": 1,
            "maximum": 1000,
            "type": "integer",
            "description": "Safety cap on the number of engine x prompt x run checks. The run also stops gracefully when Apify's \"Maximum cost per run\" is reached.",
            "default": 500
          },
          "concurrency": {
            "title": "Parallel requests",
            "minimum": 1,
            "maximum": 10,
            "type": "integer",
            "description": "How many AI requests run at the same time.",
            "default": 4
          },
          "requestsPerMinutePerEngine": {
            "title": "Max requests per minute per engine",
            "minimum": 1,
            "maximum": 600,
            "type": "integer",
            "description": "Client-side rate limit to stay inside provider limits (new API accounts often have low limits).",
            "default": 60
          },
          "requestTimeoutSecs": {
            "title": "Request timeout (seconds)",
            "minimum": 10,
            "maximum": 180,
            "type": "integer",
            "description": "Per-attempt timeout for each AI API request.",
            "default": 90
          },
          "maxRetries": {
            "title": "Retries per request",
            "minimum": 0,
            "maximum": 6,
            "type": "integer",
            "description": "Retries with exponential backoff on rate limits, timeouts and server errors. Failed checks are never billed.",
            "default": 3
          },
          "trackHistory": {
            "title": "Track results over time",
            "type": "boolean",
            "description": "Saves a compact summary of every run in a named key-value store in YOUR Apify account and compares each run with the previous one (visibility, share of voice, position, sources, competitors). Schedule the Actor weekly to build a trend. Nothing extra is billed. Not used for demo results.",
            "default": true
          },
          "trackingId": {
            "title": "Tracking ID (optional)",
            "type": "string",
            "description": "Runs with the same Tracking ID share one history. Leave empty to use your brand name + domain. Use different IDs to track the same brand separately, for example per country or per prompt set: \"acme-uk\", \"acme-us\"."
          },
          "mockMode": {
            "title": "Demo mode (no AI calls, free)",
            "type": "boolean",
            "description": "Runs the whole pipeline on canned example answers so you can see the output format and the tracking section without spending anything. Limited to 30 checks and clearly marked as demo data. Works on every plan, including free.",
            "default": false
          },
          "mockVariation": {
            "title": "Demo variation (demo mode only)",
            "minimum": 0,
            "maximum": 1000,
            "type": "integer",
            "description": "Demo mode only: a different number re-rolls the canned example answers, so you can watch the trend section change between two demo runs. Ignored for real runs.",
            "default": 0
          }
        }
      },
      "runsResponseSchema": {
        "type": "object",
        "properties": {
          "data": {
            "type": "object",
            "properties": {
              "id": {
                "type": "string"
              },
              "actId": {
                "type": "string"
              },
              "userId": {
                "type": "string"
              },
              "startedAt": {
                "type": "string",
                "format": "date-time",
                "example": "2025-01-08T00:00:00.000Z"
              },
              "finishedAt": {
                "type": "string",
                "format": "date-time",
                "example": "2025-01-08T00:00:00.000Z"
              },
              "status": {
                "type": "string",
                "example": "READY"
              },
              "meta": {
                "type": "object",
                "properties": {
                  "origin": {
                    "type": "string",
                    "example": "API"
                  },
                  "userAgent": {
                    "type": "string"
                  }
                }
              },
              "stats": {
                "type": "object",
                "properties": {
                  "inputBodyLen": {
                    "type": "integer",
                    "example": 2000
                  },
                  "rebootCount": {
                    "type": "integer",
                    "example": 0
                  },
                  "restartCount": {
                    "type": "integer",
                    "example": 0
                  },
                  "resurrectCount": {
                    "type": "integer",
                    "example": 0
                  },
                  "computeUnits": {
                    "type": "integer",
                    "example": 0
                  }
                }
              },
              "options": {
                "type": "object",
                "properties": {
                  "build": {
                    "type": "string",
                    "example": "latest"
                  },
                  "timeoutSecs": {
                    "type": "integer",
                    "example": 300
                  },
                  "memoryMbytes": {
                    "type": "integer",
                    "example": 1024
                  },
                  "diskMbytes": {
                    "type": "integer",
                    "example": 2048
                  }
                }
              },
              "buildId": {
                "type": "string"
              },
              "defaultKeyValueStoreId": {
                "type": "string"
              },
              "defaultDatasetId": {
                "type": "string"
              },
              "defaultRequestQueueId": {
                "type": "string"
              },
              "buildNumber": {
                "type": "string",
                "example": "1.0.0"
              },
              "containerUrl": {
                "type": "string"
              },
              "usage": {
                "type": "object",
                "properties": {
                  "ACTOR_COMPUTE_UNITS": {
                    "type": "integer",
                    "example": 0
                  },
                  "DATASET_READS": {
                    "type": "integer",
                    "example": 0
                  },
                  "DATASET_WRITES": {
                    "type": "integer",
                    "example": 0
                  },
                  "KEY_VALUE_STORE_READS": {
                    "type": "integer",
                    "example": 0
                  },
                  "KEY_VALUE_STORE_WRITES": {
                    "type": "integer",
                    "example": 1
                  },
                  "KEY_VALUE_STORE_LISTS": {
                    "type": "integer",
                    "example": 0
                  },
                  "REQUEST_QUEUE_READS": {
                    "type": "integer",
                    "example": 0
                  },
                  "REQUEST_QUEUE_WRITES": {
                    "type": "integer",
                    "example": 0
                  },
                  "DATA_TRANSFER_INTERNAL_GBYTES": {
                    "type": "integer",
                    "example": 0
                  },
                  "DATA_TRANSFER_EXTERNAL_GBYTES": {
                    "type": "integer",
                    "example": 0
                  },
                  "PROXY_RESIDENTIAL_TRANSFER_GBYTES": {
                    "type": "integer",
                    "example": 0
                  },
                  "PROXY_SERPS": {
                    "type": "integer",
                    "example": 0
                  },
                  "PROXY_UNBLOCKER_UNITS": {
                    "type": "integer",
                    "example": 0
                  }
                }
              },
              "usageTotalUsd": {
                "type": "number",
                "example": 0.00005
              },
              "usageUsd": {
                "type": "object",
                "properties": {
                  "ACTOR_COMPUTE_UNITS": {
                    "type": "integer",
                    "example": 0
                  },
                  "DATASET_READS": {
                    "type": "integer",
                    "example": 0
                  },
                  "DATASET_WRITES": {
                    "type": "integer",
                    "example": 0
                  },
                  "KEY_VALUE_STORE_READS": {
                    "type": "integer",
                    "example": 0
                  },
                  "KEY_VALUE_STORE_WRITES": {
                    "type": "number",
                    "example": 0.00005
                  },
                  "KEY_VALUE_STORE_LISTS": {
                    "type": "integer",
                    "example": 0
                  },
                  "REQUEST_QUEUE_READS": {
                    "type": "integer",
                    "example": 0
                  },
                  "REQUEST_QUEUE_WRITES": {
                    "type": "integer",
                    "example": 0
                  },
                  "DATA_TRANSFER_INTERNAL_GBYTES": {
                    "type": "integer",
                    "example": 0
                  },
                  "DATA_TRANSFER_EXTERNAL_GBYTES": {
                    "type": "integer",
                    "example": 0
                  },
                  "PROXY_RESIDENTIAL_TRANSFER_GBYTES": {
                    "type": "integer",
                    "example": 0
                  },
                  "PROXY_SERPS": {
                    "type": "integer",
                    "example": 0
                  },
                  "PROXY_UNBLOCKER_UNITS": {
                    "type": "integer",
                    "example": 0
                  }
                }
              }
            }
          }
        }
      }
    }
  }
}