Start a Deep Research run

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" }
  }'

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?" }'

{
  "runId": "01a0d2f4-3b1e-7c8a-9f21-4e6b7a8c9d02",
  "status": "RUNNING",
  "createdAt": "2026-09-22T14:03:11.402Z"
}

{
  "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" }
    ]
  }
}

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" }
  }'

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?" }'

{
  "runId": "01a0d2f4-3b1e-7c8a-9f21-4e6b7a8c9d02",
  "status": "RUNNING",
  "createdAt": "2026-09-22T14:03:11.402Z"
}

{
  "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" }
    ]
  }
}

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 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. The run belongs to the member who created the key, and only that member can read it back.

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

string

required

Your company’s slug. Find it in your Dashboard URL, right after /s/:https://app.gowindmill.com/s/{companySlug}/home

Body parameters

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.

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.

Show supported fields

string[]

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

string

One employee; merged into employeeIds.

string[]

The direct reports of these managers.

string

One manager; merged into managerIds.

string[]

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

string

One manager; merged into ancestorManagerIds.

string[]

Members of any of these groups.

string

One group; merged into employeeGroupIds.

string

Match employees by name or email.

string

default:"CURRENT"

Employment scope: CURRENT, FORMER, or ALL.

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.

Show timeRange properties

string

required

Start date, YYYY-MM-DD, inclusive.

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.

string

required

The run’s id. Pass it to Get a run.

string

required

RUNNING once the run is under way. FAILED when Windmill created the run but could not start it. Get the run for the reason, then start a new one.

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:

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

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" }
  }'

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?" }'

{
  "runId": "01a0d2f4-3b1e-7c8a-9f21-4e6b7a8c9d02",
  "status": "RUNNING",
  "createdAt": "2026-09-22T14:03:11.402Z"
}

{
  "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" }
    ]
  }
}

Getting started

Windy

Org Chart

Review Cycles

Pulse surveys

Feedback

Features

Company settings

Account & admin

Developers

Data

Security and Compliance

Authorization

Path parameters

Body parameters

Response

Errors

​Authorization

​Path parameters

​Body parameters

​Response

​Errors

Authorization

Path parameters

Body parameters

Response

Errors