AI search

Search is no longer only ten blue links. These endpoints look at what AI assistants actually say: the answer a buyer gets when they ask, and how often a brand comes up across those answers.

POST/v1/geo/prompt

Prompt answer

Asks an assistant a question the way a buyer would and returns the answer it gives, with the web pages it cited. Use it to see which brands get recommended for a prompt, and whether yours is one of them.

Costs 1.2 credits per call. An assistant that searches the web before answering takes 30 to 60 seconds, so allow for a slow response.

Required attributes

Name
prompt
Type
string
Description
The question to ask, 1 to 500 characters. Write it the way a customer would, not the way a keyword tool would.

Optional attributes

Name
country
Type
string
Description
ISO 3166-1 alpha-2 country code. Default US.
Name
language
Type
string
Description
ISO 639-1 language code. Defaults to the language of the country.
Name
web_search
Type
boolean
Description
Let the assistant search the web before answering. Default true. Set it to false to see what the model says from memory alone, which is a different and often more revealing test.

Response fields

Name
answer
Type
string
Description
The assistant's answer, cleaned of inline citation markers and images. Capped at 20,000 characters.
Name
sources
Type
array
Description
The pages the assistant cited, each with url, title and domain.
Name
domains_cited
Type
array
Description
The unique domains behind those sources, which is usually the number you want to track over time.

Request

POST

/v1/geo/prompt

curl -X POST https://suvjexogmfpvxjcktvuk.supabase.co/functions/v1/api/v1/geo/prompt \
  -H "Authorization: Bearer $PENGU_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"prompt": "best project management tool for a small agency"}'

Response

{
  "data": {
    "prompt": "best project management tool for a small agency",
    "country": "US",
    "language": "en",
    "checked_at": "2026-09-20T09:12:44.106Z",
    "answer": "For a small agency the usual shortlist is ...",
    "word_count": 412,
    "sources": [
      {
        "url": "https://example-review-site.com/best-agency-pm-tools",
        "title": "9 project management tools for agencies in 2026",
        "domain": "example-review-site.com"
      }
    ],
    "domains_cited": ["example-review-site.com"]
  },
  "meta": {
    "credits_charged": 1,
    "credits_remaining": 2799,
    "request_id": "b1f0a4c2-2f7d-4f0e-9a41-0c6a2c3ce511"
  }
}

POST/v1/geo/brand-mentions

Brand mentions

How often a brand or domain is mentioned in assistant answers, broken down by the model that answered, with the AI search volume behind those answers.

Costs 28.8 credits per call. This is the most expensive endpoint in the API: it reads an index of assistant answers rather than making one call. Run it on a schedule, not on every page load.

Required attributes

Name
brand
Type
string
Description
A domain such as notion.so, or a brand name such as Notion. A value with a dot and no spaces is treated as a domain; anything else is matched as a brand name.

Optional attributes

Name
platform
Type
string
Description
chat_gpt or google. Default chat_gpt.
Name
country
Type
string
Description
ISO 3166-1 alpha-2 country code. Ignored for chat_gpt, see the note below.
Name
language
Type
string
Description
ISO 639-1 language code. Ignored for chat_gpt.
Name
include_subdomains
Type
boolean
Description
Only applies when brand is a domain. Default true.

The ChatGPT mentions index only holds US English data. Asking it for another market returns nothing, which reads like an outage, so the locale is forced to US / en and the response reports the locale that was actually measured. Use platform: "google" for other markets.

Response fields

Name
mentions
Type
integer
Description
Total mentions across every model that answered.
Name
ai_search_volume
Type
integer
Description
The volume of assistant questions behind those mentions.
Name
models
Type
array
Description
One row per model, with model, mentions and ai_search_volume, sorted by mentions.

Request

POST

/v1/geo/brand-mentions

curl -X POST https://suvjexogmfpvxjcktvuk.supabase.co/functions/v1/api/v1/geo/brand-mentions \
  -H "Authorization: Bearer $PENGU_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"brand": "notion.so", "platform": "chat_gpt"}'

Response

