# CEP Finder (ListeningMind)

> Give one keyword (category, product, service or brand) and it finds category entry points (CEPs) from real search paths, related searches, search volumes, SERPs and AI Overviews, then ranks them in a report. Marketers and brand managers use it to choose campaign situations and messages. Data comes from ListeningMind DaaS search behavior and Google results for Korea, Japan and the US.

Korean: 이 카테고리를 사람들은 어떤 상황에서 찾기 시작하나(카테고리 진입 상황 지도) · Japanese: 人はどんな状況でこのカテゴリーを探し始めるか(カテゴリー・エントリー・ポイント地図)

## Use it as an agent
- [MCP server](https://daas-cep.listeningmind.ai/mcp): Streamable HTTP, JSON-RPC. 15 app tools plus app_guide, result store tools (results_sync, results_list, results_get, results_compare, results_export) and settings sweeps (plan_batch, batch_status)
- WebMCP: every page of this app registers the same tools in `document.modelContext` for a browser agent; calls that spend credits ask the person on the page
- [OpenAPI](https://daas-cep.listeningmind.ai/.well-known/openapi.json): the same tools as a REST contract (operationId = tool name)
- [agents.md](https://daas-cep.listeningmind.ai/agents.md): step-by-step guide · [API catalog](https://daas-cep.listeningmind.ai/.well-known/api-catalog) · [MCP server card](https://daas-cep.listeningmind.ai/.well-known/mcp/server-card.json)
- Every page answers `Accept: text/markdown` with a markdown version
- Tools of kind run or delete spend credits or delete data: over MCP the call returns confirm_url for a person, then call confirmation_status
- Accounts: reading results and history is open. Starting a run or changing data needs a ListeningMind member: the person approving confirm_url signs in or [signs up](https://daas-cep.listeningmind.ai/_lm/auth/signup); other changes over MCP need the member's agent key (LM-User-Key header, created at https://daas-cep.listeningmind.ai/_lm/account)

## What you give and what you get
- Inputs: Keyword (required), field to pin the meaning (optional), market (kr/jp/us), focal brand (optional), competitors (optional), depth (quick/standard/deep), report language (ko/ja/en). Optionally an edited meaning result (category anchor, seeds, trigger candidates, excludes).
- Outputs: HTML report (CEP map, priorities and triage, brand links, time series and seasonality, evidence, readiness verdict), cep_map.json data, PDF (A4/Letter).
- Cost: Data API credits (median actual use of recent Korean runs, computed by the app): quick about 19.7K (18.6K-20K, 8 runs), standard about 48.6K (40.5K-63.8K, 8 runs), deep about 61.7K (35.8K-76.8K, 8 runs), plus LLM (Gemini) calls. The meaning preview uses one LLM call only. Run time is not stored, so it is unknown (minutes; deep is slowest).

## How a result is made (in order)
1. `list_runs`: Check for an existing analysis of the same keyword first (reuse costs 0 credits).
2. `resolve_sense`: Fix the keyword's meaning and review or edit seeds, trigger candidates and excludes.
3. `start_build`: Start the analysis after the person confirms (spends credits).
4. `get_job`: Read progress until status is done.
5. `get_report`: Open the finished report.
6. `get_cep_map`: Read the JSON data when numbers are needed.
7. `download_report_pdf`: Get a PDF for sharing.
8. `prepare_rerun`: To re-run with the same conditions, load them and pass them to start_build.
9. `delete_run`: Remove runs that are no longer needed.

Run stages reported by the app: queued → start → resolve → collect → triggers → volumes → serp → synthesize → metrics → evidence → assemble → done → error → canceled

## Method (how the analysis works)
1. Fix the keyword's meaning first: category anchor, seeds, entry-situation candidates and exclude terms (a person can edit them).
2. Collect related searches for the keyword and seeds, then real search paths per entry situation.
3. Fetch search volumes in bulk and collect Google SERPs and AI Overviews.
4. Synthesize category entry points (CEPs) from this evidence.
5. Score each CEP for brand links, triage, time series and seasonality, and collect its evidence.
6. Assemble and validate cep_map and render the report with a readiness verdict.

## Reading the result
- Read readiness.verdict first: it tells how far the map can be trusted.
- ceps is the CEP list with metrics and evidence; use the priorities and triage to pick the situations to act on first.
- brands and the brand links section show which CEPs the focal brand and the competitors are tied to.
- Read the contested and open groups in positions.structure_groups (contested_ceps, open_ceps) together with the brand links.
- category_timeline.yoy and the time series and seasonality section show year-over-year change and seasonal flow; meta.credits_spent records the credits used.

## Requests this app answers well
- Tell me in which situations people start looking for sunscreen
- Build a ranked category entry point map for wireless earbuds in Japan
- Show which moisturizer entry situations our brand and our competitors are each tied to
- Which situations and messages should our US camping chair campaign use, with evidence

## Continue in another app
- [ICSS](https://daas-icss.listeningmind.ai/llms.txt) (MCP `https://daas-icss.listeningmind.ai/mcp`): When you want to test hypotheses about these situations with a synthetic consumer panel before real fieldwork. Carry: The same topic and market; ICSS find_cep_run and get_cep_states load this run as its intent-state distribution at 0 credits.
- [Prompt Builder](https://daas-prompt.listeningmind.ai/llms.txt) (MCP `https://daas-prompt.listeningmind.ai/mcp`): When you need the prompts consumers would ask AI in these situations and want to measure the brand's AI visibility. Carry: The keyword, its fixed meaning (as topic), the focal brand and competitors; use the top CEPs to check that the generated prompts cover those situations.

## 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

## Tools
- `resolve_sense` (run, POST /api/resolve): Fixes what the keyword means before a build and proposes the category anchor, seed keywords, entry-situation (trigger) candidates and exclude terms that a person can edit. Use it before start_build when the keyword may be ambiguous or when you want to edit seeds; pass the (edited) result as `sense` to start_build. One LLM call, no Data API credits, usually 15-40 seconds.
- `get_estimate` (read, GET /api/estimate/mine): Expected Data API credits and Lima for one run, for the signed-in member: {credits, low, high, lima, lima_low, lima_high, n, basis, depth, gl}. When the same member ran the same keyword, market and depth in the last 24 hours, it subtracts the expected reuse of that result (basis=cache, the plain figure under plain); otherwise it is the median of recent actual charges for the market and depth. The same figure the run's start response returns and the hub reserves. Signed-in members only. The public plain estimate is the app's own GET /api/estimate (open to everyone, not a hub tool).
- `start_build` (run, POST /api/build): Starts a CEP Finder run that collects related searches, search paths, volumes and SERPs for the keyword, synthesizes category entry points (CEPs) and scores them into a report. Returns job_id and status (queued or running); poll get_job until done. Runs execute one at a time; if 3 jobs are already running or queued the server answers HTTP 429. Spends many Data API credits (see cost) and LLM calls; ask the person before calling.
- `get_job` (read, GET /api/jobs/{job_id}): Returns one job's status (queued, running, done, error, canceled), its progress log (stage, pct, msg, t), error text, and when done the run_id with report_url and json_url. Repeat until status is done, error or canceled, then read the result with get_report or get_cep_map.
- `list_jobs` (read, GET /api/jobs): Lists jobs that are running or queued plus up to 4 jobs finished in the last 10 minutes, with keyword, depth, percent, queue position, error and report_url, and the active count against the limit of 3. Use it to see whether a new build will be accepted or to find a job started elsewhere.
- `cancel_job` (action, POST /api/jobs/{job_id}/cancel): Cancels a job. A queued job is removed at once; a running job stops at its next progress report. Credits already spent are not returned. Returns job_id, status and cancel_requested.
- `get_report` (read, GET /runs/{run_id}/report.html): Returns the saved HTML report of a finished run: CEP map, priorities, triage, brand links, time series, evidence and readiness. Pass lang to re-render the same saved data in another language at no credit cost; download=1 returns it as an attachment.
- `get_cep_map` (read, GET /runs/{run_id}/cep_map.json): Returns the machine-readable cep_map.json of a finished run: meta (keyword, topic, sense, market, credits spent), the CEP list with metrics and evidence, triage and readiness verdict. Use this instead of the HTML report when you need the numbers.
- `download_report_pdf` (read, GET /runs/{run_id}/report.pdf): Converts the run's report to PDF with headless Chromium (cached per paper size) and returns the file. Use for sharing or printing; the first conversion can take up to about a minute.
- `list_runs` (read, GET /api/runs): Lists saved runs, newest first, with run_id, input keyword, topic, sense, market (gl), report language, focal brand, competitors, number of CEPs, readiness, credits spent, depth and creation time. Use it to find an existing analysis before starting a new one.
- `prepare_rerun` (read, POST /api/runs/{run_id}/rerun): Loads the exact input conditions of a saved run without starting anything: params (keyword, topic, gl, focal_brand, competitors, depth, lang, sense) and sense_panel (the confirmed meaning) plus credits_prev. To actually re-run, pass params to start_build after the person confirms the credit cost; this is how the UI re-runs.
- `delete_run` (delete, DELETE /api/runs/{run_id}): Permanently deletes a saved run and its report files. Returns {ok: true}, or 404 if the run does not exist.
- `get_validation_report` (read, GET /validation): Returns the post-hoc validation report (HTML) built from all saved runs; it is regenerated when a newer run exists. Use it to judge how reliable CEP Finder outputs have been. Reads saved runs only.
- `rerun_run` (run, POST /api/runs/{run_id}/rerun): Starts a new run with the stored inputs of an earlier run (the whole pipeline again, data is fetched fresh). Spends Data API credits like start_build. Use prepare_rerun to read the inputs first; poll get_job with the returned job_id.
- `get_report_robots` (read, GET /_lm/report-robots/{run_id}): 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.

## Pages
- [CEP Finder home](https://daas-cep.listeningmind.ai/): Main screen: keyword input, meaning check and edit, run, progress and run history.
- [Validation report](https://daas-cep.listeningmind.ai/validation): Reliability check built from all saved runs.

## Limits
- Markets: kr, jp, us only. Report commentary in ko, ja or en; search terms stay in the market language. Runs execute one at a time; with 3 running or queued, new builds get HTTP 429. Duplicate runs of the same keyword are not blocked, so check list_runs first. Canceling does not return spent credits. Jobs live in server memory and are lost on restart; finished runs stay on disk.

## 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`)
- [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`)
- [Pulse Finder](https://daas-pulse.listeningmind.ai/llms.txt): What is rising in search for a gender and age segment right now (MCP `https://daas-pulse.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)

## Optional
- ListeningMind data and other apps: https://www.listeningmind.com · contact m-support@listeningmind.com