REST API for Oracle Analytics Server

Get reload history for a dataset

get

/api/20210901/catalog/datasets/{datasetId}/history

Return the reload history for a given dataset. Includes options to filter results by job status and start time, exclude task history, and limit the number of jobs returned. Job history includes details such as job name, job ID, status, type, start time, end time, run duration, queue duration, origin, and number of tasks. Task history includes details such as task name, status, source and target, start time, end time, run duration, size of data processed, read throughout, and number of successful rows.

Request

Path Parameters

datasetId(required): string(byte)

The object ID of the dataset with Base64 encoding. For example, if your dataset has the object ID 'Admin'.'dataSet124', enter the Base64 encoded value, J0FkbWluJy4nZGF0YVNldDEyNCc.

Query Parameters

fromStartTime: string(byte)

Return jobs that start after this time value. Acceptable date and time formats: yyyy-MM-dd'T'HH:mm:ss.SZ, yyyy-MM-dd HH:mm:ss, yyyy-MM-dd.
includeTasks: boolean(byte)

Specifies whether to return historical task and job information or only the job history. Possible values are true or false. Specify true, to return both task history and job history. Specify false, to return only job history. The default value is true.
jobStatus: string(byte)

Status of jobs to return. Valid status values include: ACCEPTED, IN_PROGRESS, FAILED, SUCCEEDED, CANCELING, CANCELED.
numberOfJobs: number(byte)

Maximum number of job histories to return starting from the newest. If the value you specify exceeds the total number of job histories available, all jobs for the given object are returned.
toStartTime: string(byte)

Return jobs that start before this time value. Acceptable date and time formats: yyyy-MM-dd'T'HH:mm:ss.SZ, yyyy-MM-dd HH:mm:ss, yyyy-MM-dd.

There's no request body for this operation.

Response

Supported Media Types

application/json

200 Response

Successful operation.

Root Schema : schema

Type: array

Show Source

Array of: object jobInformation

{
    "type":"array",
    "items":{
        "$ref":"#/components/schemas/jobInformation"
    }
}

Nested Schema : jobInformation

Type: object

Show Source

jobEndTimestamp: string

Time job finished.
jobExecutionTimestamp: string

Time job started.
jobIdentifier: string

Identifier for the job.
jobName: string

Name of the job.
jobNumberOfTasks: number

Number of tasks in the job.
jobOriginOfRequest: string

Source of the job request. Either Manual or Schedule.
jobQueuedDuration: string

Length of time (in seconds) that the job spent in the queue.
jobRunDuration: string

Length of time taken (in seconds) for the job to run.
jobRunType: string

Type of job. For example: DATASET, DATAFLOW, SEQUENCE.
jobStartTimestamp: string

Time job requested.
jobStatus: string

Status of the job. For example: ACCEPTED, IN_PROGRESS, FAILED, SUCCEEDED, CANCELING, CANCELED.
jobTasks: array jobTasks

{
    "properties":{
        "jobName":{
            "type":"string",
            "description":"Name of the job."
        },
        "jobIdentifier":{
            "type":"string",
            "description":"Identifier for the job."
        },
        "jobRunType":{
            "type":"string",
            "description":"Type of job. For example: DATASET, DATAFLOW, SEQUENCE.\n"
        },
        "jobStatus":{
            "type":"string",
            "description":"Status of the job. For example: ACCEPTED, IN_PROGRESS, FAILED, SUCCEEDED, CANCELING, CANCELED.\n"
        },
        "jobStartTimestamp":{
            "type":"string",
            "description":"Time job requested."
        },
        "jobExecutionTimestamp":{
            "type":"string",
            "description":"Time job started."
        },
        "jobEndTimestamp":{
            "type":"string",
            "description":"Time job finished."
        },
        "jobQueuedDuration":{
            "type":"string",
            "description":"Length of time (in seconds) that the job spent in the queue."
        },
        "jobRunDuration":{
            "type":"string",
            "description":"Length of time taken (in seconds) for the job to run."
        },
        "jobOriginOfRequest":{
            "type":"string",
            "description":"Source of the job request. Either Manual or Schedule."
        },
        "jobNumberOfTasks":{
            "type":"number",
            "description":"Number of tasks in the job."
        },
        "jobTasks":{
            "type":"array",
            "items":{
                "$ref":"#/components/schemas/taskInformation"
            }
        }
    }
}

Nested Schema : jobTasks

Type: array

Show Source

