prompts[] is in recommended order, and
brands[] shows which brands draw search demand in the same space. Use the prompts to plan content, ask them on
answer engines or track the answers in a GEO monitor.
How it finds the prompts
- Product kinds. Keyword data for the market shows the kinds of product people search for under the topic, such
as
sunscreen stickundersunscreen. They are the result’scores[]. - Conditions. For each kind, the research finds the questions that narrow a buyer’s choice, such as skin type,
budget or team size. They are the result’s
cores[].questions. Their options become conditions, together with the variants people search for (tinted sunscreen,sunscreen for oily skin). - Prompts. Conditions combine into prompts up to
depth, each with its measured or estimated searches, in recommended order.
Submit a research task
GET /v1/async/task/{id}, or add webhook.url to the request and
receive it when the task finishes. The task works like any other
async task, and the result is in response. The request schema is in
the API reference.
Submit Prompt Research through
POST /v1/prompt-research only. POST /v1/async/task
rejects taskType: "PROMPT_RESEARCH".Request fields
The body is flat: the research fields and the task options sit at the top level.Markets
USwrites prompts in English. Demand is the monthly average over the last 12 months (demandSource.period: "monthly_average_last_12_months"), so a seasonal term reads lower at its peak than that month’s searches.KRwrites prompts in Korean. Demand counts the last 30 days (demandSource.period: "last_30_days"). The seed is matched against Korean search data, so send it as Korean searchers write it.
language in the result is en for US and ko for KR.
Depth
depth sets how many conditions one prompt combines, and every depth up to it appears in prompts:
Options of one question are alternatives, so a prompt pairs oily skin with a budget and never with dry skin. Each
depth needs at least one prompt, so
limit must be at least depth + 1. depth: 0 returns each kind’s plain
request and the questions people search about the topic.
Read the result
For example, asunscreen run in the US returns a result like this, trimmed to a few entries:
prompts[]
The prompts in recommended order, up to limit entries. Each core’s prompts start with its plain request and its two
price levels, then follow by demand across depths. The cores take turns in proportion to their searches, every plain
request first, so any first part of the list is spread like the whole. Questions people ask to learn about the topic
(intent: "informational") hold about a fifth of the list when the research finds them, because buyers ask them
before they choose. To rank by demand alone, sort by monthlySearchVolume.
cores[]
The product kinds researched, the seed’s own first. Send cores in the request to research the kinds you choose.
brands[] and other fields
brands[] lists brands, manufacturers and product lines people search for in this space, with their
monthlySearchVolume. Their demand stays out of prompts, because prompts do not name brands. Use them as the
competitors to compare your brand with.
Score prompts against your brand
Sendbrand with brandDescription and each prompt gets a fit:
core: the description says your brand offers what the prompt asks for.related: anything the description does not mention.
limit prompts. fit ranks the prompts your brand answers higher; the demand numbers
stay the same.
fit like this:
related. To keep a subtopic
out of the result entirely, use exclude.
From research to a monitor
To track how often AI answers mention your brand on these prompts, feedprompts[] into
POST /v1/monitors. This takes the finished research task, uses its
prompts as the monitor’s prompts and the top ten brands[] as competitors (a brand monitor accepts up to 10), and
creates a daily brand monitor:
tasksPerRun limit (200 on a self-serve account; GET /v1/monitors/capabilities
reports yours), counted for each engine as prompts × location points × samples. Forty prompts on five engines with
one point and one sample each is 200 tasks.
For a category monitor, send "mode": "CATEGORY" with a category, and when the research has more than one
core, map each prompt to its core in promptTopics. See Monitors for both kinds and the full request.
Reading the numbers
- Depth 0 and 1 are measured. A plain request carries its kind’s searches, and a prompt with one condition the
searches of its keyword (
conditions[0].keyword). - Depth 2 and up are estimated. A prompt with two or more conditions is rarely searched as written, so its
number is an estimate (
volumeBasis: "estimated"). Use the estimates to rank prompts. - Broader prompts include narrower ones. The searches for sunscreen include those for mineral sunscreen, so do not add prompts’ numbers together.
- Under 10 searches a month reads
null.volumeReasonsays why:not_searched(nobody searches the condition),part_not_searched(one of its conditions is not searched) orestimate_below_floor(the estimate is under 10). Options fromcores[].questionsstay in the result even when nobody searches them, so a research on a business product often returns manynullprompts. - The numbers are search demand. They count searches for the need behind each prompt in the market, over
demandSource.period.
Errors and billing
A completed task costs 14 credits. A failed task is not charged. See Credits and limits.Rejected at submit
Failed tasks
A failed task hasstatus: "FAILED" and an error string that starts with its code:
Next steps
GEO monitors
Track the prompts you found across AI engines on a schedule.