Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.manticscore.com/llms.txt

Use this file to discover all available pages before exploring further.

Market Research is the starting point for most work in ManticScore. You submit a plain-language product idea and the platform runs a five-stage AI pipeline — interpret, search, judge, analyze, and persist — that returns a complete competitive landscape: who already exists in the space, what features matter, where gaps remain, and how strong the opportunity looks overall. Results are cached and versioned, so you can rerun research on the same idea over time and compare what changed.

​
How the pipeline works

Each research job progresses through five stages. You can watch them in real time by streaming the events endpoint.
StageWhat happens
interpretThe AI parses your idea into a structured problem and target market
searchWeb searches are run to collect competitor and market data
judgeAn LLM evaluates the quality of retrieved sources (non-blocking)
analyzeThe collected data is analyzed into structured insights
persistResults are saved and a quality score is computed
The judge stage scores retrieval quality but never blocks a run. Even if it fails, the pipeline continues and you still receive full results.

​
Starting a research job

Send a POST /research request with your idea. The endpoint returns immediately with a job ID — research runs in the background.
​
idea
string
required
Your product idea, up to 5,000 characters. Write it as you would describe it to a colleague.
​
project_id
string
UUID of an existing project to attach this research to. Pass null to keep it unattached.
​
mode
string
default:"market"
Research mode. Use market for standard competitive analysis. Use feature to automatically chain into Feature Deep Research on the top 5 features once market research completes.
curl --request POST \
  --url https://api.manticscore.com/research \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{
    "idea": "A mobile app that helps freelancers track time and automatically generate invoices from project notes",
    "project_id": null,
    "mode": "market"
  }'
Response 202 — new job queued: 
{
  "job_id": "a1b2c3d4-...",
  "status": "queued",
  "position": 0
}
Response 200 — cache hit (identical idea already analyzed): 
{
  "job_id": "a1b2c3d4-...",
  "cache_action": "clone",
  "status": "completed"
}
Use an Idempotency-Key header to safely retry the request without starting duplicate jobs.

​
Streaming progress events

Once you have a job_id, connect to the events endpoint to receive real-time updates. The stream uses newline-delimited JSON (NDJSON) and supports cursor-based resume — if you disconnect, reconnect with cursor=<last_seq> to replay missed events.
curl
curl --request GET \
  --url 'https://api.manticscore.com/research/a1b2c3d4-.../events?cursor=0' \
  --header 'Authorization: Bearer <token>'
Each line of the stream is a JSON object: 
{"v": 1, "event": "stage", "data": {"name": "search", "status": "completed", "queries": 12, "sources": 34, "duration_ms": 8200}}

​
Event types

Emitted immediately on connection. Confirms the stream is live.
{"v": 1, "event": "stream_start", "data": {"request_id": "req_abc", "job_id": "a1b2c3d4-..."}}
Emitted when each pipeline stage starts, completes, is skipped, or fails. Includes timing and counts when available.
{
  "v": 1,
  "event": "stage",
  "data": {
    "name": "analyze",
    "status": "completed",
    "duration_ms": 14300
  }
}
Free-text progress messages within a stage.
{"v": 1, "event": "progress", "data": {"stage": "search", "message": "Fetching competitor pricing pages..."}}
Emitted once when the job completes. Contains the full research artifact.
{
  "v": 1,
  "event": "result",
  "data": {
    "job_id": "a1b2c3d4-...",
    "id": "a1b2c3d4-...",
    "idea": "...",
    "status": "completed",
    "interpretation": {},
    "incumbents": [],
    "emerging": [],
    "features": [],
    "signals": [],
    "white_spaces": [],
    "quality": {}
  }
}
Signals the stream is finished. Always the final event.
{"v": 1, "event": "done", "data": {}}

​
Checking job status

Poll the status endpoint if you prefer not to stream: 
curl --request GET \
  --url https://api.manticscore.com/research/a1b2c3d4-.../status \
  --header 'Authorization: Bearer <token>'

{
  "status": "running",
  "last_event_seq": 15
}

​
Research result shape

Once completed, the result contains the following top-level fields:
​
id
string
required
UUID of this research job.
​
idea
string
required
The original idea text you submitted.
​
status
string
required
Final status: completed or failed.
​
interpretation
object
Structured parse of your idea: problem statement, target user, product type, and market category.
​
incumbents
array
Established competitors in the space, each with name, description, key features, and positioning.
​
emerging
array
Newer or smaller players that are gaining traction but haven’t reached scale.
​
features
array
Features that matter in this market, ranked by prevalence and strategic importance.
​
signals
array
Recent market signals: funding rounds, product launches, hiring trends, press coverage.
​
white_spaces
array
Gaps and underserved opportunities identified from the competitive landscape.
​
quality
object
Quality scores and a go/no-go recommendation based on market characteristics.

​
Additional actions

​
Compare with a previous version

curl
curl --request GET \
  --url https://api.manticscore.com/research/a1b2c3d4-.../diff \
  --header 'Authorization: Bearer <token>'
Returns a structured diff showing which competitors, features, and signals were added or removed since the previous research run on the same idea.

​
Get remix suggestions

curl
curl --request POST \
  --url https://api.manticscore.com/research/a1b2c3d4-.../remix \
  --header 'Authorization: Bearer <token>'
Returns three adjacent pivot ideas based on your completed research — useful when you want to explore related opportunities without starting from scratch.

​
Set reuse scope

Control whether your research can be used as a cache source for other users:
curl
curl --request PATCH \
  --url https://api.manticscore.com/research/a1b2c3d4-.../scope \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{"reuse_scope": "public"}'

​
Limits and credits

Value
Rate limit10 requests / minute
Credit cost3 credits per research job
Free tier20 credits / day
Max idea length5,000 characters
If you hit the rate limit, your request may be captured to a retry queue rather than dropped. ManticScore will attempt to run it when capacity frees up.