Array of: object taskInformation

{
    "type":"array",
    "items":{
        "$ref":"#/components/schemas/taskInformation"
    }
}

Nested Schema : taskInformation

Type: object

Show Source

taskAverageReadThroughput: number

Average read throughput for the task.
taskDataSizeInBytes: number

Total data processed by the task in bytes.
taskEndTimestamp: string

Time the task finished.
taskName: string

Name of the task.
taskNumberOfSuccessfulRows: number

Number of rows successfully processed by this task.
taskRunDuration: string

Length of time taken (in seconds) for the task to run.
taskSourceName: string

Name of the source connection.
taskStartTimestamp: string

Time the task started.
taskStatus: string

Status of the task. For example: ACCEPTED, IN_PROGRESS, FAILED, SUCCEEDED, CANCELING, CANCELED.
taskTargetName: string

Name of the target connection.

{
    "properties":{
        "taskName":{
            "type":"string",
            "description":"Name of the task."
        },
        "taskSourceName":{
            "type":"string",
            "description":"Name of the source connection."
        },
        "taskTargetName":{
            "type":"string",
            "description":"Name of the target connection."
        },
        "taskStatus":{
            "type":"string",
            "description":"Status of the task. For example: ACCEPTED, IN_PROGRESS, FAILED, SUCCEEDED, CANCELING, CANCELED.\n"
        },
        "taskDataSizeInBytes":{
            "type":"number",
            "description":"Total data processed by the task in bytes."
        },
        "taskStartTimestamp":{
            "type":"string",
            "description":"Time the task started."
        },
        "taskEndTimestamp":{
            "type":"string",
            "description":"Time the task finished."
        },
        "taskAverageReadThroughput":{
            "type":"number",
            "description":"Average read throughput for the task."
        },
        "taskRunDuration":{
            "type":"string",
            "description":"Length of time taken (in seconds) for the task to run."
        },
        "taskNumberOfSuccessfulRows":{
            "type":"number",
            "description":"Number of rows successfully processed by this task."
        }
    }
}

403 Response

Forbidden (missing permissions for operation, request denied for unspecified reason, and so on).

Root Schema : Error

Type: object

Show Source

code(required): string

Short error code that defines the error, meant for programmatic parsing.
message(required): string

Human-readable error string.

{
    "type":"object",
    "properties":{
        "code":{
            "type":"string",
            "description":"Short error code that defines the error, meant for programmatic parsing.\n"
        },
        "message":{
            "type":"string",
            "description":"Human-readable error string.\n"
        }
    },
    "required":[
        "code",
        "message"
    ]
}

404 Response

Not Found. The requested resource was not found.

Root Schema : Error

Type: object

Show Source

code(required): string

Short error code that defines the error, meant for programmatic parsing.
message(required): string

Human-readable error string.

{
    "type":"object",
    "properties":{
        "code":{
            "type":"string",
            "description":"Short error code that defines the error, meant for programmatic parsing.\n"
        },
        "message":{
            "type":"string",
            "description":"Human-readable error string.\n"
        }
    },
    "required":[
        "code",
        "message"
    ]
}

500 Response

Internal Server Error. The server encountered an unexpected condition preventing fulfilment of the request.

Root Schema : Error

Type: object

Show Source

code(required): string

Short error code that defines the error, meant for programmatic parsing.
message(required): string

Human-readable error string.

{
    "type":"object",
    "properties":{
        "code":{
            "type":"string",
            "description":"Short error code that defines the error, meant for programmatic parsing.\n"
        },
        "message":{
            "type":"string",
            "description":"Human-readable error string.\n"
        }
    },
    "required":[
        "code",
        "message"
    ]
}

Examples

In this example, you return the detailed history of reload operations for a given datasetID. The object ID of the data set is 'john.smith@mycompany.com'.'MySalesDataset' which has the Base64URL-safe encoded datasetID value: J2pvaG4uc21pdGhAbXljb21wYW55LmNvbScuJ015U2FsZXNEYXRhc2V0Jw.

cURL Example:

curl -i \
     --header 'Authorization: Bearer <token>' \
     --header 'Content-Type: application/json' \
     --request GET 'https://<hostname>/api/20210901/catalog/datasets/J2pvaG4uc21pdGhAbXljb21wYW55LmNvbScuJ015U2FsZXNEYXRhc2V0Jw/history' \

This example returns all history for the data set.

