---
title: "Start an investigation"
method: POST
path: "/v1/investigations"
tags: ["Investigations"]
---

# Start an investigation

`POST /v1/investigations`

## Request

- Base URL: `https://docs.grepr.ai` (the document declares no server; this is the origin it was published from)
- URL: `https://docs.grepr.ai/v1/investigations`
- Auth: one of:
  - API key in header `GREPR-API-KEY`
  - OpenID Connect (`https://grepr-prod.us.auth0.com/.well-known/openid-configuration`)

Triggers an agent investigation with optional free-form context and returns the new investigation id. The investigation is queued and runs asynchronously once the agent has a free concurrency slot. With issueId, a person hands the agent that issue, which becomes the investigation's subject and records the handoff in its history.

## Request body

- StartInvestigationRequest: Request body for the manual-trigger endpoint. The engineer's user identity is taken from the request's auth context, not the body.
  - `agentId` string, required: TSID of the agent to investigate.
  - `issueId` string: When set, hands the agent this issue (its TSID): the run's subject, which its first message holds and whose history records the handoff. Only a person may hand off an issue, and a handoff can't be a continuation. `null` for a plain run.
  - `next` boolean: With `issueId`, true to have the agent work on the issue next: the run starts ahead of the agent's other queued runs, without stopping a running one. Allowed only with `issueId`; `null` or false for the usual place in the queue.
  - `parentInvestigationId` string: When set, seeds the new investigation from this parent's journalled transcript — a continuation; the parent must belong to `agentId`. `null` for a fresh investigation.
  - `userProvidedContext` string: Free-form context for the agent's first turn, or `null`.

## Response `202`

Investigation queued

- StartInvestigationResponse
  - `investigationId` string

## Other responses

- `400`: An invalid continuation, or a handoff that is also a continuation or to an agent with no issue tools (a handoff's refusals carry an issue error body)
- `401`: Unauthorized
- `403`: No permission to run investigations, or a handoff by anyone but a person, by a person who may not edit the issue, or to an agent that may not view and edit it
- `404`: Agent not found, or the handed issue doesn't exist or the caller can't see it
- `409`: The agent is paused or the continued investigation is still active, or a handoff of a closed issue or to an agent a person removed from it
- `429`: The agent is at its maximum concurrent investigations and its concurrency-limit policy discards new work instead of queueing it (the response carries the id of the recorded DISCARDED investigation), or the agent's or its LLM integration's max tokens are reached (the response carries a code and message).

---

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