▣ ARTIFICIAL INTELLIGENCE · MARKETING

Analyze AI Search Performance API

What it does

AI Search Analytics helps you measure how a brand or domain appears in AI search results. Send a target and source, and get back brand matches, prompt data, and visibility metrics you can use to track presence across AI engines.

Use the discovery endpoint to find brands associated with a URL, domain, base domain, or full URL. For prompt analysis, query by target brand or by brand name and receive a dated response with totals plus a prompts array. Each prompt includes the prompt text, its type, the answer text, any links, and volume. You can sort by volume, type, or snippet length, and filter by volume, keyword count, character count, and multi-keyword inclusion or exclusion.

For performance tracking, the overview endpoints return summary metrics and monthly time series for AI traffic, link presence, organic traffic, overall traffic, and average position. Use the aggregated view to compare performance across engines, or the leaderboard endpoint to compare a primary target against up to 10 competitors and see share of voice, link presence, and brand presence by engine.

Build reporting dashboards, monitor competitor visibility, or audit how often your brand is cited versus linked in AI-driven search experiences.

▣ ENDPOINT 01 / 06

GET

Get AI Search Overview — Single Engine (Trend)

https://api.eu.apyhub.com/se-ranking/ai-search/v1/ai-search/overview/by-engine/time-series

QUICKSTART

GUIDE

Quickstart

Fetch the time-series overview for an AI search engine by passing the required query parameters.

curl -X GET "https://api.eu.apyhub.com/se-ranking/ai-search/v1/ai-search/overview/by-engine/time-series?engine=ai-overview&source=us&target=seranking.com" \
  -H "apy-token: $APY_TOKEN"

What you'll get back

Returns a JSON object with two top-level objects: summary and time_series.

summary contains link_presence, brand_presence, average_position, and ai_opportunity_traffic, each as an object with current, previous, change_percent, and change_absolute number fields.
time_series contains arrays for ai_traffic, link_presence, organic_traffic, overall_traffic, and average_position; each array item has a date string in YYYY-MM format and a numeric value.

{
  "summary": {
    "link_presence": {
      "current": 0,
      "previous": 0,
      "change_percent": 0,
      "change_absolute": 0
    }
  },
  "time_series": {
    "ai_traffic": [
      {
        "date": "2024-01",
        "value": 0
      }
    ]
  }
}

TRY ITLIVE · 4000 ATOMS

API key

Loading your default key…

The full key is used to call the gateway and stays in this tab — never sent to orbit or saved.

About this endpoint

What it does

Returns an AI search overview for a given engine, source, and target as a JSON object with summary metrics and time-series data. The request is made with query parameters only.

Query Parameter(s)

Attribute	Type	Mandatory	Description
brand	String	No	Brand identifier or name.
scope	ENUM	No	Scope for the comparison. Allowed values: `domain`, `base_domain`, `url`. Default: `base_domain`.
engine	String	Yes	AI search engine to query.
source	String	Yes	Source to compare from.
target	String	Yes	Target to compare against.

Response

Returns a JSON object with two top-level object fields: summary and time_series. summary contains four metric objects, each with current, previous, change_percent, and change_absolute number fields. time_series contains arrays of { date, value } objects for AI and traffic metrics.

Parameter	Type	Mandatory	Description
summary	Object	No	Summary metrics object.
summary.link_presence	Object	No	Link presence metrics with `current`, `previous`, `change_percent`, and `change_absolute` number fields.
summary.brand_presence	Object	No	Brand presence metrics with `current`, `previous`, `change_percent`, and `change_absolute` number fields.
summary.average_position	Object	No	Average position metrics with `current`, `previous`, `change_percent`, and `change_absolute` number fields.
summary.ai_opportunity_traffic	Object	No	AI opportunity traffic metrics with `current`, `previous`, `change_percent`, and `change_absolute` number fields.
time_series	Object	No	Time-series data object.
time_series.ai_traffic	Object Array	No	Array of `{ date, value }` objects. `date` is a string in `YYYY-MM` format and `value` is a float.
time_series.link_presence	Object Array	No	Array of `{ date, value }` objects. `date` is a string in `YYYY-MM` format and `value` is a float.
time_series.organic_traffic	Object Array	No	Array of `{ date, value }` objects. `date` is a string in `YYYY-MM` format and `value` is a float.
time_series.overall_traffic	Object Array	No	Array of `{ date, value }` objects. `date` is a string in `YYYY-MM` format and `value` is a float.
time_series.average_position	Object Array	No	Array of `{ date, value }` objects. `date` is a string in `YYYY-MM` format and `value` is a float.

