Qlik Sense data task runtime API

openapi: 3.2.0
info:
  title: di-projects data task runtime API
  version: ''
servers:
- url: https://{tenant}.{region}.qlikcloud.com
  variables:
    region:
      default: us
      description: The region the tenant is hosted in
    tenant:
      default: your-tenant
      description: Name of the tenant that will be called
tags:
- name: data task runtime
paths:
  /api/v1/di-projects/{projectId}/di-tasks/{dataTaskId}/runtime/actions/start:
    post:
      tags:
      - data task runtime
      summary: Start a project task
      responses:
        '204':
          description: NO CONTENT
        '400':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Errors'
          description: Bad Request
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Errors'
          description: Not Found
      parameters:
      - in: path
        name: dataTaskId
        schema:
          type: string
        examples:
          example:
            value: task-cYSY
        required: true
        description: Identifier of the data task.
      - in: path
        name: projectId
        schema:
          type: string
        examples:
          example:
            value: 65424a71c11367914c1e659b
        required: true
        description: Identifier of the data project.
      description: Start a data task on a data integration project.
      operationId: start_data_task
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/StartTaskReq'
        required: false
      x-qlik-visibility: public
      x-qlik-stability: stable
      x-qlik-deprecated: false
      x-qlik-tier:
        tier: '2'
        limit: 100
  /api/v1/di-projects/{projectId}/di-tasks/{dataTaskId}/runtime/actions/stop:
    post:
      tags:
      - data task runtime
      summary: Stop a project task
      responses:
        '204':
          description: NO CONTENT
        '400':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Errors'
          description: Bad Request
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Errors'
          description: Not Found
      parameters:
      - in: path
        name: dataTaskId
        schema:
          type: string
        examples:
          example:
            value: task-cYSY
        required: true
        description: Identifier of the data task.
      - in: path
        name: projectId
        schema:
          type: string
        examples:
          example:
            value: 65424a71c11367914c1e659b
        required: true
        description: Identifier of the data project.
      description: Stop a data task on a data integration project.
      operationId: stop_data_task
      x-qlik-visibility: public
      x-qlik-stability: stable
      x-qlik-deprecated: false
      x-qlik-tier:
        tier: '2'
        limit: 100
  /api/v1/di-projects/{projectId}/di-tasks/{dataTaskId}/runtime/state:
    get:
      tags:
      - data task runtime
      summary: Get project task runtime state
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DataTaskRuntimeState'
          description: OK
        '400':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Errors'
          description: Bad Request
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Errors'
          description: Not Found
      parameters:
      - in: path
        name: dataTaskId
        schema:
          type: string
        examples:
          example:
            value: task-cYSY
        required: true
        description: Identifier of the data task.
      - in: path
        name: projectId
        schema:
          type: string
        examples:
          example:
            value: 65424a71c11367914c1e659b
        required: true
        description: Identifier of the data project.
      description: Get the current runtime state of a data task
      operationId: get_data_task_runtime_state
      x-qlik-visibility: public
      x-qlik-stability: stable
      x-qlik-deprecated: false
      x-qlik-tier:
        tier: special
        limit: 120
  /api/v1/di-projects/{projectId}/di-tasks/{dataTaskId}/runtime/state/datasets:
    get:
      tags:
      - data task runtime
      summary: List runtime dataset states
      responses:
        '200':
          content:
            application/json:
              schema:
                type: object
                properties:
                  datasets:
                    type: array
                    items:
                      $ref: '#/components/schemas/DataTaskDatasetState'
          description: Returns all datasets for the specified data task
        '400':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Errors'
          description: Bad Request
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Errors'
          description: Not Found
      parameters:
      - in: path
        name: dataTaskId
        schema:
          type: string
        required: true
        description: Identifier of the data task.
      - in: path
        name: projectId
        schema:
          type: string
        required: true
        description: Identifier of the data project.
      description: Returns dataset-level runtime state for a data task
      operationId: list_data_task_datasets
      x-qlik-visibility: public
      x-qlik-stability: stable
      x-qlik-deprecated: false
      x-qlik-tier:
        tier: special
        limit: 120
