> ## Documentation Index > Fetch the complete documentation index at: https://lightdash-mintlify-41a20335.mintlify.site/llms.txt > Use this file to discover all available pages before exploring further. # Start Deep Research run > Start a durable Deep Research investigation. ## OpenAPI ````yaml https://raw.githubusercontent.com/lightdash/lightdash/refs/heads/main/packages/backend/src/generated/swagger.json post /api/v1/ee/projects/{projectUuid}/ai-deep-research openapi: 3.0.0 info: title: Lightdash API version: 1.108.1 description: > Open API documentation for all public Lightdash API endpoints. # Authentication Before you get started, you might need to create a Personal Access Token to authenticate via the API. You can create a token by following this guide: https://docs.lightdash.com/references/personal_tokens license: name: MIT contact: name: Lightdash Support email: support@lightdash.com url: https://docs.lightdash.com/help-and-contact/contact/contact_info/ servers: - url: / security: [] tags: - name: My Account description: These routes allow users to manage their own user account. - name: Organizations description: >- Each user is a member of a single organization. These routes allow users to manage their organization. Most actions are only available to admin users. - name: Projects description: >- Projects belong to a single organization. These routes allow users to manage their projects, browse content, and execute queries. Users inside an organization might have access to a project from an organization-level role or they might be granted access to a project directly. - name: Spaces description: >- Spaces allow you to organize charts and dashboards within a project. They also allow granular access to content by allowing you to create private spaces, which are only accessible to the creator and admins. - name: Roles & Permissions description: >- These routes allow users to manage roles and permissions for their organization. externalDocs: url: https://docs.lightdash.com/references/roles - name: Query description: >- These routes allow users to execute and manage queries against their data warehouse. This includes metric queries, SQL queries, and retrieving query results. paths: /api/v1/ee/projects/{projectUuid}/ai-deep-research: post: summary: Start Deep Research run description: Start a durable Deep Research investigation. operationId: createAiDeepResearchRun parameters: - in: path name: projectUuid required: true schema: $ref: '#/components/schemas/UUID' requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/AiDeepResearchRequestBody' responses: '202': description: Accepted content: application/json: schema: $ref: '#/components/schemas/ApiAiDeepResearchRunResponse' '409': description: Deep Research run already active content: application/json: schema: $ref: '#/components/schemas/ApiErrorPayload' default: description: Error content: application/json: schema: $ref: '#/components/schemas/ApiErrorPayload' security: [] components: schemas: UUID: type: string format: uuid description: |- Stringified UUIDv4. See [RFC 4112](https://tools.ietf.org/html/rfc4122) 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} AiDeepResearchRequestBody: properties: entryPoint: $ref: '#/components/schemas/AiDeepResearchEntryPoint' description: Product surface that accepted the run. promptUuid: type: string description: Thread message that captured this prompt. threadUuid: type: string description: Agent thread to attach the run to. Must be owned by the caller. agentUuid: type: string description: Agent whose complete runtime configuration will execute this run. prompt: type: string required: - entryPoint - promptUuid - threadUuid - agentUuid - prompt type: object ApiAiDeepResearchRunResponse: $ref: '#/components/schemas/ApiSuccess_AiDeepResearchRun_' ApiErrorPayload: properties: error: properties: data: $ref: '#/components/schemas/AnyType' description: Optional data containing details of the error message: type: string description: A friendly message summarising the error name: type: string description: Unique name for the type of error statusCode: type: number format: integer description: HTTP status code required: - name - statusCode type: object status: type: string enum: - error nullable: false required: - error - status type: object description: |- The Error object is returned from the api any time there is an error. The message contains AiDeepResearchEntryPoint: type: string enum: - homepage - ask_ai ApiSuccess_AiDeepResearchRun_: properties: results: $ref: '#/components/schemas/AiDeepResearchRun' status: type: string enum: - ok nullable: false required: - results - status type: object AnyType: description: |- This AnyType is an alias for any The goal is to make it easier to identify any type in the codebase without having to eslint-disable all the time These are only used on legacy `any` types, don't use it for new types. This is added on a separate file to avoid circular dependencies. AiDeepResearchRun: properties: completedAt: type: string nullable: true startedAt: type: string nullable: true updatedAt: type: string createdAt: type: string cancellationRequestedAt: type: string nullable: true errorMessage: type: string nullable: true metrics: $ref: '#/components/schemas/AiDeepResearchRunMetrics' executionContextSnapshot: allOf: - $ref: '#/components/schemas/AiDeepResearchExecutionContextSnapshot' nullable: true budget: $ref: '#/components/schemas/AiDeepResearchBudget' isReportExpired: type: boolean reportExpiredAt: type: string nullable: true reportExpiresAt: type: string nullable: true resultMarkdown: type: string nullable: true description: The report narrative with compact references. status: $ref: '#/components/schemas/AiDeepResearchRunStatus' prompt: type: string entryPoint: $ref: '#/components/schemas/AiDeepResearchEntryPoint' promptUuid: type: string aiThreadUuid: type: string agentUuid: type: string projectUuid: type: string aiDeepResearchRunUuid: type: string required: - completedAt - startedAt - updatedAt - createdAt - cancellationRequestedAt - errorMessage - metrics - executionContextSnapshot - budget - isReportExpired - reportExpiredAt - reportExpiresAt - resultMarkdown - status - prompt - entryPoint - promptUuid - aiThreadUuid - agentUuid - projectUuid - aiDeepResearchRunUuid type: object AiDeepResearchRunMetrics: properties: chartCount: type: number format: double nullable: true findingsCount: type: number format: double nullable: true warehouseQueryCount: type: number format: double nullable: true toolErrorCount: type: number format: double nullable: true toolCallCount: type: number format: double nullable: true tokenUsageComplete: type: boolean nullable: true totalTokens: type: number format: double nullable: true reasoningTokens: type: number format: double nullable: true cacheWriteTokens: type: number format: double nullable: true cacheReadTokens: type: number format: double nullable: true outputTokens: type: number format: double nullable: true inputTokens: type: number format: double nullable: true durationMs: type: number format: double nullable: true required: - chartCount - findingsCount - warehouseQueryCount - toolErrorCount - toolCallCount - tokenUsageComplete - totalTokens - reasoningTokens - cacheWriteTokens - cacheReadTokens - outputTokens - inputTokens - durationMs type: object AiDeepResearchExecutionContextSnapshot: properties: effectivePermissions: properties: autoApproveSql: type: boolean canUseSelfImprovementTools: type: boolean canUseContentTools: type: boolean canUseDataTools: type: boolean canRunSql: type: boolean canManageAgent: type: boolean required: - autoApproveSql - canUseSelfImprovementTools - canUseContentTools - canUseDataTools - canRunSql - canManageAgent type: object repository: properties: availableSkillNames: items: type: string type: array repoFsSupportsCodeSearch: type: boolean nullable: true repoFsRoot: type: string nullable: true repoDiscoveryEnabled: type: boolean nullable: true previewDeploySetupEnabled: type: boolean nullable: true codingAgentEnabled: type: boolean nullable: true aiWritebackEnabled: type: boolean nullable: true projectContextEnabled: type: boolean nullable: true required: - availableSkillNames - repoFsSupportsCodeSearch - repoFsRoot - repoDiscoveryEnabled - previewDeploySetupEnabled - codingAgentEnabled - aiWritebackEnabled - projectContextEnabled type: object knowledgeDocuments: items: properties: alwaysIncludeInContext: type: boolean updatedAt: type: string name: type: string uuid: type: string required: - alwaysIncludeInContext - updatedAt - name - uuid type: object type: array tools: properties: attachedMcpServers: items: properties: enabledToolNames: items: type: string type: array name: type: string uuid: type: string required: - enabledToolNames - name - uuid type: object type: array availableToolNames: items: type: string type: array required: - attachedMcpServers - availableToolNames type: object model: properties: keyManagement: type: string enum: - lightdash-managed - self-managed - null nullable: true reasoningEnabled: type: boolean nullable: true modelName: type: string nullable: true provider: type: string nullable: true required: - keyManagement - reasoningEnabled - modelName - provider type: object agent: properties: enableUserContext: type: boolean enableContentTools: type: boolean enableSelfImprovement: type: boolean enableDataAccess: type: boolean spaceAccess: items: type: string type: array tags: items: type: string type: array nullable: true hasInstruction: type: boolean updatedAt: type: string version: type: number format: double name: type: string uuid: type: string required: - enableUserContext - enableContentTools - enableSelfImprovement - enableDataAccess - spaceAccess - tags - hasInstruction - updatedAt - version - name - uuid type: object capturedAt: type: string resolutionStage: type: string enum: - preflight - execution schemaVersion: type: number enum: - 1 nullable: false required: - effectivePermissions - repository - knowledgeDocuments - tools - model - agent - capturedAt - resolutionStage - schemaVersion type: object AiDeepResearchBudget: allOf: - $ref: '#/components/schemas/AiDeepResearchLimits' - properties: maxResultRows: type: number format: double required: - maxResultRows type: object AiDeepResearchRunStatus: type: string enum: - queued - running - failed - completed - cancelled - partially_completed AiDeepResearchLimits: properties: deadlineMs: type: number format: double description: Wall-clock ceiling for the research loop. maxWarehouseQueries: type: number format: double maxToolCalls: type: number format: double maxSteps: type: number format: double description: Model steps the coordinator may take before it must finish. maxTokens: type: number format: double required: - deadlineMs - maxWarehouseQueries - maxToolCalls - maxSteps - maxTokens type: object ````