Query parameters

Name

Type

Description

brandOPTIONAL

string

—

scopeOPTIONAL

string

domain · base_domain · url

—

DEFAULT base_domain

engineREQUIRED

string

—

sourceREQUIRED

string

—

targetREQUIRED

string

—

▣ ENDPOINT 02 / 06

GET

discover brand

https://api.eu.apyhub.com/se-ranking/ai-search/v1/ai-search/discover-brand

QUICKSTART

GUIDE

Quickstart

Find brand suggestions for a target by passing the required query parameters in a simple GET request.

curl -X GET "https://api.eu.apyhub.com/se-ranking/ai-search/v1/ai-search/discover-brand?source=us&target=seranking.com&scope=base_domain" \
  -H "apy-token: $APY_TOKEN"

What you'll get back

Returns a JSON object with a brands array of strings. Each string is a discovered brand name.

{
  "brands": [
    "Example"
  ]
}

TRY ITLIVE · 500 ATOMS

API key

Loading your default key…

The full key is used to call the gateway and stays in this tab — never sent to orbit or saved.

About this endpoint

What it does

Discovers brand names from the supplied target and source values using the selected scope. Returns a JSON object containing a brands array of strings.

Query Parameter(s)

Attribute	Type	Mandatory	Description
scope	String	Yes	Scope used for discovery. Allowed values: `domain`, `base_domain`, `url`. Default: `base_domain`.
source	String	Yes	Source string used by the discovery process.
target	String	Yes	Target string used by the discovery process.

Response

Returns a JSON object with a brands string array field.

Attribute	Type	Mandatory	Description
brands	String Array	No	Array of brand names discovered by the endpoint.

Query parameters

Name

Type

Description

scopeREQUIRED

string

domain · base_domain · url

—

DEFAULT base_domain

sourceREQUIRED

string

—

targetREQUIRED

string

—

▣ ENDPOINT 03 / 06

GET

Get AI Search Overview — All Engines (Trend)

https://api.eu.apyhub.com/se-ranking/ai-search/v1/ai-search/overview/aggregated/time-series

QUICKSTART

GUIDE

Quickstart

Compare AI search metrics for a target against a source using the required query parameters.

curl -X GET "https://api.eu.apyhub.com/se-ranking/ai-search/v1/ai-search/overview/aggregated/time-series?source=us&target=seranking.com" \
  -H "apy-token: $APY_TOKEN"

What you'll get back

Returns a JSON object with optional summary and time_series objects.

summary contains metric objects such as link_presence, brand_presence, average_position, and ai_opportunity_traffic, each with current, previous, change_percent, and change_absolute numbers.
time_series contains arrays such as ai_traffic, link_presence, organic_traffic, overall_traffic, and average_position, where each item has a date string in YYYY-MM format and a numeric value.

{
  "summary": {
    "link_presence": {
      "current": 12.5,
      "previous": 10.2,
      "change_percent": 22.55,
      "change_absolute": 2.3
    }
  },
  "time_series": {
    "ai_traffic": [
      { "date": "2024-05", "value": 120.4 }
    ]
  }
}

TRY ITLIVE · 10000 ATOMS

API key

Loading your default key…

The full key is used to call the gateway and stays in this tab — never sent to orbit or saved.

About this endpoint

What it does

Retrieves an aggregated AI search overview across engines for the requested target and source, with optional brand and scope filters. The response includes summary metrics and time-series data.

Query Parameter(s)

