TypeScript AI Visibility API

Query the raw answers ChatGPT, Perplexity, Google AI Overviews, Google AI Mode, Copilot and Gemini actually return — from TypeScript, against a response small enough to describe with three interfaces. Scraped HTML is any: its shape changes whenever the UI does. A stable JSON API is an interface you can write down — answer text, citations and sources, checked by the compiler.

Call the AI Visibility API from TypeScript

The request is one fetch; the value is the contract. Below: a six-engine SurfaceKey union, the three interfaces that describe the entire response, and a typed fetchAnswers wrapper. That wrapper is the whole SDK — and you own it.

type SurfaceKey =
  | "chatgpt"
  | "perplexity"
  | "gemini"
  | "google_ai_overview"
  | "copilot";

interface Source {
  title: string;
  url: string;
  position: number;
}

interface Answer {
  surfaceKey: SurfaceKey;
  answerText: string;
  sources: Source[];
}

interface FetchRun {
  id: string;
  query: string;
  surfaces: SurfaceKey[];
  status: string;
  recordsDelivered: number;
  creditsCharged: number;
  answers: Answer[];
}

async function fetchAnswers(
  query: string,
  surfaces: SurfaceKey[],
): Promise<FetchRun> {
  const resp = await fetch("https://api.agentgeo.org/v1/fetches", {
    method: "POST",
    headers: {
      "Authorization": "Bearer ag_live_your_key_here",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({ query, surfaces }),
  });
  if (!resp.ok) throw new Error(`AgentGEO ${resp.status}: ${await resp.text()}`);
  return (await resp.json()) as FetchRun;
}

const run = await fetchAnswers("best running shoes for flat feet", [
  "chatgpt",
  "perplexity",
]);

for (const answer of run.answers) {
  console.log(answer.surfaceKey, "→", answer.answerText);
}

The JSON you're typing against — this is the entire surface those interfaces need to cover:

{
  "id": "run_84c1f2ab91d3",
  "query": "best running shoes",
  "surfaces": ["chatgpt"],
  "status": "completed",
  "recordsDelivered": 1,
  "creditsCharged": 1,
  "answers": [
    {
      "surfaceKey": "chatgpt",
      "answerText": "For most runners, top picks include ...",
      "sources": [
        { "title": "Best Running Shoes", "url": "https://example.com/guide", "position": 1 }
      ]
    }
  ]
}

Because sources is typed, helpers built on top stay typed too. Extracting every cited domain — the input to any share-of-voice metric — is a few honest lines:

// Every domain an engine cited — hostname-level share of voice
function citedDomains(run: FetchRun): Set<string> {
  const domains = new Set<string>();
  for (const answer of run.answers) {
    for (const src of answer.sources) {
      domains.add(new URL(src.url).hostname);
    }
  }
  return domains;
}

const domains = citedDomains(run);
console.log([...domains]);                 // e.g. ["runnersworld.com", ...]
console.log(domains.has("yourbrand.com")); // the GEO question, in one line

What the TypeScript API gives you

AgentGEO stays a thin answer-access layer, not a closed dashboard. The API delivers raw, structured data; your TypeScript codebase (or your users' AI agent) turns it into product.

• Six engines, one union type — ChatGPT, Perplexity, Google AI Overviews, Google AI Mode, Copilot and Gemini share a single request/response contract, so SurfaceKey is the only place engines are enumerated.
• A shape you can write an interface for — FetchRun, Answer, Source: three interfaces cover the whole response, and the compiler enforces them everywhere the data flows.
• Citations as typed data — Answer.sources is Source[] with title, url and position. Autocomplete works, strict null checks work, and nothing degrades to any.
• Managed-scraper engine, maintained for you — no Playwright underneath the types, no proxies, no CAPTCHA walls. The runtime path is as clean as the type layer.
• MCP connection, too — the same data is exposed over MCP via agentgeo-mcp on npm, so Claude Code, Cursor, Codex or any MCP client can consume the identical contract.
• Usage-based billing with a spend cap — free tier with no credit card, then subscription plus overage. Priced by usage, never per seat.

Common problems with DIY answer-scraping in TypeScript

In TypeScript the scraping route carries a special indignity: you chose the language for the guarantees, and scraped HTML is where guarantees go to die. Drive a headless browser into ChatGPT or Perplexity and everything the compiler can vouch for ends at the DOM boundary.

• Typing scraped DOM is fiction. The true type of ChatGPT's rendered markup is 'whatever last week's deploy produced' — so scraper code degrades to any, unknown and casts, and strict mode stops meaning anything.
• It compiles green and breaks at runtime. document.querySelector(".citation") type-checks forever; the class it targets was renamed last Tuesday. The compiler cannot see the DOM you will actually receive.
• Layout changes bypass the type system entirely. The breaking change lands in their frontend deploy, not your commit — no red squiggle, no failing build, just empty sources arrays quietly landing in production.
• Hand-maintained interfaces for six engines' HTML. Six undocumented markup structures, all shifting independently. Those interfaces are stale a week after you write them — false confidence is worse than no types.
• Under the types it's still a scraper. Playwright, stealth patches, proxies, CAPTCHA walls: TypeScript hardens your code, not the hostile, unversioned input that code is parsing.

The MCP route: same contract, inside your agent

The same data is exposed over MCP. When the consumer is an agent rather than your own code — Claude Code, Cursor, Codex or any MCP client — one command wires it up via the agentgeo-mcp npm package, and the agent pulls answers and runs the GEO analysis itself:

claude mcp add agentgeo -- npx -y agentgeo-mcp --key ag_live_your_key_here

Who builds on this

Teams building the dashboard itself: rank-trackers for the AI-answer era, agency reporting products, internal share-of-voice tools — anywhere AI-visibility data becomes a typed domain model inside a larger codebase. If you compared closed platforms like Profound and wanted raw, typed data instead of a rented UI — or you were weighing scraping ChatGPT directly — this is the layer underneath.