# Pulse Finder: agent guide

ListeningMind Audience Pulse. It harvests candidate keywords from seed keywords or categories, measures gender and age share, 48-month search volume and SERP / AI Overview presence, and ranks the things that are surging, new or over-indexing in the chosen segment. Marketers, merchandisers and content planners use it to find next-quarter openings and risks. Data comes from the ListeningMind Data API (trend_finder, intent_finder, keyword_info, SERP, path_finder, cluster_finder). Markets: Korea, Japan, US; the gender and age split exists only for Korea.

## Connect
- MCP: `https://daas-pulse.listeningmind.ai/mcp` (Streamable HTTP). Start with `app_guide`.
- Browser agents: tools are registered on every page through WebMCP (`document.modelContext`).
- REST: `https://daas-pulse.listeningmind.ai/.well-known/openapi.json`

## Approval
- read and action tools run at once.
- run and delete tools need a person's approval. Over MCP the tool returns `confirm_url`; show it to the person, then call `confirmation_status` with the token until state is done.
- In the browser the page shows the person a confirm box.

## Workflow
1. `get_config` (read): Get valid categories, purposes, segments and the credit cap.
2. `interpret_brief` (run): If there is a written request, turn it into run parameters.
3. `suggest_seeds` (run): With a single seed, add seeds that open other demand clusters.
4. `estimate_credits` (read): Check the expected credits and tell the person before starting.
5. `start_run` (run): Start the run.
6. `get_run` (read): Poll until status is done, then read the result.
7. `get_run_evidence` (read): Check coverage and the credit log behind the result.
8. `explain_keyword` (run): Drill into a keyword of interest to see why it rises.
9. `get_keyword_brief_markdown` (read): Get the brief for the drilled keyword.
10. `get_report_markdown` (read): Get the full report as text.
11. `download_trends_csv` (read): Export the table as CSV.

## Inputs
Segment (gender all/f/m, age a13 to a50), categories (beauty, food, ...) or seed keywords (comma separated, e.g. sunscreen, cushion), period (1m/3m/6m/12m), market (kr/jp/us), purpose (discover, campaign, ...), and optionally a plain-language brief, things to exclude and a credit cap.

## Outputs
Ranked entities, tabs for surging, emerging, newcomers and over-indexing keywords, scores with evidence per keyword, harvest coverage and credit log. Keyword drill-down (search paths, clusters, SERP narrative) and keyword brief (Markdown, HTML, PDF). Report as HTML or Markdown, trends CSV, result JSON.

## Cost and time
A run costs roughly 1,000-15,000 Data API credits (server cap 15,000; cached calls are free) plus LLM classification calls, and takes 2-3 minutes. A keyword drill-down costs about 3,830 credits (standard) or 5,480 (deep). Seed suggestions about 260 credits. Reading a brief is one LLM call.

## Limits
Gender and age split only works for gl=kr; jp and us are market-wide. Segment share is derived as the product of the gender and age marginal distributions. UI languages ko/ja/en. A keyword brief exists only after explain_keyword ran for that keyword. Up to 6 seeds by default (max_seeds).

## Method (how the analysis works)
1. Choose seed keywords from the given seeds or categories (a written request can be turned into run parameters).
2. Harvest candidate keywords from the issue index (trend_finder), related queries (intent_finder) and topics mined from SERP and AI Overview.
3. Fetch gender and age share and 48-month volume for each candidate, and widen the harvest if too few pass the floor.
4. Classify type and fit with an LLM and group the queries into the things (entities) they name.
5. Measure when co-searched terms formed and rank the things that are surging, emerging, new or over-indexing in the segment.

## Reading the result
- entities is the ranked list of things; the trending (surging), emerging, newcomers and overindex tabs give scores and evidence per keyword.
- Over-indexing compares the segment's share with baseline_share; segment share is estimated from the gender and age marginals and exists only for Korea.
- coverage (measured pool size, demography_rate) and the credit log from get_run_evidence show how widely the result was measured.
- explain_keyword shows why one keyword rises, from search paths, co-search clusters and SERP.