Attribute	Type	Mandatory	Description
brand	String	No	Optional brand filter.
scope	ENUM	No	Scope of the lookup. Allowed values: `domain`, `base_domain`, `url`. Default: `base_domain`.
source	String	Yes	Source identifier to aggregate from.
target	String	Yes	Target identifier to aggregate for.

Response

Returns a JSON object with top-level summary and time_series object fields. The summary object contains link_presence, brand_presence, average_position, and ai_opportunity_traffic objects, each with current, previous, change_percent, and change_absolute float fields. The time_series object contains arrays for ai_traffic, link_presence, organic_traffic, overall_traffic, and average_position, and each array item is an object with date and value fields.

Parameter	Type	Mandatory	Description
summary	Object	No	Summary metrics object.
summary.link_presence	Object	No	Link presence summary with `current`, `previous`, `change_percent`, and `change_absolute` float fields.
summary.link_presence.current	Number	No	Current float value.
summary.link_presence.previous	Number	No	Previous float value.
summary.link_presence.change_percent	Number	No	Float change percentage.
summary.link_presence.change_absolute	Number	No	Float absolute change.
summary.brand_presence	Object	No	Brand presence summary with `current`, `previous`, `change_percent`, and `change_absolute` float fields.
summary.brand_presence.current	Number	No	Current float value.
summary.brand_presence.previous	Number	No	Previous float value.
summary.brand_presence.change_percent	Number	No	Float change percentage.
summary.brand_presence.change_absolute	Number	No	Float absolute change.
summary.average_position	Object	No	Average position summary with `current`, `previous`, `change_percent`, and `change_absolute` float fields.
summary.average_position.current	Number	No	Current float value.
summary.average_position.previous	Number	No	Previous float value.
summary.average_position.change_percent	Number	No	Float change percentage.
summary.average_position.change_absolute	Number	No	Float absolute change.
summary.ai_opportunity_traffic	Object	No	AI opportunity traffic summary with `current`, `previous`, `change_percent`, and `change_absolute` float fields.
summary.ai_opportunity_traffic.current	Number	No	Current float value.
summary.ai_opportunity_traffic.previous	Number	No	Previous float value.
summary.ai_opportunity_traffic.change_percent	Number	No	Float change percentage.
summary.ai_opportunity_traffic.change_absolute	Number	No	Float absolute change.
time_series	Object	No	Time-series data object.
time_series.ai_traffic	Object Array	No	Monthly AI traffic series. Each item has `date` (`YYYY-MM`) and `value` float fields.
time_series.ai_traffic[].date	String	No	Month in `YYYY-MM` format.
time_series.ai_traffic[].value	Number	No	Float value for the month.
time_series.link_presence	Object Array	No	Monthly link presence series. Each item has `date` (`YYYY-MM`) and `value` float fields.
time_series.link_presence[].date	String	No	Month in `YYYY-MM` format.
time_series.link_presence[].value	Number	No	Float value for the month.
time_series.organic_traffic	Object Array	No	Monthly organic traffic series. Each item has `date` (`YYYY-MM`) and `value` float fields.
time_series.organic_traffic[].date	String	No	Month in `YYYY-MM` format.
time_series.organic_traffic[].value	Number	No	Float value for the month.
time_series.overall_traffic	Object Array	No	Monthly overall traffic series. Each item has `date` (`YYYY-MM`) and `value` float fields.
time_series.overall_traffic[].date	String	No	Month in `YYYY-MM` format.
time_series.overall_traffic[].value	Number	No	Float value for the month.
time_series.average_position	Object Array	No	Monthly average position series. Each item has `date` (`YYYY-MM`) and `value` float fields.
time_series.average_position[].date	String	No	Month in `YYYY-MM` format.
time_series.average_position[].value	Number	No	Float value for the month.

Query parameters

Name

Type

Description

brandOPTIONAL

string

—

scopeOPTIONAL

string

domain · base_domain · url

—

DEFAULT base_domain

sourceREQUIRED

string

—

targetREQUIRED

string

—

▣ ENDPOINT 04 / 06

POST

Compare Brand vs Competitors (AI Leaderboard)

