Start Deep Research run

Start a durable Deep Research investigation.

POST /api/v1/ee/projects/{projectUuid}/ai-deep-research

Error

A valid request URL is required to generate request examples

202

{
  "results": {
    "completedAt": "<string>",
    "startedAt": "<string>",
    "updatedAt": "<string>",
    "createdAt": "<string>",
    "cancellationRequestedAt": "<string>",
    "errorMessage": "<string>",
    "metrics": {
      "chartCount": 123,
      "findingsCount": 123,
      "warehouseQueryCount": 123,
      "toolErrorCount": 123,
      "toolCallCount": 123,
      "tokenUsageComplete": true,
      "totalTokens": 123,
      "reasoningTokens": 123,
      "cacheWriteTokens": 123,
      "cacheReadTokens": 123,
      "outputTokens": 123,
      "inputTokens": 123,
      "durationMs": 123
    },
    "executionContextSnapshot": {
      "effectivePermissions": {
        "autoApproveSql": true,
        "canUseSelfImprovementTools": true,
        "canUseContentTools": true,
        "canUseDataTools": true,
        "canRunSql": true,
        "canManageAgent": true
      },
      "repository": {
        "availableSkillNames": [
          "<string>"
        ],
        "repoFsSupportsCodeSearch": true,
        "repoFsRoot": "<string>",
        "repoDiscoveryEnabled": true,
        "previewDeploySetupEnabled": true,
        "codingAgentEnabled": true,
        "aiWritebackEnabled": true,
        "projectContextEnabled": true
      },
      "knowledgeDocuments": [
        {
          "alwaysIncludeInContext": true,
          "updatedAt": "<string>",
          "name": "<string>",
          "uuid": "<string>"
        }
      ],
      "tools": {
        "attachedMcpServers": [
          {
            "enabledToolNames": [
              "<string>"
            ],
            "name": "<string>",
            "uuid": "<string>"
          }
        ],
        "availableToolNames": [
          "<string>"
        ]
      },
      "model": {
        "reasoningEnabled": true,
        "modelName": "<string>",
        "provider": "<string>"
      },
      "agent": {
        "enableUserContext": true,
        "enableContentTools": true,
        "enableSelfImprovement": true,
        "enableDataAccess": true,
        "spaceAccess": [
          "<string>"
        ],
        "tags": [
          "<string>"
        ],
        "hasInstruction": true,
        "updatedAt": "<string>",
        "version": 123,
        "name": "<string>",
        "uuid": "<string>"
      },
      "capturedAt": "<string>",
      "schemaVersion": 1
    },
    "budget": {
      "maxHypotheses": 123,
      "maxWarehouseQueries": 123,
      "maxToolCalls": 123,
      "maxTokens": 123,
      "maxResultRows": 123
    },
    "isReportExpired": true,
    "reportExpiredAt": "<string>",
    "reportExpiresAt": "<string>",
    "resultChartData": {},
    "resultMarkdown": "<string>",
    "prompt": "<string>",
    "promptUuid": "<string>",
    "aiThreadUuid": "<string>",
    "agentUuid": "<string>",
    "projectUuid": "<string>",
    "aiDeepResearchRunUuid": "<string>"
  },
  "status": "ok"
}

Path Parameters

projectUuid · string<uuid> · required

Stringified UUIDv4. See RFC 4112

Pattern: [0-9A-Fa-f]{8}-[0-9A-Fa-f]{4}-4[0-9A-Fa-f]{3}-[89ABab][0-9A-Fa-f]{3}-[0-9A-Fa-f]{12}

Body

application/json

entryPoint · enum<string> · required

Product surface that accepted the run.

Available options: homepage, ask_ai

promptUuid · string · required

Thread message that captured this prompt.

threadUuid · string · required

Agent thread to attach the run to. Must be owned by the caller.

agentUuid · string · required

Agent whose complete runtime configuration will execute this run.

prompt · string · required

Response

202

application/json

Accepted

results · object · required

Show child attributes

status · enum<string> · required

Available options: ok