> ## Documentation Index
> Fetch the complete documentation index at: https://help.gowindmill.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Start a Deep Research run

> Start a Deep Research run from a prompt and get back a run id you can read until the report is ready.

Starts a Deep Research run: Windy plans the research, sends researchers to gather evidence across your company's connected tools, and writes a report. The call returns as soon as the run is queued. Read the run with [Get a run](/api-reference/deep-research/get-run) and the returned `runId` until its status is `COMPLETED` or `FAILED`, then open the report from the run's `output`.

```
POST /api/v2/c/{companySlug}/deep-research
```

Runs take minutes, not seconds.

## Authorization

This endpoint works with any valid [API key](/api-reference/overview#authentication). The run belongs to the member who created the key, and only that member can read it back.

> [!WARNING]
>
> **The key's creator must be in the org chart.** Deep Research researches on behalf of a person, so the member who created the API key must have an employee record in your company. A key created by a member without one returns `404 Not Found`.

## Path parameters

**companySlug** `string` *required*

Your company's slug. Find it in your Dashboard URL, right after `/s/`:

`https://app.gowindmill.com/s/{companySlug}/home`

## Body parameters

**prompt** `string` *required*

The research question or task, 1 to 4,000 characters. State the outcome you want from the report. Windy infers the people and the period from the prompt when you don't pass `employeeFilter` or `timeRange`.

**employeeFilter** `object`

The employees the research is about. When you pass it, every researcher stays inside this set. When you omit it, Windy picks people from the prompt, and the scope can end up wider than you intended.

This filter is a subset of the employee filter the other endpoints accept. It has only the fields below; any other field fails validation with a `400`.

**supported fields**

**employeeFilter.employeeIds** `string[]`

Only these employees. They also become the report's subjects.

**employeeFilter.employeeId** `string`

One employee; merged into `employeeIds`.

**employeeFilter.managerIds** `string[]`

The direct reports of these managers.

**employeeFilter.managerId** `string`

One manager; merged into `managerIds`.

**employeeFilter.ancestorManagerIds** `string[]`

Everyone in these managers' reporting trees, direct and indirect.

**employeeFilter.ancestorManagerId** `string`

One manager; merged into `ancestorManagerIds`.

**employeeFilter.employeeGroupIds** `string[]`

Members of any of these groups.

**employeeFilter.employeeGroupId** `string`

One group; merged into `employeeGroupIds`.

**employeeFilter.query** `string`

Match employees by name or email.

**employeeFilter.status** `string` (default: CURRENT)

Employment scope: `CURRENT`, `FORMER`, or `ALL`.

**timeRange** `object`

The period the research covers, as whole days in the key creator's timezone. When you pass it, every researcher stays inside it. When you omit it, Windy infers the period from the prompt.

**timeRange properties**

**timeRange.from** `string` *required*

Start date, `YYYY-MM-DD`, inclusive.

**timeRange.to** `string` *required*

End date, `YYYY-MM-DD`, inclusive. Must be on or after `from`.

## Response

A `201` means the run exists. Check `status`: it is `RUNNING` in the normal case.

**runId** `string` *required*

The run's id. Pass it to [Get a run](/api-reference/deep-research/get-run).

**status** `string` *required*

`RUNNING` once the run is under way. `FAILED` when Windmill created the run but could not start it. [Get the run](/api-reference/deep-research/get-run) for the reason, then start a new one.

**createdAt** `string` *required*

ISO 8601 time the run was started.

## Errors

| Status | When |
| - | - |
| `400 Validation error` | The prompt is empty or over 4,000 characters, `employeeFilter` has a field this run does not accept, or `timeRange` is missing a bound or runs backwards. The `details` list names each problem. |
| `401 Unauthorized` | The API key is missing, malformed, expired, or revoked. |
| `400 Bad Request` | `employeeFilter.employeeIds` or `employeeFilter.employeeId` names someone who isn't an employee in your company. |
| `404 Not Found` | The company slug is wrong, or the key's creator has no employee record. |

Validation errors carry the field path so you can fix the request:

```json theme={null}
{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Request validation failed",
    "requestId": "01a0d2f4-3b1e-7c8a-9f21-4e6b7a8c9d01",
    "details": [
      { "path": ["employeeFilter"], "message": "Unrecognized key: \"jobTitles\"" }
    ]
  }
}
```

```bash Start a run about one team theme={null}
curl -X POST \
  'https://api.gowindmill.com/api/v2/c/acme/deep-research' \
  -H 'Authorization: Bearer wm_api_xxxxxxxxxxxxxxxxxxxx' \
  -H 'Content-Type: application/json' \
  -d '{
    "prompt": "How did the platform team'\''s delivery pace change over the summer, and what drove it?",
    "employeeFilter": { "ancestorManagerIds": ["cm3k9x2p40001l8f0h7q1v9zt"] },
    "timeRange": { "from": "2026-06-01", "to": "2026-08-31" }
  }'
```

```bash Start a run from a prompt only theme={null}
curl -X POST \
  'https://api.gowindmill.com/api/v2/c/acme/deep-research' \
  -H 'Authorization: Bearer wm_api_xxxxxxxxxxxxxxxxxxxx' \
  -H 'Content-Type: application/json' \
  -d '{ "prompt": "What themes come up in engineering retros this quarter?" }'
```

```json 201 Created theme={null}
{
  "runId": "01a0d2f4-3b1e-7c8a-9f21-4e6b7a8c9d02",
  "status": "RUNNING",
  "createdAt": "2026-09-22T14:03:11.402Z"
}
```

```json 400 Validation error theme={null}
{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Request validation failed",
    "requestId": "01a0d2f4-3b1e-7c8a-9f21-4e6b7a8c9d01",
    "details": [
      { "path": ["timeRange", "to"], "message": "Invalid input: expected string, received undefined" }
    ]
  }
}
```


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.