https://api.eu.apyhub.com/se-ranking/ai-search/v1/ai-search/overview/leaderboard

QUICKSTART

GUIDE

Quickstart

Compare one primary brand against at least one competitor across selected AI engines.

curl -X POST "https://api.eu.apyhub.com/se-ranking/ai-search/v1/ai-search/overview/leaderboard" \
  -H "apy-token: $APY_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "source": "us",
    "engines": ["ai-overview"],
    "primary": {
      "brand": "SE Ranking",
      "target": "seranking.com"
    },
    "competitors": [
      { "brand": "Semrush", "target": "semrush.com" }
    ]
  }'

What you'll get back

Returns a JSON object with three top-level fields: results is an object keyed by domain, then by engine; leaderboard is an array of ranked result objects; and request_metadata is an object summarizing the request context.

{
  "results": {},
  "leaderboard": [
    {
      "rank": 1,
      "domain": "example.com",
      "link_presence": 1,
      "brand_presence": 1,
      "share_of_voice": 0.75,
      "is_primary_target": true
    }
  ],
  "request_metadata": {
    "source": "example.com",
    "engines": ["ai-overview"],
    "primary": "Example",
    "competitors": ["Competitor"]
  }
}

TRY ITLIVE · 40000 ATOMS

API key

Loading your default key…

The full key is used to call the gateway and stays in this tab — never sent to orbit or saved.

About this endpoint

What it does

Returns an AI search leaderboard for a primary target and up to 10 competitors, using the requested source and engines. The response includes a domain-by-engine results map, a ranked leaderboard, and request metadata echoing the submitted inputs.

Request Body

Parameter	Type	Mandatory	Description
scope	ENUM	No	Scope used for matching targets. Allowed values: `domain`, `base_domain`, `url`. Default: `base_domain`.
source	String	Yes	Source identifier to use for the leaderboard request.
engines	String Array	Yes	AI search engines to include. Each item is a string, for example `ai-overview`, `chatgpt`, `perplexity`, `gemini`, `ai-mode`.
primary	Object	Yes	Primary target definition. Use `primary.brand` and `primary.target` for the nested values.
primary.brand	String	No	Brand name for the primary target.
primary.target	String	No	Target value for the primary entry.
competitors	Object Array	Yes	Competitor target definitions. Array items contain `brand` and `target`. Minimum items: 1. Maximum items: 10.
competitors[].brand	String	No	Brand name for a competitor.
competitors[].target	String	No	Target value for a competitor.

Response

Returns a JSON object with three top-level fields: results is an object keyed by domain, then by engine; leaderboard is an array of leaderboard entries; and request_metadata is an object echoing the request context. The success response shape is therefore an object wrapper with these three fields.

Parameter	Type	Mandatory	Description
results	Object	No	Keyed by domain, then by engine. Each engine entry contains `link_presence` and `brand_presence` integer fields.
leaderboard	Object Array	No	Ranked leaderboard entries. Each item includes `rank`, `domain`, `link_presence`, `brand_presence`, `share_of_voice`, and `is_primary_target`.
request_metadata	Object	No	Echoes request metadata. Contains `source`, `engines`, `primary`, and `competitors`.

Body

Name

Type

Description

bodyOPTIONAL

object

—

▣ ENDPOINT 05 / 06

GET

prompts by target

https://api.eu.apyhub.com/se-ranking/ai-search/v1/ai-search/prompts-by-target

QUICKSTART

GUIDE

Quickstart

Fetch prompts for a target search term with the required query parameters.

curl -X GET "https://api.eu.apyhub.com/se-ranking/ai-search/v1/ai-search/prompts-by-target?engine=ai-mode&target=seranking.com&source=us&scope=base_domain" \
  -H "apy-token: $APY_TOKEN"

What you'll get back

Returns a JSON object with date as a string date, total as an integer, and prompts as an array of objects. Each prompt object can include type, answer (with text and links), prompt, and volume.

{
  "date": "2026-07-27",
  "total": 1,
  "prompts": [
    {
      "type": "Link",
      "answer": {
        "text": "Some example answer",
        "links": ["https://example.com"]
      },
      "prompt": "ai search prompts",
      "volume": 100
    }
  ]
}

