# createDeepResearchReport

Mutation

Start a Deep Research report in the current workspace; it spends credits.

Available to agents as MCP tool `createDeepResearchReport` — see [Write tools](/api/v2/docs/mcp/write-tools#create-deep-research-report).

## Arguments

| Name | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `input` | [`DeepResearchReportInput!`](/api/v2/docs/types/deep-research-report-input) | Yes | — | Mutation input. |

## Returns

| Name | Type | Description |
| --- | --- | --- |
| `deepResearchReport` | [`DeepResearchReport`](/api/v2/docs/types/deep-research-report) | The new report, still running. Null when the input was refused. |
| `userErrors` | [`[UserError!]!`](/api/v2/docs/types/user-error) | Why the report was not started: invalid input (pointing at the field) or not enough credits. Empty on success. |

## Examples

### Start a Deep Research report

Start a Share of Voice report on two tracked competitors. It spends the workspace's credits, so quote it first; poll `deepResearchReport(id:)` until `running` is false.

```graphql
mutation CreateDeepResearchReportDefault($input: DeepResearchReportInput!) {
  createDeepResearchReport(input: $input) {
    deepResearchReport {
      id
      status
      running
    }
    userErrors {
      field
      message
    }
  }
}
```

Variables:

```json
{
  "input": {
    "inputType": "BRAND",
    "templateSlug": "share-of-voice",
    "brandIds": [
      "28add94e-9994-54b2-9aaa-528e6606efe9",
      "97eb8f2a-7cf3-596f-b283-08dde96550e0"
    ]
  }
}
```

Response — HTTP 200:

```json
{
  "data": {
    "createDeepResearchReport": {
      "deepResearchReport": {
        "id": "475b666e-f1a3-5019-a216-f599aed6cce0",
        "status": "PENDING",
        "running": true
      },
      "userErrors": []
    }
  }
}
```