Note: You can use the numberOfJobs parameter to restrict the number of jobs returned. All the jobs are returned if the parameter is omitted or set to 0 (numberOfJobs=0).

Example of Request Body

Not applicable.

Example of Response Body

[
    {
    "jobName":"'john.smith@mycompany.com'.'MySalesDataSet: Enrich MySales Report'",
    "jobIdentifier":"1234ABCD5678EFGH9012IJKL3456MNOP",
    "jobStartTimestamp":"2024-06-24T16:08:44.0+0000",
    "jobExecutionStartTimestamp":"2024-06-24T16:09:14.0+0000",
    "jobEndTimestamp":"2024-06-24T16:09:45.0+0000",
    "jobStatus":"SUCCEEDED",
    "jobRunType":"DATASET",
    "jobNumberOfSuccessfulRows":"29796",
    "jobQueuedDuration":"PT1M1S",
    "jobRunDuration":"PT31S",
    "jobOriginOfRequest":"External",
    "jobNumberOfTasks":"1",
    "jobTasks":[{
        {"taskName":"DSET : MySalesDataSet: Enrich MySales Report",
        "taskStartTimestamp":"2024-06-06T21:24:14.0+0000",
        "taskStatus":"IN_PROGRESS",
        "taskSourceName":"'john.smith@mycompany.com'.'MySalesDataSet: Enrich MySales Report'",
        "taskTargetName":"Data Set Storage",
        "taskAverageReadThroughput":"1220",
        "taskDuration":"PT7.691S"},

        {"taskName":"DSET : MySalesDataSet 2",
        "taskStatus":"ACCEPTED",
        "taskSourceName":"Internal Data Set Storage",
        "taskTargetName":"Data Set Storage",
        "taskDuration":"PT477141H24M21.691S"}]
    },
{"jobName":"'john.smith@mycompany.com'.'MySalesDataSet: Enrich MySales Report'",
    "jobIdentifier":"2345ABCD6789EFGH0123IJKL4567MNOP",
    "jobStartTimestamp":"2024-04-17T15:19:47.0+0000",
    "jobExecutionStartTimestamp":"2024-04-17T15:20:04.0+0000",
    "jobEndTimestamp":"2024-04-17T15:20:28.0+0000",
    "jobStatus":"SUCCEEDED",
    "jobRunType":"DATASET",
    "jobNumberOfSuccessfulRows":"144",
    "jobQueuedDuration":"PT41S",
    "jobRunDuration":"PT24S",
    "jobOriginOfRequest":"Manual",
    "jobNumberOfTasks":"3",
    "jobTasks":[{
        {"taskName":"DSET : MySalesDataSet: Enrich MySales Report",
        "taskStartTimestamp":"2024-04-17T15:20:16.0+0000",
        "taskEndTimestamp":"2024-04-17T15:20:24.0+0000",
        "taskStatus":"SUCCEEDED",
        "taskSourceName":"'john.smith@mycompany.com'.'MySalesDataSet - Set 1'",
        "taskTargetName":"Data Set Storage",
        "taskAverageReadThroughput":"1714",
        "taskDataSizeInBytes":"65536",
        "taskNumberOfSuccessfulRows":"72",
        "taskDuration":"PT8S"},

        {"taskName":"DSET : MySalesDataSet 2",
        "taskStartTimestamp":"2024-04-17T15:20:25.0+0000",
        "taskEndTimestamp":"2024-04-17T15:20:28.0+0000",
        "taskStatus":"SUCCEEDED",
        "taskSourceName":"Internal Data Set Storage",
        "taskTargetName":"Data Set Storage",
        "taskAverageReadThroughput":"6545",
        "taskDataSizeInBytes":"13486",
        "taskNumberOfSuccessfulRows":"72",
        "taskDuration":"PT3S"}
        ]
    },
    ...
]

cURL Example with Parameters:

If you want to return specific reload history, you can apply one or more query parameters to filter the results by job status or start time, exclude task history, and limit the number of jobs returned. For example, you might want to return only jobs that succeeded from a particular date (2024-05-01) and exclude task information.

curl -i \
     --header 'Authorization: Bearer <token>' \
     --header 'Content-Type: application/json' \
     --request GET 'https://<hostname>/api/20210901/catalog/datasets/J2pvaG4uc21pdGhAbXljb21wYW55LmNvbScuJ015U2FsZXNEYXRhc2V0Jw/history?jobStatus=SUCCEEDED&fromStartTime=2024-05-01&includeTasks=false'