> ## 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.

# Get a Deep Research run

> Read a Deep Research run to follow its agents and, once it completes, get the finished report.

Returns one run you started with [Start a run](/api-reference/deep-research/start-run): its status, the agents working on it, and, once it's `COMPLETED`, the report's id, title, summary, link, and full text.

```
GET /api/v2/c/{companySlug}/deep-research/{runId}
```

Read the run until `status` is `COMPLETED` or `FAILED`. Runs take minutes.

## Authorization

This endpoint works with any valid [API key](/api-reference/overview#authentication). You can only read runs started by the member who created the key. A run started by anyone else, or through the Windmill Dashboard, 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`

**runId** `string` *required*

The run's id, returned as `runId` by [Start a run](/api-reference/deep-research/start-run). Must be a UUID; anything else returns `400`.

## Query parameters

**fresh** `boolean`

Pass `true` on your first read right after starting a run, so the response includes the run you just created. Leave it off on later reads.

## Response

The response wraps the run in a `run` object.

**run.runId** `string` *required*

The run's id.

**run.status** `string` *required*

The run's status:

* **`RUNNING`** until the report is finished.
* **`COMPLETED`** when the report is ready. Terminal. `output` is set.
* **`FAILED`** when the run stopped with an error. Terminal. See `failureReason`. Start a new run to try again.

**run.prompt** `string` *required*

The prompt the run was started with.

**run.createdAt** `string` *required*

ISO 8601 time the run was started.

**run.updatedAt** `string` *required*

ISO 8601 time of the last activity on the run.

**run.completedAt** `string | null` *required*

ISO 8601 time the run reached `COMPLETED` or `FAILED`; `null` while it's running.

**run.failureReason** `string | null` *required*

Why the run failed, in plain language; `null` unless `status` is `FAILED`.

**run.agents** `object[]` *required*

The agents working on the run so far. Empty until research starts, then grows as Windy assigns work.

**agent properties**

**name** `string` *required*

The agent's name.

**role** `string` *required*

`RESEARCHER` gathers evidence for one workstream. `REPORT_WRITER` writes the report.

**done** `boolean` *required*

`true` once the agent has finished its part of the run.

**run.output** `object | null` *required*

The finished report. `null` until `status` is `COMPLETED`, and always `null` when `FAILED`.

**output properties**

**type** `string` *required*

Always `REPORT`.

**reportId** `string` *required*

The report's id.

**reportVersion** `number` *required*

The report's version. A run always produces version 1.

**title** `string` *required*

The report's title.

**summary** `string | null` *required*

A short summary of the report.

**url** `string` *required*

Where to read the report in the Windmill Dashboard.

**content** `string` *required*

The full report as Markdown, without citations. Open `url` for the version with its cited sources.

## Errors

| Status | When |
| - | - |
| `400 Validation error` | `runId` isn't a UUID. |
| `401 Unauthorized` | The API key is missing, malformed, expired, or revoked. |
| `404 Not Found` | No run with this id exists in your company, or the key's creator didn't start it. |

The error response body is always shaped like this:

```json theme={null}
{
  "error": {
    "code": "NOT_FOUND",
    "message": "The resource you were looking for could not be found",
    "requestId": "01a0d2f4-3b1e-7c8a-9f21-4e6b7a8c9d03"
  }
}
```

```bash First read after starting theme={null}
curl \
  'https://api.gowindmill.com/api/v2/c/acme/deep-research/01a0d2f4-3b1e-7c8a-9f21-4e6b7a8c9d02?fresh=true' \
  -H 'Authorization: Bearer wm_api_xxxxxxxxxxxxxxxxxxxx'
```

```bash Later reads theme={null}
curl \
  'https://api.gowindmill.com/api/v2/c/acme/deep-research/01a0d2f4-3b1e-7c8a-9f21-4e6b7a8c9d02' \
  -H 'Authorization: Bearer wm_api_xxxxxxxxxxxxxxxxxxxx'
```

```json 200 OK (running) theme={null}
{
  "run": {
    "runId": "01a0d2f4-3b1e-7c8a-9f21-4e6b7a8c9d02",
    "status": "RUNNING",
    "prompt": "How did the platform team's delivery pace change over the summer, and what drove it?",
    "createdAt": "2026-09-22T14:03:11.402Z",
    "updatedAt": "2026-09-22T14:04:40.118Z",
    "completedAt": null,
    "failureReason": null,
    "agents": [
      { "name": "Delivery pace researcher", "role": "RESEARCHER", "done": true },
      { "name": "Blockers researcher", "role": "RESEARCHER", "done": false }
    ],
    "output": null
  }
}
```

```json 200 OK (completed) theme={null}
{
  "run": {
    "runId": "01a0d2f4-3b1e-7c8a-9f21-4e6b7a8c9d02",
    "status": "COMPLETED",
    "prompt": "How did the platform team's delivery pace change over the summer, and what drove it?",
    "createdAt": "2026-09-22T14:03:11.402Z",
    "updatedAt": "2026-09-22T14:09:52.771Z",
    "completedAt": "2026-09-22T14:09:52.771Z",
    "failureReason": null,
    "agents": [
      { "name": "Delivery pace researcher", "role": "RESEARCHER", "done": true },
      { "name": "Blockers researcher", "role": "RESEARCHER", "done": true },
      { "name": "Report writer", "role": "REPORT_WRITER", "done": true }
    ],
    "output": {
      "type": "REPORT",
      "reportId": "cm3kb1q7e0004l8f0z2r4m8na",
      "reportVersion": 1,
      "title": "Platform team delivery pace, June through August 2026",
      "summary": "Throughput held steady through July, then slowed in August as two large migrations absorbed the team.",
      "url": "https://app.gowindmill.com/s/acme/reports/cm3kb1q7e0004l8f0z2r4m8na/report?v=1",
      "content": "# Platform team delivery pace, June through August 2026\n\nThroughput held steady through July, then slowed in August as two large migrations absorbed the team..."
    }
  }
}
```

```json 200 OK (failed) theme={null}
{
  "run": {
    "runId": "01a0d2f4-3b1e-7c8a-9f21-4e6b7a8c9d02",
    "status": "FAILED",
    "prompt": "How did the platform team's delivery pace change over the summer, and what drove it?",
    "createdAt": "2026-09-22T14:03:11.402Z",
    "updatedAt": "2026-09-22T14:03:12.090Z",
    "completedAt": "2026-09-22T14:03:12.090Z",
    "failureReason": "The run could not be started.",
    "agents": [],
    "output": null
  }
}
```


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