Lightdash v2 API

openapi: 3.2.0
info:
  title: Lightdash AiAgents V2 API
  version: 0.3156.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: /
tags:
- name: v2
paths:
  /api/v2/projects/{projectUuid}/pre-aggregates/stats:
    get:
      operationId: getPreAggregateStats
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiGetPreAggregateStatsResponse'
        default:
          description: Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorPayload'
      description: Retrieves aggregated pre-aggregate hit/miss statistics for a project
      summary: Get pre-aggregate stats
      tags:
      - v2
      security: []
      parameters:
      - in: path
        name: projectUuid
        required: true
        schema:
          type: string
      - in: query
        name: days
        required: false
        schema:
          format: double
          type: number
      - in: query
        name: page
        required: false
        schema:
          format: double
          type: number
      - in: query
        name: pageSize
        required: false
        schema:
          format: double
          type: number
      - in: query
        name: exploreName
        required: false
        schema:
          type: string
      - in: query
        name: queryType
        required: false
        schema:
          type: string
          enum:
          - chart
          - dashboard
          - explorer
  /api/v2/projects/{projectUuid}/pre-aggregates/dashboards/{dashboardUuidOrSlug}/audit:
    get:
      operationId: getDashboardPreAggregateAudit
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiGetDashboardPreAggregateAuditResponse'
        default:
          description: Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorPayload'
      description: 'Audits pre-aggregate hit/miss coverage for every tile on a dashboard

        without executing the queries. Returns a per-tile breakdown grouped

        by tab, suitable for CI coverage checks and pre-aggregate tuning.'
      summary: Get dashboard pre-aggregate audit
      tags:
      - v2
      security: []
      parameters:
      - in: path
        name: projectUuid
        required: true
        schema:
          type: string
      - in: path
        name: dashboardUuidOrSlug
        required: true
        schema:
          type: string
    post:
      operationId: runDashboardPreAggregateAudit
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiGetDashboardPreAggregateAuditResponse'
        default:
          description: Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorPayload'
      description: Audit pre-aggregate hit/miss coverage with runtime filter overrides
      summary: Run dashboard pre-aggregate audit
      tags:
      - v2
      security: []
      parameters:
      - in: path
        name: projectUuid
        required: true
        schema:
          type: string
      - in: path
        name: dashboardUuidOrSlug
        required: true
        schema:
          type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ApiRunDashboardPreAggregateAuditBody'
  /api/v2/projects/{projectUuid}/pre-aggregates/materializations:
    get:
      operationId: getPreAggregateMaterializations
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiGetPreAggregateMaterializationsResponse'
        default:
          description: Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorPayload'
      description: Retrieves pre-aggregate definitions with their latest materialization status
      summary: Get pre-aggregate materializations
      tags:
      - v2
      security: []
      parameters:
      - in: path
        name: projectUuid
        required: true
        schema:
          type: string
      - in: query
        name: page
        required: false
        schema:
          format: double
          type: number
      - in: query
        name: pageSize
        required: false
        schema:
          format: double
          type: number
  /api/v2/orgs/{orgUuid}/roles:
    post:
      operationId: CreateOrganizationRole
      responses:
        '201':
          description: Created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiDefaultRoleResponse'
        default:
          description: Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorPayload'
      description: Create a new role in organization
      summary: Create custom role
      tags:
      - v2
      security: []
      parameters:
      - in: path
        name: orgUuid
        required: true
        schema:
          type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateRole'
    get:
      operationId: GetOrganizationRoles
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                anyOf:
                - $ref: '#/components/schemas/ApiGetRolesResponse'
                - $ref: '#/components/schemas/ApiRoleWithScopesResponse'
        default:
          description: Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorPayload'
      description: Get roles for organization
      summary: Get organization roles
      tags:
      - v2
      security: []
      parameters:
      - in: path
        name: orgUuid
        required: true
        schema:
          type: string
      - in: query
        name: load
        required: false
        schema:
          type: string
      - in: query
        name: roleTypeFilter
        required: false
        schema:
          type: string
  /api/v2/orgs/{orgUuid}/roles/{roleUuid}:
    patch:
      operationId: UpdateOrganizationRole
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiDefaultRoleResponse'
        default:
          description: Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorPayload'
      description: Update role in organization
      summary: Update custom role
      tags:
      - v2
      security: []
      parameters:
      - in: path
        name: orgUuid
        required: true
        schema:
          type: string
      - in: path
        name: roleUuid
        required: true
        schema:
          type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateRole'
    delete:
      operationId: DeleteOrganizationRole
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiUnassignRoleFromUserResponse'
        default:
          description: Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorPayload'
      description: Delete role from organization
      summary: Delete custom role
      tags:
      - v2
      security: []
      parameters:
      - in: path
        name: orgUuid
        required: true
        schema:
          type: string
      - in: path
        name: roleUuid
        required: true
        schema:
          type: string
    get:
      operationId: GetCustomRoleByUuid
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiRoleWithScopesResponse'
        default:
          description: Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorPayload'
      description: Get custom role by uuid
      summary: Get custom role
      tags:
      - v2
      security: []
      parameters:
      - in: path
        name: orgUuid
        required: true
        schema:
          type: string
      - in: path
        name: roleUuid
        required: true
        schema:
          type: string
  /api/v2/orgs/{orgUuid}/roles/{roleUuid}/assignees:
    get:
      operationId: GetOrganizationRoleAssignees
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiRoleAssigneesResponse'
        default:
          description: Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorPayload'
      description: 'List the users, groups, and service accounts currently assigned to a role.

        Used by the delete-confirmation modal to explain why a role cannot

        be deleted while still in use.'
      summary: List role assignees
      tags:
      - v2
      security: []
      parameters:
      - in: path
        name: orgUuid
        required: true
        schema:
          type: string
      - in: path
        name: roleUuid
        required: true
        schema:
          type: string
  /api/v2/orgs/{orgUuid}/roles/{roleUuid}/scopes:
    post:
      operationId: AddScopesToRole
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiUnassignRoleFromUserResponse'
        default:
          description: Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorPayload'
      description: Add scopes to role
      summary: Add scopes to role
      tags:
      - v2
      deprecated: true
      security: []
      parameters:
      - in: path
        name: orgUuid
        required: true
        schema:
          type: string
      - in: path
        name: roleUuid
        required: true
        schema:
          type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AddScopesToRole'
  /api/v2/orgs/{orgUuid}/roles/{roleUuid}/scopes/{scopeName}:
    delete:
      operationId: RemoveScopeFromRole
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiRemoveScopeFromRoleResponse'
        default:
          description: Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorPayload'
      description: Remove scope from role
      summary: Remove scope from role
      tags:
      - v2
      deprecated: true
      security: []
      parameters:
      - in: path
        name: orgUuid
        required: true
        schema:
          type: string
      - in: path
        name: roleUuid
        required: true
        schema:
          type: string
      - in: path
        name: scopeName
        required: true
        schema:
          type: string
  /api/v2/projects/{projectId}/roles/assignments:
    get:
      operationId: GetProjectRoleAssignments
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiRoleAssignmentListResponse'
        default:
          description: Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorPayload'
      description: List project role assignments
      summary: List project role assignments
      tags:
      - v2
      security: []
      parameters:
      - in: path
        name: projectId
        required: true
        schema:
          type: string
  /api/v2/projects/{projectId}/roles/assignments/user/{userId}:
    post:
      operationId: UpsertProjectUserRoleAssignment
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiRoleAssignmentResponse'
        default:
          description: Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorPayload'
      description: Create or update project role assignment for user (upsert)
      summary: Assign project role to user
      tags:
      - v2
      security: []
      parameters:
      - in: path
        name: projectId
        required: true
        schema:
          type: string
      - in: path
        name: userId
        required: true
        schema:
          type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpsertUserRoleAssignmentRequest'
    delete:
      operationId: DeleteProjectUserRoleAssignment
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiUnassignRoleFromUserResponse'
        default:
          description: Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorPayload'
      description: Delete project role assignment for user
      summary: Remove project role from user
      tags:
      - v2
      security: []
      parameters:
      - in: path
        name: projectId
        required: true
        schema:
          type: string
      - in: path
        name: userId
        required: true
        schema:
          type: string
  /api/v2/projects/{projectId}/roles/assignments/group/{groupId}:
    post:
      operationId: UpsertProjectGroupRoleAssignment
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiRoleAssignmentResponse'
        default:
          description: Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorPayload'
      description: Create or update project role assignment for group (upsert)
      summary: Assign project role to group
      tags:
      - v2
      security: []
      parameters:
      - in: path
        name: projectId
        required: true
        schema:
          type: string
      - in: path
        name: groupId
        required: true
        schema:
          type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpsertUserRoleAssignmentRequest'
    patch:
      operationId: UpdateProjectGroupRoleAssignment
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiRoleAssignmentResponse'
        default:
          description: Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorPayload'
      description: Update project role assignment for group
      summary: Update project group role
      tags:
      - v2
      security: []
      parameters:
      - in: path
        name: projectId
        required: true
        schema:
          type: string
      - in: path
        name: groupId
        required: true
        schema:
          type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateRoleAssignmentRequest'
    delete:
      operationId: DeleteProjectGroupRoleAssignment
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiUnassignRoleFromUserResponse'
        default:
          description: Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorPayload'
      description: Delete project role assignment for group
      summary: Remove project role from group
      tags:
      - v2
      security: []
      parameters:
      - in: path
        name: projectId
        required: true
        schema:
          type: string
      - in: path
        name: groupId
        required: true
        schema:
          type: string
  /api/v2/orgs/{orgUuid}/roles/assignments:
    get:
      operationId: GetOrganizationRoleAssignments
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiRoleAssignmentListResponse'
        default:
          description: Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorPayload'
      description: List organization role assignments (system roles only)
      summary: List organization role assignments
      tags:
      - v2
      security: []
      parameters:
      - in: path
        name: orgUuid
        required: true
        schema:
          type: string
  /api/v2/orgs/{orgUuid}/roles/assignments/user/{userId}:
    post:
      operationId: UpsertOrganizationUserRoleAssignment
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiRoleAssignmentResponse'
        default:
          description: Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorPayload'
      description: Assign system role to user at organization level
      summary: Assign organization role to user
      tags:
      - v2
      security: []
      parameters:
      - in: path
        name: orgUuid
        required: true
        schema:
          type: string
      - in: path
        name: userId
        required: true
        schema:
          type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              properties:
                roleId:
                  type: string
              required:
              - roleId
              type: object
  /api/v2/orgs/{orgUuid}/roles/{roleId}/duplicate:
    post:
      operationId: DuplicateRole
      responses:
        '201':
          description: Role duplicated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiRoleWithScopesResponse'
        default:
          description: Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorPayload'
      description: Duplicate a role
      summary: Duplicate role
      tags:
      - v2
      security: []
      parameters:
      - in: path
        name: orgUuid
        required: true
        schema:
          type: string
      - in: path
        name: roleId
        required: true
        schema:
          type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateRole'
  /api/v2/projects/{projectUuid}/validate:
    get:
      operationId: ListValidationResults
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiPaginatedValidateResponse'
        default:
          description: Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorPayload'
      description: Get paginated validation results for a project with search, filter, and sort support.
      summary: List validation results
      tags:
      - v2
      security: []
      parameters:
      - description: the projectId for the validation
        in: path
        name: projectUuid
        required: true
        schema:
          type: string
      - description: page number (1-indexed)
        in: query
        name: page
        required: false
        schema:
          default: 1
          format: double
          type: number
      - description: number of results per page
        in: query
        name: pageSize
        required: false
        schema:
          default: 20
          format: double
          type: number
      - description: search string to filter by name or error message
        in: query
        name: searchQuery
        required: false
        schema:
          type: string
      - description: field to sort by
        in: query
        name: sortBy
        required: false
        schema:
          type: string
          enum:
          - name
          - createdAt
          - errorType
          - source
      - description: sort direction
        in: query
        name: sortDirection
        required: false
        schema:
          type: string
          enum:
          - asc
          - desc
      - description: comma-separated list of source types to filter by
        in: query
        name: sourceTypes
        required: false
        schema:
          type: string
      - description: comma-separated list of error types to filter by
        in: query
        name: errorTypes
        required: false
        schema:
          type: string
      - description: whether to include chart configuration warnings
        in: query
        name: includeChartConfigWarnings
        required: false
        schema:
          type: boolean
      - description: boolean for analytics tracking
        in: query
        name: fromSettings
        required: false
        schema:
          type: boolean
  /api/v2/projects/{projectUuid}/validate/{validationIdOrUuid}:
    get:
      operationId: GetValidationResult
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiSingleValidationResponse'
        default:
          description: Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorPayload'
      description: Get a single validation result.
      summary: Get validation result
      tags:
      - v2
      security: []
      parameters:
      - description: the projectId for the validation
        in: path
        name: projectUuid
        required: true
        schema:
          type: string
      - description: 'the validation UUID, or a legacy integer id

          for rows created before the UUID migration (PROD-7386).'
        in: path
        name: validationIdOrUuid
        required: true
        schema: {}
  /api/v2/saved/{chartUuid}/schedulers:
    get:
      operationId: getSavedChartSchedulers
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiSavedChartPaginatedSchedulersResponse'
        default:
          description: Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorPayload'
      description: Get all schedulers for a saved chart
      summary: List chart schedulers
      tags:
      - v2
      security: []
      parameters:
      - description: The uuid of the chart
        in: path
        name: chartUuid
        required: true
        schema:
          type: string
      - description: number of items per page
        in: query
        name: pageSize
        required: false
        schema:
          format: double
          type: number
      - description: page number
        in: query
        name: page
        required: false
        schema:
          format: double
          type: number
      - description: filter schedulers by name
        in: query
        name: searchQuery
        required: false
        schema:
          type: string
      - description: comma-separated list of scheduler formats to include
        in: query
        name: formats
        required: false
        schema:
          type: string
      - description: include the most recent run for each scheduler
        in: query
        name: includeLatestRun
        required: false
        schema:
          type: boolean
  /api/v2/saved/{chartUuid}/schedulers/{schedulerUuid}/runs:
    get:
      operationId: getSavedChartSchedulerRuns
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiSchedulerRunsResponse'
        default:
          description: Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorPayload'
      description: Get the run history of a single scheduler on a chart
      summary: List chart scheduler runs
      tags:
      - v2
      security: []
      parameters:
      - description: The uuid of the chart
        in: path
        name: chartUuid
        required: true
        schema:
          type: string
      - description: The uuid of the scheduler
        in: path
        name: schedulerUuid
        required: true
        schema:
          type: string
      - description: number of items per page
        in: query
        name: pageSize
        required: false
        schema:
          format: double
          type: number
      - description: page number
        in: query
        name: page
        required: false
        schema:
          format: double
          type: number
      - description: filter runs by scheduler name
        in: query
        name: searchQuery
        required: false
        schema:
          type: string
      - description: column to sort by (scheduledTime, createdAt)
        in: query
        name: sortBy
        required: false
        schema:
          type: string
          enum:
          - scheduledTime
          - createdAt
      - description: sort direction (asc or desc)
        in: query
        name: sortDirection
        required: false
        schema:
          type: string
          enum:
          - asc
          - desc
      - description: comma-separated list of run statuses to include
        in: query
        name: statuses
        required: false
        schema:
          type: string
      - description: comma-separated list of destination types to include
        in: query
        name: destinations
        required: false
        schema:
          type: string
  /api/v2/projects/{projectUuid}/query/{queryUuid}:
    get:
      operationId: getAsyncQueryResults
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiGetAsyncQueryResultsResponse'
        default:
          description: Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorPayload'
      description: Retrieves paginated results from a previously executed async query using its UUID
      summary: Get results
      tags:
      - v2
      security: []
      parameters:
      - in: path
        name: projectUuid
        required: true
        schema:
          type: string
      - description: The UUID of the async query to retrieve results for
        in: path
        name: queryUuid
        required: true
        schema:
          type: string
      - description: Page number for pagination (starts at 1)
        in: query
        name: page
        required: false
        schema:
          format: double
          type: number
      - description: 'Number of results per page (default: 500, max: 5000)'
        in: query
        name: pageSize
        required: false
        schema:
          format: double
          type: number
  /api/v2/projects/{projectUuid}/query/{queryUuid}/cancel:
    post:
      operationId: cancelAsyncQuery
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiSuccessEmpty'
        default:
          description: Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorPayload'
      description: Cancels a running async query and discards any partial results
      summary: Cancel query
      tags:
      - v2
      security: []
      parameters:
      - in: path
        name: projectUuid
        required: true
        schema:
          type: string
      - description: The UUID of the async query to cancel
        in: path
        name: queryUuid
        required: true
        schema:
          type: string
  /api/v2/projects/{projectUuid}/query/{queryUuid}/calculate-total:
    post:
      operationId: executeAsyncCalculateTotal
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiSuccess_ApiExecuteAsyncMetricQueryResults_'
        default:
          description: Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorPayload'
      description: Calculates totals for a previously-executed query, referenced by its queryUuid. Re-runs the source query's MetricQuery against the warehouse so totals are correct for every metric type (count distinct, average, ratio, etc.) — unlike client-side cell summation, which only works for sum/count. The requested `kind` selects which totals to compute.
      summary: Calculate totals
      tags:
      - v2
      security: []
      parameters:
      - in: path
        name: projectUuid
        required: true
        schema:
          type: string
      - description: The UUID of the previously-executed query to compute totals from
        in: path
        name: queryUuid
        required: true
        schema:
          type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ExecuteAsyncCalculateTotalRequestParams'
  /api/v2/projects/{projectUuid}/query/metric-query:
    post:
      operationId: executeAsyncMetricQuery
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiSuccess_ApiExecuteAsyncMetricQueryResults_'
        default:
          description: Error
          content:
            application/json:
              schema:
       

# --- truncated at 32 KB (280 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/lightdash/refs/heads/main/openapi/lightdash-v2-api-openapi.yml