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.