---
title: "Start Run"
method: POST
path: "/api/v1/run"
tags: ["grep-public-api"]
---

# Start Run

`POST /api/v1/run`

## Request

- Base URL: `https://api.grep.ai` (the document declares no server; this is the origin it was published from)
- URL: `https://api.grep.ai/api/v1/run`
- Auth: none declared

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 body

- RunInput: Input for ``POST /run`` — the agent-run shadow of ``POST /research``. Slice B (additive): ``/run`` is a thin alias over ``/research`` that accepts a single polymorphic ``input`` field instead of ``question``: * ``input`` is a **string** → used verbatim as the run question. * ``input`` is a **JSON object** → JSON-serialized into the question and the raw object persisted to ``Job.input_payload['structured_input']`` so the agent can read the original structure back. Every OTHER field is inherited unchanged from ``ResearchJobInput`` (``effort``/``depth``, ``approach``, ``expert_id``, ``response_language``, ``webhook_url``, etc.) so a ``/run`` call has the full ``/research`` surface. ``question`` and ``structured_input`` are inherited internals that callers do NOT set directly — ``input`` drives both. They are kept out of the request schema via ``exclude``/``Field(exclude=...)`` so the public OpenAPI for ``/run`` advertises ``input`` as the one entrypoint.
  - `action_mode` boolean: If True, implement changes (write code, create PRs) instead of producing a research report.
  - `additional_thesis` string, nullable: Additional thesis to explore
  - `api_mode` boolean: If True (default for API), produce pure markdown without widget:html blocks. Set to False for widget:html blocks.
  - `approach` 'scientific' | 'technical' | 'creative' | 'general', nullable: Research approach. If not provided, auto-determined from question.
  - `benchmark_mode` boolean: If True, skip HTML reporter and return raw markdown + structured sources for benchmark evaluation.
  - `context` string, nullable: Additional context for the research
  - `custom_mcp_tools` string[], nullable: Custom MCP tools to use
  - `custom_skills` string[], nullable: Custom skills to use
  - `effort` 'ultra_fast' | 'deep' | 'ultra_deep' | 'low' | 'medium' | 'high' | 'build': 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` string, nullable: Expert ID from registry (e.g., 'patent-expert', 'medical-expert'). Overrides auto-detection.
  - `from_date` string, nullable: Start date for content filtering (YYYY-MM-DD)
  - `from_suggested_topic` boolean: If True, job originated from an agent-suggested topic card. Bypasses the person-search private_individual gate (only). Does NOT bypass tier2_strike moderation.
  - `harness_sha` string, nullable: Vendored agentrun harness variant for this job (advanced/experimental). Omit to use the deployment default. Ignored by the ``claude_agents`` runtime.
  - `input` union, required: The run input. Either a plain string (used as the question) or a JSON object (serialized into the question and persisted raw so the agent can read the structured input).
    - string
    - object
  - `job_id` string, nullable: Optional pre-generated job ID. Use this when workspace files have been uploaded.
  - `json_schema` object, nullable: 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.
  - `max_cost_usd` number, nullable: 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.
  - `model` string, nullable: 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.
  - `model_config_profile` string, nullable: Research model config profile name from RESEARCH_MODEL_CONFIGS (e.g., 'opus46_full', 'opus46_haiku_searcher', 'haiku_full')
  - `output_type` string, nullable: 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.
  - `project` string, nullable: 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_rich_report` boolean: 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.
  - `response_language` string: Language for research report (ISO 639-1 code: en, es, fr, de, pt, ja, ko, zh-CN, it, nl)
  - `runtime` 'claude_agents' | 'agentrun', nullable: 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_override` string, nullable: Search tool variant for eval: 'anthropic_native_websearch', 'parallel_mcp_native', 'custom_wrapped_parallel'
  - `skip_clarification` boolean: If True, skip clarification questions even if the planner requests them. Useful for automated/webhook jobs.
  - `skip_moderation_block` boolean: If True, run moderation but don't block job on violations. Parcha admins may auto-enable this.
  - `status_webhook_filter` string[], nullable: Optional filter for message types to send. E.g., ['Thinking', 'UserMessage', 'status']. If None, sends ALL messages.
  - `status_webhook_url` string, nullable: Webhook URL to receive ALL status messages in real-time. Each message POSTed with: job_id, message, message_type, timestamp, metadata
  - `to_date` string, nullable: End date for content filtering (YYYY-MM-DD)
  - `webhook_url` string, nullable: Webhook URL for completion notification
  - `website` string, nullable: Website URL for enriched context

## Response `200`

Successful Response

- ResearchJobResponse: Response from starting a run.
  - `downgrade` object, nullable
  - `idempotent_replay` boolean: True when this response replays a previous request with the same idempotency key.
  - `job_id` string, required
  - `message` string, nullable
  - `slug` string, nullable
  - `status` string, required

## Other responses

- `422`: Validation Error

---

[API](https://skmtc.dev/grep/apis/grep-api.md) - [All operations](https://skmtc.dev/grep/apis/grep-api/llms.txt) - [OpenAPI document](https://skmtc.dev/grep/apis/grep-api/revisions/3719dd7f43ec?raw)