Qlik Sense task run history API

openapi: 3.2.0
info:
  title: di-projects task run history 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: task run history
paths:
  /api/v1/di-projects/{projectId}/di-tasks/{dataTaskId}/runtime/runs/{runId}/state:
    get:
      tags:
      - task run history
      summary: Get run state
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DataTaskRuntimeState'
          description: Run execution state retrieved successfully.
        '400':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Errors'
          description: Invalid request or missing parameters.
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Errors'
          description: Task run 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.
      - in: path
        name: runId
        schema:
          type: string
        examples:
          example:
            value: run-abc123
        required: true
        description: Identifier of the run instance.
      description: Returns the state of a specific historical run instance for a data task, including execution progress and any errors encountered.
      operationId: get_task_run_state
      x-qlik-visibility: public
      x-qlik-stability: stable
      x-qlik-deprecated: false
      x-qlik-tier:
        tier: '1'
        limit: 1000
  /api/v1/di-projects/{projectId}/di-tasks/{dataTaskId}/runtime/runs/{runId}/state/datasets:
    get:
      tags:
      - task run history
      summary: List run dataset states
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ListDataTaskDatasetsRsp'
          description: Dataset-level state for the specified run instance retrieved successfully.
        '400':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Errors'
          description: Invalid request or missing parameters.
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Errors'
          description: Task run not found.
        '410':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Errors'
          description: Gone — the dataset state for this run has been purged due to retention policy.
        '413':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Errors'
          description: Payload Too Large — the dataset state for this run exceeds the per-response size limit. This is a soft guard against pathologically large tasks; if you hit this consistently, contact support.
      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.
      - in: path
        name: runId
        schema:
          type: string
        examples:
          example:
            value: run-abc123
        required: true
        description: Identifier of the run instance.
      description: Returns dataset-level state for a specific historical run instance of a data task. All datasets for the run are returned in a single response; this endpoint does not paginate.
      operationId: list_task_run_datasets
      x-qlik-visibility: public
      x-qlik-stability: stable
      x-qlik-deprecated: false
      x-qlik-tier:
        tier: '1'
        limit: 1000
  /api/v1/di-projects/{projectId}/di-tasks/{dataTaskId}/runtime/runs/actions/search:
    post:
      tags:
      - task run history
      summary: Search task run history
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DiSearchTaskRunHistoryRsp'
          description: Search results retrieved successfully.
        '400':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Errors'
          description: Invalid request. Check parameter formats and filter syntax.
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Errors'
          description: Project or task 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: Returns a paginated list of historical run instances for the specified data task, filtered by the provided criteria.
      operationId: search_task_runs
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/DiSearchTaskRunHistoryReq'
        required: true
        description: Search criteria and pagination options for task run history query.
      x-qlik-visibility: public
      x-qlik-stability: stable
      x-qlik-deprecated: false
      x-qlik-tier:
        tier: '2'
        limit: 100
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.
    DiSearchTaskRunHistoryRsp:
      type: object
      properties:
        runs:
          type: array
          items:
            $ref: '#/components/schemas/TaskRunItemRsp'
          description: List of task run instances matching the search.
        lastId:
          type: string
          example: caf50cbf-d6f8-47c6-a5e0-b31e0d11102a
          description: Identifier of the last run in this page. Pass this value back as `lastId` in the next request to fetch the following page.
        nextPageExists:
          type: boolean
          example: true
          description: True when more pages are available after this one; false when this is the last page.
    TaskRunSearchFilter:
      type: object
      required:
      - field
      - operator
      - value
      properties:
        field:
          $ref: '#/components/schemas/TaskRunSearchFilterField'
        value:
          type: array
          items:
            type: string
          description: Values to match. For `BETWEEN` on `PERIOD`, supply exactly two ISO-8601 timestamps.
        operator:
          $ref: '#/components/schemas/TaskRunSearchFilterOperator'
      description: Specifies a single filter criterion to apply when searching task run history.
    ListDataTaskDatasetsRsp:
      type: object
      properties:
        datasets:
          type: array
          items:
            $ref: '#/components/schemas/DataTaskDatasetState'
    TaskRunStatus:
      enum:
      - STARTING
      - RUNNING
      - COMPLETED
      - FAILED
      - CANCELED
      - MISFIRED
      type: string
      description: Execution status of a task run instance.
    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.
    TaskRunSearchFilterOperator:
      enum:
      - IN
      - NOT_IN
      - BETWEEN
      type: string
      description: 'Filter operator.

        - `IN` / `NOT_IN`: exact match against the values list (recommended for ID, STATUS, SUB_STATUS).

        - `BETWEEN`: only valid with the `PERIOD` field. The `value` list must contain two ISO-8601 timestamps (start, end).

        '
    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.
    TaskRunSearchFilterField:
      enum:
      - ID
      - STATUS
      - SUB_STATUS
      - PERIOD
      type: string
      description: The run-history field to filter on.
    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.
    DiSearchTaskRunHistoryReq:
      type: object
      properties:
        limit:
          type: integer
          format: int32
          default: 50
          maximum: 200
          minimum: 1
          description: Maximum number of runs to return.
        lastId:
          type: string
          example: caf50cbf-d6f8-47c6-a5e0-b31e0d11102a
          description: Cursor for paging. Pass the `runId` of the last item from the previous response to fetch the next page; omit on the first request.
        filters:
          type: array
          items:
            $ref: '#/components/schemas/TaskRunSearchFilter'
          example:
          - field: STATUS
            value:
            - COMPLETED
            - FAILED
            operator: IN
          - field: PERIOD
            value:
            - '2024-03-01T00:00:00Z'
            - '2024-03-31T23:59:59Z'
            operator: BETWEEN
          description: Field filters to apply to the search.
      description: Request parameters for searching task run history, including filter criteria and pagination options.
    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
    TaskRunItemRsp:
      type: object
      properties:
        runId:
          type: string
          example: caf50cbf-d6f8-47c6-a5e0-b31e0d11102a
          description: Identifier of the run instance.
        status:
          $ref: '#/components/schemas/TaskRunStatus'
        endTime:
          type: string
          format: date-time
          example: '2024-03-01T09:30:00Z'
          description: Timestamp indicating when the run ended.
        duration:
          type: string
          example: 00:30:00
          description: Duration of the run in HH:MM:SS format.
        startTime:
          type: string
          format: date-time
          example: '2024-03-01T09:00:00Z'
          description: Timestamp indicating when the run started.
        subStatus:
          type: string
          description: Sub-status of the run, when applicable.
        errorMessage:
          type: string
          default: ''
          description: Error message, if the run failed.
        datasetsCount:
          type: integer
          format: int32
          example: 10
          description: Total number of datasets processed in this run.
        originSubStatus:
          type: string
          description: Origin-specific sub-status of the run, when applicable.
        datasetsErrorCount:
          type: integer
          format: int32
          example: 0
          description: Number of datasets that encountered errors in this run.
      description: Represents a single historical task run instance with execution status, timing, and error information.
    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.