Start Run
Start a new agent run (shadow of POST /research).
Accepts a single input field — a string (used as the question) or a JSON object (serialized into the question, with the raw object persisted to the job so the agent can read it). All other fields match POST /research.
Requires USER or API_KEY authentication (not capability-based). Expert ACL is validated upstream by _validate_run_expert_acl. The run is pollable under both /run/{job_id} and /research/{job_id}.
Returns: ResearchJobResponse with job_id for tracking
Request
- Base URLhttps://api.grep.ai (the document declares no server; this is the origin it was published from)
- URLhttps://api.grep.ai/api/v1/run
- Authnone declared
Request body
If True, implement changes (write code, create PRs) instead of producing a research report.
Additional thesis to explore
If True (default for API), produce pure markdown without widget:html blocks. Set to False for widget:html blocks.
Research approach. If not provided, auto-determined from question.
If True, skip HTML reporter and return raw markdown + structured sources for benchmark evaluation.
Additional context for the research
Custom MCP tools to use
Custom skills to use
Research effort level. When omitted, uses the agent default depth, or low if none is configured. New values: 'low' (~10-20s, Haiku), 'medium' (~2-3 min), 'high' (~8-15 min), 'build' (Opus 4.6, creative/app building). Legacy values: 'ultra_fast'→low, 'deep'→medium, 'ultra_deep'→high.
Expert ID from registry (e.g., 'patent-expert', 'medical-expert'). Overrides auto-detection.
Start date for content filtering (YYYY-MM-DD)
If True, job originated from an agent-suggested topic card. Bypasses the person-search private_individual gate (only). Does NOT bypass tier2_strike moderation.
Vendored agentrun harness variant for this job (advanced/experimental). Omit to use the deployment default. Ignored by the claude_agents runtime.
Optional pre-generated job ID. Use this when workspace files have been uploaded.
Custom output JSON Schema (draft-07). The request 422s with the reason when the schema cannot be compiled; annotation keywords outside the draft-07 vocabulary are dropped.
Leave unset unless the user explicitly asks for a spending cap; never estimate one. Optional maximum metered provider spend for each logical run. The minimum depends on effort, because a run pays for its prompt/skill preamble before it can issue a tool call: low/ultra_fast $0.50, medium/deep and build $2.50, high/ultra_deep $5.00. The normal billing margin still applies when provider cost is converted to credits.
Override the AI model used for research. If provided, bypasses automatic tier-based model selection. Accepts a concrete model id (e.g., 'claude-opus-4-6', 'gpt-5.6-luna', 'deepseek-v4-pro') or a registry alias (e.g., 'luna', 'glm', 'deepseek'). Internal/benchmark use only.
Research model config profile name from RESEARCH_MODEL_CONFIGS (e.g., 'opus46_full', 'opus46_haiku_searcher', 'haiku_full')
Output type: 'report' (default) for a markdown report, 'data_explorer' for a tabular data app, 'structured_output' to return ONLY the structured JSON payload — no report and no artifact is written, so a run whose result is consumed by code skips the write-up entirely. Pair it with json_schema to shape the payload.
Workspace directory path (e.g. 'experts/flutterwave_mcc'). If set, reads instructions.md from this directory and uses it as the agent's system prompt. The job runs under a dedicated project brain.
Render the report with widget:html visualisations (cover page, charts, diagrams, callouts). Default false produces a clean markdown report (headings, prose, markdown tables, inline citations) suitable for API/MCP consumers piping the output into their own pipelines. The Parcha UI sends true to get the rich rendered experience.
Language for research report (ISO 639-1 code: en, es, fr, de, pt, ja, ko, zh-CN, it, nl)
Agent runtime harness. When omitted, resolves to the server default (GREP_DEFAULT_RESEARCH_HARNESS, else claude_agents) — see default_research_harness(). An explicit value always wins.
Search tool variant for eval: 'anthropic_native_websearch', 'parallel_mcp_native', 'custom_wrapped_parallel'
If True, skip clarification questions even if the planner requests them. Useful for automated/webhook jobs.
If True, run moderation but don't block job on violations. Parcha admins may auto-enable this.
Optional filter for message types to send. E.g., ['Thinking', 'UserMessage', 'status']. If None, sends ALL messages.
Webhook URL to receive ALL status messages in real-time. Each message POSTed with: job_id, message, message_type, timestamp, metadata
End date for content filtering (YYYY-MM-DD)
Webhook URL for completion notification
Website URL for enriched context
Response
Successful Response
True when this response replays a previous request with the same idempotency key.
Changes
No recorded changes to this operation across all 1 revision of this API.