TRY ITLIVE · 10000 ATOMS

API key

Loading your default key…

The full key is used to call the gateway and stays in this tab — never sent to orbit or saved.

About this endpoint

What it does

Returns a list of prompts for the specified engine, target, source, and scope, with optional sorting, pagination, and volume/keyword/character filters applied.

Query Parameter(s)

Attribute	Type	Mandatory	Description
engine	String	Yes	The search engine identifier.
target	String	Yes	The target query/value to search prompts for.
source	String	Yes	The source query/value used for the search.
scope	ENUM	Yes	Scope used for matching.<br>- `domain`<br>- `base_domain` (default)<br>- `url`
sort	ENUM	No	Sort field.<br>- `volume` (default)<br>- `type`<br>- `snippet_length`
limit	Integer	No	Maximum number of prompts to return. Default: `100`. Maximum: `1000`.
offset	Integer	No	Number of records to skip. Default: `0`.
sort_order	ENUM	No	Sort direction.<br>- `asc`<br>- `desc` (default)
filter[volume][from]	Integer	No	Minimum `volume` value to include.
filter[volume][to]	Integer	No	Maximum `volume` value to include.
filter[keyword_count][from]	Integer	No	Minimum keyword count to include.
filter[keyword_count][to]	Integer	No	Maximum keyword count to include.
filter[characters_count][from]	Integer	No	Minimum character count to include.
filter[characters_count][to]	Integer	No	Maximum character count to include.
filter[multi_keyword_included]	String	No	Filter by multi-keyword inclusion.
filter[multi_keyword_excluded]	String	No	Filter by multi-keyword exclusion.

Response

Returns a JSON object with date as a string in date format, total as an integer, and prompts as an array of objects. Each prompt object includes type as a string, answer as an object, prompt as a string, and volume as an integer.

Parameter	Type	Mandatory	Description
date	String	No	Response date in `date` format.
total	Integer	No	Total number of prompts returned or matched.
prompts	Object Array	No	Array of prompt objects. Each item contains `type`, `answer`, `prompt`, and `volume`.
prompts[].type	String	No	Prompt type, e.g. `Link` or `Brand`.
prompts[].answer	Object	No	Answer object containing `text` and `links`.
prompts[].answer.text	String	No	Answer text.
prompts[].answer.links	String Array	No	Links associated with the answer.
prompts[].prompt	String	No	The prompt text.
prompts[].volume	Integer	No	Prompt volume.

Query parameters

Name

Type

Description

sortOPTIONAL

string

volume · type · snippet_length

—

DEFAULT volume

limitOPTIONAL

integer

—

DEFAULT 100

scopeREQUIRED

string

domain · base_domain · url

—

DEFAULT base_domain

engineREQUIRED

string

—

offsetOPTIONAL

integer

—

DEFAULT 0

sourceREQUIRED

string

—

targetREQUIRED

string

—

sort_orderOPTIONAL

string

asc · desc

—

DEFAULT desc

filter[volume][to]OPTIONAL

integer

—

filter[volume][from]OPTIONAL

integer

—

filter[keyword_count][to]OPTIONAL

integer

—

filter[keyword_count][from]OPTIONAL

integer

—

filter[characters_count][to]OPTIONAL

integer

—

filter[characters_count][from]OPTIONAL

integer

—

filter[multi_keyword_excluded]OPTIONAL

string

—

filter[multi_keyword_included]OPTIONAL

string

—

▣ ENDPOINT 06 / 06

GET

prompts by brand

https://api.eu.apyhub.com/se-ranking/ai-search/v1/ai-search/prompts-by-brand

QUICKSTART

GUIDE

Quickstart

Fetch brand-related prompts by passing the required query parameters for engine, brand, and source.

curl -X GET "https://api.eu.apyhub.com/se-ranking/ai-search/v1/ai-search/prompts-by-brand?engine=perplexity&brand=SE%20Ranking&source=us" \
  -H "apy-token: $APY_TOKEN"