## Requests this app answers well
- What is surging in beauty right now among women in their 20s in Korea
- Find food keywords newly rising among men in their 30s for next quarter's campaign
- Rank what has been emerging over the last 3 months from the seeds sunscreen and cushion
- List newly appearing search topics in home interior in the US and why they rise

## Continue in another app
- [Demand Forecast](https://daas-forecast.listeningmind.ai/llms.txt) (MCP `https://daas-forecast.listeningmind.ai/mcp`): When a rising item looks worth acting on and you need its next 3-6 months of demand and the launch or campaign timing. Carry: The rising keywords or entity names as seeds (up to 5), with the market.
- [CEP Finder](https://daas-cep.listeningmind.ai/llms.txt) (MCP `https://daas-cep.listeningmind.ai/mcp`): When you need to know in which situations people start looking for the rising item. Carry: The rising keyword and market.

## Using the screens (browser agents)
- `describe_screen`: menus, tabs, fields and buttons of the current screen, and what the page is for
- `go_to`: open a menu or page of this app by its label or path
- `fill_field`: type a value into a field by its label (never presses run; runs go through the run tools, which ask the person)
- `read_this_page`: the text and ids of what the person is looking at

## The ListeningMind apps (same account, same tools, call any of them)
Each app has `/mcp`, `/llms.txt`, `/agents.md` and WebMCP on its pages. `family_apps` and `recommend_app` return this list with addresses.
- [ACO](https://daas-aco.listeningmind.ai/llms.txt): Diagnoses whether a product detail page can be cited by AI answers and used by shopping agents (MCP `https://daas-aco.listeningmind.ai/mcp`)
- [AOO](https://daas-aoo.listeningmind.ai/llms.txt): Measures whether AI agents can get real tasks done on a website (MCP `https://daas-aoo.listeningmind.ai/mcp`)
- [Brand Finder](https://daas-brand.listeningmind.ai/llms.txt): Which brands lead search by generation or field, and what their brand assets are (MCP `https://daas-brand.listeningmind.ai/mcp`)
- [Brand Naming Agent](https://daas-naming.listeningmind.ai/llms.txt): Creates and checks brand name candidates grounded in search data (MCP `https://daas-naming.listeningmind.ai/mcp`)
- [Brand Wiki](https://daas-wiki.listeningmind.ai/llms.txt): Turns a brand website into the entities, wiki pages and evidence AI assistants read (MCP `https://daas-wiki.listeningmind.ai/mcp`)
- [CEP Finder](https://daas-cep.listeningmind.ai/llms.txt): In which situations do people start looking for this category (category entry point map) (MCP `https://daas-cep.listeningmind.ai/mcp`)
- [Creative Finder](https://daas-creative.listeningmind.ai/llms.txt): Finds purchase situations (CEP) in search data and drafts a creative, an image and a video for each (MCP `https://daas-creative.listeningmind.ai/mcp`)
- [Demand Forecast](https://daas-forecast.listeningmind.ai/llms.txt): What category demand looks like in the next 3-6 months and when to launch or campaign (MCP `https://daas-forecast.listeningmind.ai/mcp`)
- [Funnel Leak Finder](https://daas-funnel.listeningmind.ai/llms.txt): Where category search journeys leak to competitors (MCP `https://daas-funnel.listeningmind.ai/mcp`)
- [GEO Audit](https://daas-geo.listeningmind.ai/llms.txt): Checks whether a web page is ready to be read and cited by search engines and AI answer engines (MCP `https://daas-geo.listeningmind.ai/mcp`)
- [ICSS](https://daas-icss.listeningmind.ai/llms.txt): Synthetic consumer panel conditioned on search intent, for surveys and FGDs (MCP `https://daas-icss.listeningmind.ai/mcp`)
- [Intent KG](https://daas-intent.listeningmind.ai/llms.txt): What people look for about a topic, why, and how they choose (Intent Knowledge Graph) (MCP `https://daas-intent.listeningmind.ai/mcp`)
- [Prompt Builder](https://daas-prompt.listeningmind.ai/llms.txt): Finds what consumers ask AI and builds managed brand prompts with AI visibility (MCP `https://daas-prompt.listeningmind.ai/mcp`)
- [Smart Store Suite](https://daas-store.listeningmind.ai/llms.txt): Which Smart Store products to grow, and how to rewrite their titles and detail pages in searchers' words (MCP `https://daas-store.listeningmind.ai/mcp`)
- [Taste Finder](https://daas-taste.listeningmind.ai/llms.txt): In what sensory and emotional words do people choose this (consumer taste report from search data) (MCP `https://daas-taste.listeningmind.ai/mcp`)
- [ListeningMind Data API](https://daas.listeningmind.ai/llms.txt): the search data behind every app (MCP `https://daas.listeningmind.ai/mcp`) · [glossary](https://daas.listeningmind.ai/en/glossary) · [all apps](https://daas.listeningmind.ai/en/apps)

## Run stages
- `seeds`: Choosing seed keywords
- `harvest.issues`: Collecting issue index (trend_finder)
- `harvest.intent`: Expanding related queries (intent_finder)
- `harvest.serp`: Mining topics from SERP and AI Overview
- `harvest.reharvest`: Second pass on AI Overview topics
- `harvest.measure`: Measuring hop-1 results (v3)
- `harvest.hop1`: Hop-1 expansion (v3)
- `harvest.hop2`: Hop-2 expansion (v3)
- `harvest.done`: Candidate keywords collected
- `screen`: Fetching gender/age split and 48-month volume
- `screen.done`: Keyword data received
- `widen`: Too few passed the floor, expanding again
- `classify`: Classifying type and fit (LLM)
- `entities`: Grouping queries into the things they name
- `formation`: Measuring when co-searched terms formed
- `done`: Done

## All tools
### get_config
Returns the option lists the input form uses: markets, categories per market, genders, ages, periods, purposes, credit cap, drill-down cost, and the current account credit balance. Free. Read only, free.
`GET /api/config`
- `lang`: Language of generated text: ko, ja or en.
- `gl`: Search market: kr (Korea), jp (Japan) or us (United States).

### interpret_brief
Turns a plain-language request into run parameters (gender, age, category, seeds, period, purpose) and returns each field with the phrase it came from and the fields it could not read. One paid LLM call, no Data API credits, a few seconds. Fields not supported by the text stay null. Spends ListeningMind Data API credits or paid model calls. Over MCP a person approves it first (you get a confirm link); in the browser the page asks the person. Cost: 1 LLM call, no Data API credits. Usually followed by: suggest_seeds, estimate_credits.
`POST /api/interpret`
- `brief` (required): The request in plain language, e.g. '20대 여성 대상 다음 분기 뷰티 신제품 기회'.
- `lang`: Language of generated text: ko, ja or en.
- `gl`: Search market: kr (Korea), jp (Japan) or us (United States).

### suggest_seeds
Proposes extra seed keywords that open different demand clusters than the given one, for the chosen segment. Uses intent_finder and keyword_info plus one LLM call. About 260 Data API credits (cap 780); the fetched data is cached and reused by the run. Takes 10-40 seconds. Spends ListeningMind Data API credits or paid model calls. Over MCP a person approves it first (you get a confirm link); in the browser the page asks the person. Cost: about 260 Data API credits (cap 780) and 1 LLM call. Time: 10-40 seconds. Usually followed by: estimate_credits.
`POST /api/suggest_seeds`
- `keyword` (required): Base seed keyword (the UI sends the first free_text entry).
- `gl`: Search market: kr (Korea), jp (Japan) or us (United States).
- `gender`: Gender ids, as in start_run.
- `age`: Age ids, as in start_run.
- `lang`: Language of generated text: ko, ja or en.

### estimate_credits
Returns a rough Data API credit estimate for the given run parameters ({credits}). Computed locally, no API calls. Cached calls in the real run cost nothing, so the actual spend is often lower. Read only, free. Usually followed by: start_run.
`POST /api/estimate`
- `gender`: Gender segment ids, multi-select: all, f (female), m (male). Changes which audience the segment share, over-index and floor are computed for. Used only for gl=kr; jp and us have no demographic split. A single string is also accepted. The web form starts with ['f'].
- `age`: Age segment ids, multi-select: all, a13 (13-19), a20s, a20_24, a25_29, a30, a40, a50 (50+), a0 (under 12). Changes the audience the segment share is computed for. Used only for gl=kr. A single string is also accepted. The web form starts with ['a20s'].
- `category`: Category ids whose built-in topics become seed keywords when free_text is empty. Ids: beauty, food, fashion, travel, finance, automobile, health, living, digital, content, pet, kids, hobby, career, or all. get_config lists them with labels per market. Changes the seed topics and therefore the whole candidate pool. A single string is also accepted. The web form starts with ['health'].
- `free_text`: Comma-separated seed keywords. When given, these replace the category topics (up to max_seeds are used). Example: '선크림, 쿠션'.
- `max_seeds`: Maximum number of seed keywords taken from free_text or the categories. More seeds widen the candidate pool and cost more credits. Not in the web form (API only).
- `period`: Recent window compared against the prior 12 months: 1m, 3m, 6m or 12m. A purpose may override it unless period_explicit is true.
- `gl`: Search market: kr (Korea), jp (Japan) or us (United States).
- `lang`: Language of generated text: ko, ja or en.
- `credit_cap`: Hard Data API credit cap for this run; the run stops with an error when it is reached. Default is the server cap (15,000 at the time of writing; get_config.credit_cap). The server does not clamp a higher value, so do not raise it without the person's consent. Not in the web form (API only).
- `pool_cap`: Maximum candidate keywords measured with keyword_info (10 credits each). Larger pools find more long-tail items and cost more. Not in the web form (API only).
- `purpose`: What the person wants to decide. Sets the default period, vocabulary-age probe and preferred result types. discover (product or business opening), sourcing (what to stock), compete (track competitors), audience (understand the segment), campaign (promotion angles), content (content and search traffic), talent (a face or influencer), watch (early warning), risk (what already blew up).
- `brief`: The person's request in plain language. Passed to the classifier as context.
- `exclude`: Plain text naming things to leave out of the result (passed to the classifier).
- `formation`: Run the vocabulary-age probe (Query Finder calls on up to 48 entities, about 5,280 extra credits). Default follows the purpose, otherwise on.
- `period_explicit`: true keeps the given period even when a purpose is set.
- `harvest`: Set to v3 for the novelty-first candidate harvest (extra hop calls, more credits). Omit for the standard harvest. The web UI does not set it.

### start_run
Starts a background run that harvests candidate keywords from the seeds, measures segment share and 48-month volume, classifies them with an LLM and ranks surging, emerging, newcomer and over-indexing things for the segment. Returns {run_id, url}. Poll get_run until status is done or error. Typically 2-3 minutes and roughly 1,000-15,000 Data API credits (capped by credit_cap). Spends ListeningMind Data API credits or paid model calls. Over MCP a person approves it first (you get a confirm link); in the browser the page asks the person. Cost: Data API credits per run: median about 9,400 (roughly 1,000-15,000, server cap 15,000; 중앙값 약 9,400) plus LLM classification calls. The start answer may carry estimate_credits for this run, which the hub reserves instead of the median; cached calls this member paid for earlier are free. Time: 2-3 minutes. Usually followed by: get_run.
`POST /api/runs`
- `gender`: Gender segment ids, multi-select: all, f (female), m (male). Changes which audience the segment share, over-index and floor are computed for. Used only for gl=kr; jp and us have no demographic split. A single string is also accepted. The web form starts with ['f'].
- `age`: Age segment ids, multi-select: all, a13 (13-19), a20s, a20_24, a25_29, a30, a40, a50 (50+), a0 (under 12). Changes the audience the segment share is computed for. Used only for gl=kr. A single string is also accepted. The web form starts with ['a20s'].
- `category`: Category ids whose built-in topics become seed keywords when free_text is empty. Ids: beauty, food, fashion, travel, finance, automobile, health, living, digital, content, pet, kids, hobby, career, or all. get_config lists them with labels per market. Changes the seed topics and therefore the whole candidate pool. A single string is also accepted. The web form starts with ['health'].
- `free_text`: Comma-separated seed keywords. When given, these replace the category topics (up to max_seeds are used). Example: '선크림, 쿠션'.
- `max_seeds`: Maximum number of seed keywords taken from free_text or the categories. More seeds widen the candidate pool and cost more credits. Not in the web form (API only).
- `period`: Recent window compared against the prior 12 months: 1m, 3m, 6m or 12m. A purpose may override it unless period_explicit is true.
- `gl`: Search market: kr (Korea), jp (Japan) or us (United States).
- `lang`: Language of generated text: ko, ja or en.
- `credit_cap`: Hard Data API credit cap for this run; the run stops with an error when it is reached. Default is the server cap (15,000 at the time of writing; get_config.credit_cap). The server does not clamp a higher value, so do not raise it without the person's consent. Not in the web form (API only).
- `pool_cap`: Maximum candidate keywords measured with keyword_info (10 credits each). Larger pools find more long-tail items and cost more. Not in the web form (API only).
- `purpose`: What the person wants to decide. Sets the default period, vocabulary-age probe and preferred result types. discover (product or business opening), sourcing (what to stock), compete (track competitors), audience (understand the segment), campaign (promotion angles), content (content and search traffic), talent (a face or influencer), watch (early warning), risk (what already blew up).
- `brief`: The person's request in plain language. Passed to the classifier as context.
- `exclude`: Plain text naming things to leave out of the result (passed to the classifier).
- `formation`: Run the vocabulary-age probe (Query Finder calls on up to 48 entities, about 5,280 extra credits). Default follows the purpose, otherwise on.
- `period_explicit`: true keeps the given period even when a purpose is set.
- `harvest`: Set to v3 for the novelty-first candidate harvest (extra hop calls, more credits). Omit for the standard harvest. The web UI does not set it.

### get_run
Returns one run: status (running, done, error), progress {stage, pct, steps}, credits spent, params and, when done, the full result (entities, trending, emerging, newcomers, overindex, harvest, coverage). Repeat until status is done or error. Read only, free. Waits up to about 45 s for 'status' to reach done, error; call again if not done. Usually followed by: get_run_evidence, explain_keyword, get_report_markdown.
`GET /api/runs/{run_id}`
- `run_id` (required): Run id returned by start_run or list_runs (shown in the result URL /r/{run_id}).

### list_runs
Lists recent runs with run_id, status, credits, created_at, url, segment label, category, free_text, period and market. Read only, free.
`GET /api/runs`
- `limit`: Maximum runs to return.
- `lang`: Language of the segment labels.

### get_run_evidence
For a finished run, returns Data API calls per endpoint (calls, credits, cache hits), harvest and coverage details, skipped items, baseline share, score weights and seeds. Free. Read only, free.
`GET /api/runs/{run_id}/evidence`
- `run_id` (required): Run id returned by start_run or list_runs (shown in the result URL /r/{run_id}).

### explain_keyword
Explains why one keyword or entity from a finished run is rising: search paths, co-search clusters and SERP, summarised by an LLM with numbers checked against the data. standard costs about 3,830 Data API credits, deep (adds a 6-month path comparison) about 5,480. The result is stored, so asking again is free. 20-90 seconds. Spends ListeningMind Data API credits or paid model calls. Over MCP a person approves it first (you get a confirm link); in the browser the page asks the person. Cost: about 3,830 Data API credits (standard) or 5,480 (deep) plus 1 LLM call; free when already stored. Time: 20-90 seconds. Usually followed by: get_keyword_brief_markdown, download_keyword_brief_pdf.
`POST /api/runs/{run_id}/explain`
- `run_id` (required): Run id returned by start_run or list_runs (shown in the result URL /r/{run_id}).
- `keyword` (required): Keyword exactly as it appears in the run result (row keyword).
- `depth`: standard or deep. The web UI uses standard.
- `lang`: Language of generated text: ko, ja or en.
- `credit_cap`: Credit cap for this drill-down. Default is twice the estimate.

### get_keyword_brief_markdown
Returns {keyword, markdown}: a one-page brief for a keyword that was already drilled into with explain_keyword. Renders stored data only, no credits. 404 if the drill-down was not run. Read only, free.
`GET /api/runs/{run_id}/brief.md`
- `run_id` (required): Run id returned by start_run or list_runs (shown in the result URL /r/{run_id}).
- `keyword` (required): Keyword or entity that was drilled into with explain_keyword.
- `depth`: Depth used in explain_keyword.
- `lang`: Language of the export (ko, ja or en). Omit to use the run's own language.

### get_keyword_brief_html
Returns the printable HTML page of a keyword brief (needs explain_keyword first). download=1 adds an attachment header. Free. Read only, free.
`GET /runs/{run_id}/brief.html`
- `run_id` (required): Run id returned by start_run or list_runs (shown in the result URL /r/{run_id}).
- `keyword` (required): Keyword or entity that was drilled into with explain_keyword.
- `depth`: Depth used in explain_keyword.
- `lang`: Language of the export (ko, ja or en). Omit to use the run's own language.
- `download`: 1 to send as a file download, 0 to view inline.

### download_keyword_brief_pdf
Downloads the keyword brief as a PDF (needs explain_keyword first). Returns 503 when the server has no headless Chrome; then use get_keyword_brief_html. Free. Read only, free.
`GET /runs/{run_id}/brief.pdf`
- `run_id` (required): Run id returned by start_run or list_runs (shown in the result URL /r/{run_id}).
- `keyword` (required): Keyword or entity that was drilled into with explain_keyword.
- `depth`: Depth used in explain_keyword.
- `lang`: Language of the export (ko, ja or en). Omit to use the run's own language.

### get_report_markdown
Returns the full run report as Markdown text. Free. 404 until the run is done. Read only, free.
`GET /runs/{run_id}/report.md`
- `run_id` (required): Run id returned by start_run or list_runs (shown in the result URL /r/{run_id}).
- `lang`: Language of the export (ko, ja or en). Omit to use the run's own language.

### get_report_preview
Returns the full run report as an HTML page for viewing. Free. Read only, free.
`GET /runs/{run_id}/preview.html`
- `run_id` (required): Run id returned by start_run or list_runs (shown in the result URL /r/{run_id}).
- `lang`: Language of the export (ko, ja or en). Omit to use the run's own language.

### download_report_html
Downloads the full run report as a self-contained HTML file. Free. Read only, free.
`GET /runs/{run_id}/report.html`
- `run_id` (required): Run id returned by start_run or list_runs (shown in the result URL /r/{run_id}).
- `lang`: Language of the export (ko, ja or en). Omit to use the run's own language.

### download_trends_csv
Downloads the ranked trend rows as CSV (UTF-8 with BOM). Free. Read only, free.
`GET /runs/{run_id}/trends.csv`
- `run_id` (required): Run id returned by start_run or list_runs (shown in the result URL /r/{run_id}).
- `lang`: Language of the export (ko, ja or en). Omit to use the run's own language.

### download_run_json
Returns the raw result object of a finished run as JSON. Free. Read only, free.
`GET /runs/{run_id}/run.json`
- `run_id` (required): Run id returned by start_run or list_runs (shown in the result URL /r/{run_id}).

### rerun_run
Starts a new run with the same parameters as an earlier run. Returns {run_id, url, from}. Same cost and duration as start_run, minus cached calls. Spends ListeningMind Data API credits or paid model calls. Over MCP a person approves it first (you get a confirm link); in the browser the page asks the person. Cost: same as start_run (cached calls are free). Time: 2-3 minutes. Usually followed by: get_run.
`POST /api/runs/{run_id}/rerun`
- `run_id` (required): Run id returned by start_run or list_runs (shown in the result URL /r/{run_id}).

### delete_run
Deletes a run and its stored drill-downs. Cannot be undone. Deletes data. A person approves it first.
`DELETE /api/runs/{run_id}`
- `run_id` (required): Run id returned by start_run or list_runs (shown in the result URL /r/{run_id}).

### get_report_robots
Returns whether search engines may index this report page (index or noindex), and why: a company member's run or one set by hand is index; a customer's run, and any run that is still going, failed or came back empty, is noindex. Read only; no credits. Read only, free.
`GET /_lm/report-robots/{run_id}`
- `run_id` (required): The report's run id: the id in the report address (for ACO the project id, or project~step).