{
  "data": {
    "brand": "notion.so",
    "platform": "chat_gpt",
    "country": "US",
    "language": "en",
    "checked_at": "2026-09-20T09:14:02.551Z",
    "mentions": 18420,
    "ai_search_volume": 240900,
    "models": [
      { "model": "gpt-4o", "mentions": 11240, "ai_search_volume": 152300 },
      { "model": "gpt-4o-mini", "mentions": 7180, "ai_search_volume": 88600 }
    ]
  },
  "meta": {
    "credits_charged": 20.5,
    "credits_remaining": 2778.5,
    "request_id": "5c2e9f17-6c1e-4d0b-9f52-3b8a1d44e902"
  }
}

POST/v1/geo/keyword-volume

AI search volume

How often people ask AI assistants about each keyword, with a twelve month trend: the AI counterpart of search volume. Use it to see which topics buyers already research through assistants before they ever reach Google.

Costs 3 credits per call, for up to 100 keywords.

Required attributes

Name
keywords
Type
array
Description
1 to 100 keywords, or a comma separated string.

Optional attributes

Name
country
Type
string
Description
ISO 3166-1 alpha-2 country code. Default US, where coverage is widest.
Name
language
Type
string
Description
ISO 639-1 language code. Defaults to the language of the country.

Response fields

Name
keywords[].ai_search_volume
Type
integer
Description
null when the keyword is not in the AI dataset. That is different from zero: "not measured" and "nobody asks" are separate findings, and a report should not merge them.
Name
measured
Type
integer
Description
How many of the keywords you sent came back with data.
Name
keywords[].trend_12m
Type
array
Description
Monthly AI search volume for the last twelve months.

Request

POST

/v1/geo/keyword-volume

curl -X POST https://suvjexogmfpvxjcktvuk.supabase.co/functions/v1/api/v1/geo/keyword-volume \
  -H "Authorization: Bearer $PENGU_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"keywords": ["project management software", "best crm"], "country": "US"}'

Response

{
  "data": {
    "country": "US",
    "language": "en",
    "checked_at": "2026-10-19T10:12:44.106Z",
    "count": 2,
    "measured": 2,
    "total_ai_search_volume": 14300,
    "keywords": [
      {
        "keyword": "best crm",
        "ai_search_volume": 8900,
        "trend_12m": [
          {
            "month": "2026-09",
            "volume": 9400
          }
        ]
      },
      {
        "keyword": "project management software",
        "ai_search_volume": 5400,
        "trend_12m": [
          {
            "month": "2026-09",
            "volume": 5800
          }
        ]
      }
    ]
  },
  "meta": {
    "credits_charged": 3,
    "credits_remaining": 2797,
    "request_id": "4e1b7a20-9c3d-4f61-8a52-1d0e6b9f3c84"
  }
}

POST/v1/geo/brand-questions

Questions where AI mentions a brand

The real questions people ask AI assistants in which a brand comes up, with the sources each answer cited and the other brands named alongside it. The closest thing there is to reading the conversations where a buying decision is being shaped.

Costs 28.8 credits per call. The two summary lists are worth more than any single row: they are where the competitive picture in a GEO report comes from.

Required attributes

Name
brand
Type
string
Description
A domain such as notion.so, or a brand name such as Notion. A domain is matched on the site; a name is matched on the brand entity the assistants recognise.

Optional attributes

Name
platform
Type
string
Description
chat_gpt or google. Default chat_gpt.
Name
country
Type
string
Description
ISO 3166-1 alpha-2 country code. Ignored for chat_gpt, which only holds US English data; the response reports the locale actually measured.
Name
language
Type
string
Description
ISO 639-1 language code. Ignored for chat_gpt.
Name
include_subdomains
Type
boolean
Description
Only applies when brand is a domain. Default true.
Name
limit
Type
integer
Description
Questions to return, 10 to 100. Default 50. Capped by your plan.

Response fields

Name
top_cited_domains
Type
array
Description
The domains assistants lean on across every answer, by how many questions cite them. A third-party domain high on this list is a placement target.
Name
brands_named_alongside
Type
array
Description
The other brands that appear in the same answers, by frequency. The brand you asked about is left out: it is in every answer by construction.
Name
questions[].sources
Type
array
Description
The pages that answer cited, each with url, title and domain.