components:
  schemas:
    ErrorSource:
      type: object
      properties:
        pointer:
          type: string
          description: JSON Pointer (RFC 6901) to the field in the request body that caused the error.
        parameter:
          type: string
          description: Name of the query parameter or path parameter that caused the error.
      description: Identifies the location of the error in the request.
    Error:
      type: object
      properties:
        code:
          type: string
          description: Machine-readable error code for programmatic handling.
        title:
          type: string
          description: Brief human-readable summary of the error.
        detail:
          type: string
          description: Detailed explanation of the error and suggested remediation steps.
        source:
          $ref: '#/components/schemas/ErrorSource'
        status:
          type: integer
          format: int32
          description: HTTP status code associated with the error.
      description: Represents a single error condition with details about what went wrong.
    DataTaskDatasetState:
      type: object
      properties:
        name:
          type: string
          description: Name of the dataset
        fullLoad:
          type: object
          properties:
            state:
              enum:
              - QUEUED
              - LOADING
              - COMPLETED
              - ERROR
              type: string
            endTime:
              type: string
              format: date-time
            message:
              type: string
            duration:
              type: string
              description: Duration in HH:MM:SS format (hours:minutes:seconds)
            fileStats:
              $ref: '#/components/schemas/FileStatistics'
            startTime:
              type: string
              format: date-time
            cachedChangesCount:
              type: number
              description: Number of changes captured and cached during full load (CDC landing/replication tasks only)
            failedRecordsCount:
              type: number
              description: Number of records that failed to load (currently only for knowledge marts)
            totalProcessedCount:
              type: number
              description: Number of records (or docs in knowledge marts) were loaded.
        cdcStatus:
          type: object
          properties:
            state:
              enum:
              - QUEUED
              - PROCESSING
              - ACCUMULATING_CHANGES
              - COMPLETED
              - ERROR
              type: string
            message:
              type: string
            ddlCount:
              type: number
              description: Number of DDL statements executed during the last run
            deleteCount:
              type: number
              description: delete portion of totalProcessedCount. Only available for some task types
            insertCount:
              type: number
              description: Insert portion of totalProcessedCount. Only available for some task types
            updateCount:
              type: number
              description: update portion of totalProcessedCount. Only available for some task types
            lastProcessed:
              type: string
              format: date-time
            totalProcessedCount:
              type: number
              description: Total number of changes/DMLs applied to the dataset
            incomingChangesCount:
              type: number
              description: Number of incoming changes for the dataset. Only relevant for 'Iceberg Storage' and 'Streaming Transform' tasks.
            unoptimizedRecordsCount:
              type: number
              description: Number of records that are queryable via the view, but not yet merged into optimized Iceberg partitions. Only relevant for 'Iceberg Storage' and 'Streaming Transform' tasks.
          description: Change Data Capture state for the dataset, tracking incremental changes applied and any errors.
        datasetId:
          type: string
          description: Id of the dataset
        streaming:
          type: object
          properties:
            state:
              enum:
              - QUEUED
              - RUNNING
              - ERROR
              type: string
            message:
              type: string
            lastProcessed:
              type: string
              format: date-time
              description: Timestamp of the latest source record inserted into the target dataset.
            parseIssueCount:
              type: number
              description: Number of records that had parsing issues
            recordsWrittenCount:
              type: number
              description: Total number of records written to the dataset
            totalProcessedCount:
              type: number
              description: Total number of processed changes for the dataset
            recordsFilteredCount:
              type: number
              description: Total number of records filtered out and not written to the dataset
            unoptimizedRecordsCount:
              type: number
              description: Queryable records pending merge into optimized Iceberg partitions.
          description: Real-time streaming state for the dataset, tracking record processing and transformation statistics.
        sourceName:
          type: string
          description: Original name of the dataset, relevant only for data movement tasks
        dataReadiness:
          enum:
          - READY
          - NOT_READY
          - ERROR
          type: string
          description: Is the data ready for use?
        lastBatchOfChanges:
          type: object
          properties:
            state:
              enum:
              - QUEUED
              - PROCESSING
              - COMPLETED
              - ERROR
              type: string
            endTime:
              type: string
              format: date-time
            message:
              type: string
            duration:
              type: string
              description: Duration in HH:MM:SS format (hours:minutes:seconds)
            fileStats:
              $ref: '#/components/schemas/FileStatistics'
            startTime:
              type: string
              format: date-time
            operationStats:
              $ref: '#/components/schemas/OperationStatistics'
            totalProcessedCount:
              type: number
            throughputInRecordsPerSecond:
              type: number
              description: Throughput in records per second
      description: Represents the execution state of a single dataset within a task run, including full load, CDC, and streaming progress.
    StartTaskReq:
      type: object
      properties:
        option:
          enum:
          - PROCESS_CHANGES_FROM_TIMESTAMP
          - PROCESS_CHANGES_FROM_POSITION
          - RECOVER_USING_LOCALLY_STORED_CHECKPOINT
          type: string
          description: Task run option for the task (optional, applies to Replication tasks only).
        processChangesFrom:
          type: string
          description: The value indicating where to resume the process, either a timestamp or an offset depending on the run option (optional, applies to Replication tasks only).
    Errors:
      type: object
      properties:
        errors:
          type: array
          items:
            $ref: '#/components/schemas/Error'
          description: Array of error objects describing what went wrong.
        traceId:
          type: string
          description: Unique identifier for this error response, useful for tracking and support inquiries.
      description: Standard error response wrapper containing one or more error details and a trace ID for diagnostics.
    OperationStatistics:
      type: object
      properties:
        deleteCount:
          type: number
          description: Number of delete operations.
        failedCount:
          type: number
          description: Number of failed operations.
        insertCount:
          type: number
          description: Number of insert operations.
        updateCount:
          type: number
          description: Number of update operations.
      description: Breakdown of operations for record-oriented tasks.
    DataTaskRuntimeState:
      type: object
      properties:
        name:
          type: string
          description: Name of the data task
        type:
          $ref: '#/components/schemas/DataTaskType'
        lastRun:
          $ref: '#/components/schemas/DataTaskInstanceState'
        runReadiness:
          type: object
          properties:
            state:
              enum:
              - READY_TO_RUN
              - ALREADY_RUNNING
              - NOT_RUNNABLE
              type: string
            message:
              type: string
      description: Represents the current or historical execution state of a data task, including progress information, error details, and dataset-level statistics.
    DataTaskType:
      enum:
      - LANDING
      - STORAGE
      - QVD_STORAGE
      - TRANSFORM
      - DATAMART
      - REGISTERED_DATA
      - REPLICATION
      - DISTRIBUTION
      - LAKE_LANDING
      - KNOWLEDGE_MART
      - FILE_BASED_KNOWLEDGE_MART
      - LAKEHOUSE_STORAGE
      - LAKEHOUSE_MIRROR
      - STREAMING_LAKE_LANDING
      - STREAMING_TRANSFORM
      - REPLICATE_LANDING
      type: string
      x-enum-varnames:
      - LANDING
      - STORAGE
      - QVD_STORAGE
      - TRANSFORM
      - DATAMART
      - REGISTERED_DATA
      - REPLICATION
      - LAKE_LANDING
      - KNOWLEDGE_MART
      - FILE_BASED_KNOWLEDGE_MART
      - LAKEHOUSE_STORAGE
      - LAKEHOUSE_MIRROR
      - STREAMING_LAKE_LANDING
      - STREAMING_TRANSFORM
      - REPLICATE_LANDING
    FileStatistics:
      type: object
      properties:
        volume:
          type: string
          description: Volume of data processed (e.g. '10.91 MiB').
        processedCount:
          type: number
          description: Number of files processed.
      description: Statistics for file-based tasks.
    DataTaskInstanceState:
      type: object
      properties:
        state:
          enum:
          - STARTING
          - RUNNING
          - COMPLETED
          - FAILED
          - CANCELED
          - STOPPING
          type: string
        errors:
          type: array
          items:
            $ref: '#/components/schemas/Error'
          description: List of errors encountered during the last run
        endTime:
          type: string
          format: date-time
          description: Timestamp indicating when the task instance ended
        general:
          type: object
          properties:
            gatewayId:
              type: string
              description: For tasks that run on a gateway, this is the id of the gateway
            gatewayName:
              type: string
              description: For tasks that run on a gateway, this is the name of the gateway
            datasetCount:
              type: number
              description: Total number of datasets produced by the task, including ones in error
            gatewayTaskName:
              type: string
              description: For tasks that run on a gateway, this is the internal name of the task on the gateway
            dataTaskUpdatedTo:
              type: string
              format: date-time
              description: The latest point in time the data reflects, based on updates from the source system.
            lakehouseClusterId:
              type: string
              description: For lakehouse storage tasks, this is the id of the cluster where the task runs
            liveViewsUpdatedTo:
              type: string
              format: date-time
              description: The latest point in time the live views reflect, based on updates from the source system.
            datasetsInErrorCount:
              type: number
              description: Count of datasets that encountered errors
            lakehouseClusterName:
              type: string
              description: For lakehouse storage tasks, this is the name of the cluster where the task runs
          description: Overall task execution statistics including dataset counts, data freshness timestamps, and infrastructure details.
        message:
          type: string
        traceId:
          type: string
          description: Trace identifier for the last run, useful for diagnostics and support
        duration:
          type: string
          description: Duration in HH:MM:SS format (hours:minutes:seconds)
        fullLoad:
          type: object
          properties:
            errorCount:
              type: number
              description: Number of datasets that have failed full load in this task run
            queuedCount:
              type: number
              description: Number of datasets that are queued for full load in this task run
            loadingCount:
              type: number
              description: Number of datasets that are currently being loaded in this task run
            completedCount:
              type: number
              description: Number of datasets that have completed full load in this task run
          description: Statistics for the full load phase of the task run, tracking dataset processing progress.
        cdcStatus:
          type: object
          properties:
            latency:
              type: string
              example: 01:30:45
              description: Duration in HH:MM:SS format (hours:minutes:seconds)
            totalProcessedCount:
              type: number
            applyingChangesCount:
              type: number
            incomingChangesCount:
              type: number
              description: Number of incoming changes. Only relevant for 'Iceberg Storage' and 'Streaming Transform' tasks.
            accumulatingChangesCount:
              type: number
            throughputInKilobytesPerSecond:
              type: number
              description: Throughput in kilobytes per second
          description: Change Data Capture status information for tasks performing incremental updates, including latency and processing counts.
        startTime:
          type: string
          format: date-time
          description: Timestamp indicating when the task instance started
        streaming:
          type: object
          properties:
            latency:
              type: string
              description: Duration in HH:MM:SS format (hours:minutes:seconds)
            errorCount:
              type: number
              description: Number of streaming datasets that have encountered errors
            queuedCount:
              type: number
              description: Number of streaming datasets that are queued
            runningCount:
              type: number
              description: Number of streaming datasets that are currently running
            totalProcessedCount:
              type: number
              description: Total number of records processed
          description: Real-time streaming statistics for tasks that continuously process data streams.
        lastBatchOfChanges:
          type: object
          properties:
            relatesToRecordsTo:
              type: string
              format: date-time
              description: This batch ends with operational source changes from this time.
            totalProcessedCount:
              type: number
            relatesToRecordsFrom:
              type: string
              format: date-time
              description: This batch starts with operational source changes from this time.
            throughputInRecordsPerSecond:
              type: number
              description: Throughput in records per second
          description: Statistics for the most recent batch of changes processed during the task run, including timing and throughput metrics.
      description: Represents the execution state of a task instance, including progress metrics, errors, and operation-specific statistics.