What you'll get back

Returns a JSON object with date as a string in YYYY-MM-DD format, total as an integer, and prompts as an array of prompt objects.

Each prompt object can include type (string), answer (object with text and links), prompt (string), and volume (integer).

{
  "date": "2026-07-27",
  "total": 1,
  "prompts": [
    {
      "type": "Brand",
      "answer": {
        "text": "Example answer",
        "links": ["https://example.com"]
      },
      "prompt": "Example prompt",
      "volume": 100
    }
  ]
}

TRY ITLIVE · 10000 ATOMS

API key

Loading your default key…

The full key is used to call the gateway and stays in this tab — never sent to orbit or saved.

About this endpoint

What it does

Returns a list of prompts for a given brand and source, with optional sorting and filtering applied through query parameters. The response includes the report date, the total number of prompts, and an array of prompt objects.

Query Parameter(s)

Attribute	Type	Mandatory	Description
engine	String	Yes	Search engine to query.
brand	String	Yes	Brand to retrieve prompts for.
source	String	Yes	Source to retrieve prompts from.
sort	ENUM	No	Sort field. Allowed values: `volume`, `type`, `snippet_length`. Default: `volume`.
limit	Integer	No	Maximum number of results to return. Default: `100`. Maximum: `1000`.
offset	Integer	No	Number of results to skip before returning records. Default: `0`.
sort_order	ENUM	No	Sort direction. Allowed values: `asc`, `desc`. Default: `desc`.
filter[volume][to]	Integer	No	Upper bound for `volume`.
filter[volume][from]	Integer	No	Lower bound for `volume`.
filter[keyword_count][to]	Integer	No	Upper bound for `keyword_count`.
filter[keyword_count][from]	Integer	No	Lower bound for `keyword_count`.
filter[characters_count][to]	Integer	No	Upper bound for `characters_count`.
filter[characters_count][from]	Integer	No	Lower bound for `characters_count`.
filter[multi_keyword_excluded]	String	No	Filter prompts by excluded multi-keyword value.
filter[multi_keyword_included]	String	No	Filter prompts by included multi-keyword value.

Response

Returns a JSON object with date as a string in date format, total as an integer, and prompts as an array of objects. Each item in prompts contains type as a string, answer as an object with text and links, prompt as a string, and volume as an integer.

Attribute	Type	Mandatory	Description
date	String	No	Report date in `date` format.
total	Integer	No	Total number of prompts returned.
prompts	Object Array	No	Array of prompt objects.
prompts[].type	String	No	Prompt type, for example `Link` or `Brand`.
prompts[].answer	Object	No	Answer details.
prompts[].answer.text	String	No	Answer text.
prompts[].answer.links	String Array	No	Links associated with the answer.
prompts[].prompt	String	No	Prompt text.
prompts[].volume	Integer	No	Prompt volume.

Query parameters

Name

Type

Description

sortOPTIONAL

string

volume · type · snippet_length

—

DEFAULT volume

brandREQUIRED

string

—

limitOPTIONAL

integer

—

DEFAULT 100

engineREQUIRED

string

—

offsetOPTIONAL

integer

—

DEFAULT 0

sourceREQUIRED

string

—

sort_orderOPTIONAL

string

asc · desc

—

DEFAULT desc

filter[volume][to]OPTIONAL

integer

—

filter[volume][from]OPTIONAL

integer

—

filter[keyword_count][to]OPTIONAL

integer

—

filter[keyword_count][from]OPTIONAL

integer

—

filter[characters_count][to]OPTIONAL

integer

—

filter[characters_count][from]OPTIONAL

integer

—

filter[multi_keyword_excluded]OPTIONAL

string

—

filter[multi_keyword_included]OPTIONAL

string

—

▣ COMMON ERRORS

Errors any endpoint can return

400bad_request

Required parameter missing or malformed body.

401unauthorized

API key missing, revoked, or not authorized for this service.

429rate_limited

Your plan's per-second rate exceeded. Retry with exponential backoff.

503upstream_busy

Backend temporarily unavailable. Try again in a few seconds.