Request

POST

/v1/geo/brand-questions

curl -X POST https://suvjexogmfpvxjcktvuk.supabase.co/functions/v1/api/v1/geo/brand-questions \
  -H "Authorization: Bearer $PENGU_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"brand": "notion.so", "platform": "chat_gpt", "limit": 50}'

Response

{
  "data": {
    "brand": "notion.so",
    "platform": "chat_gpt",
    "country": "US",
    "language": "en",
    "checked_at": "2026-10-19T10:14:02.551Z",
    "count": 50,
    "top_cited_domains": [
      {
        "name": "g2.com",
        "questions": 31
      },
      {
        "name": "notion.so",
        "questions": 22
      }
    ],
    "brands_named_alongside": [
      {
        "name": "Obsidian",
        "questions": 18
      },
      {
        "name": "Confluence",
        "questions": 12
      }
    ],
    "questions": [
      {
        "question": "best note taking app for teams",
        "ai_search_volume": 3100,
        "first_seen": "2026-05-01",
        "last_seen": "2026-10-10",
        "brands_named": [
          "Notion",
          "Obsidian"
        ],
        "sources": [
          {
            "url": "https://www.g2.com/categories/note-taking",
            "title": "Best Note-Taking Software",
            "domain": "g2.com"
          }
        ]
      }
    ]
  },
  "meta": {
    "credits_charged": 28.8,
    "credits_remaining": 2771.2,
    "request_id": "a8c3e5f1-2b74-4d09-9e16-7f0b3c2d5a48"
  }
}

POST/v1/geo/cited-pages

Pages AI cites

The web pages assistants cite as sources when they answer about a brand, ranked by how often. Shows which of the brand's own pages earn citations, and which third-party pages are shaping what assistants say about it.

Costs 28.8 credits per call. Give brand as a domain to get the own versus third-party split.

Required attributes

Name
brand
Type
string
Description
A domain such as notion.so, or a brand name such as Notion. A domain is matched on the site; a name is matched on the brand entity the assistants recognise.

Optional attributes

Name
platform
Type
string
Description
chat_gpt or google. Default chat_gpt.
Name
country
Type
string
Description
ISO 3166-1 alpha-2 country code. Ignored for chat_gpt, which only holds US English data; the response reports the locale actually measured.
Name
language
Type
string
Description
ISO 639-1 language code. Ignored for chat_gpt.
Name
include_subdomains
Type
boolean
Description
Only applies when brand is a domain. Default true.
Name
limit
Type
integer
Description
Pages to return, 5 to 50. Default 20. Capped by your plan.

Response fields

Name
pages[].is_own
Type
boolean
Description
Whether the page is on the brand's own site. null when the brand was given as a name, since there is then no site to compare against.
Name
own_pages
Type
integer
Description
How many of the cited pages are the brand's own. third_party_pages is the rest.
Name
pages[].models
Type
array
Description
Mentions and AI search volume by the model that cited the page.

Request

POST

/v1/geo/cited-pages

curl -X POST https://suvjexogmfpvxjcktvuk.supabase.co/functions/v1/api/v1/geo/cited-pages \
  -H "Authorization: Bearer $PENGU_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"brand": "notion.so", "platform": "chat_gpt", "limit": 20}'

Response

{
  "data": {
    "brand": "notion.so",
    "platform": "chat_gpt",
    "country": "US",
    "language": "en",
    "checked_at": "2026-10-19T10:15:40.003Z",
    "count": 20,
    "own_pages": 6,
    "third_party_pages": 14,
    "pages": [
      {
        "url": "https://www.g2.com/products/notion/reviews",
        "domain": "g2.com",
        "is_own": false,
        "mentions": 90,
        "ai_search_volume": 21000,
        "models": [
          {
            "model": "gpt-4o",
            "mentions": 90,
            "ai_search_volume": 21000
          }
        ]
      }
    ]
  },
  "meta": {
    "credits_charged": 28.8,
    "credits_remaining": 2742.4,
    "request_id": "c2f9a1d4-6e38-4b70-8c15-3a7e0d9b2f61"
  }
}