REST API for Oracle Analytics Cloud

Get run history for a sequence

get

/api/20210901/catalog/sequences/{sequenceId}/history

Return the run history for a given sequence. 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

sequenceId(required): string(byte)

The object ID of the sequence with Base64URL encoding. For example, if your sequence has the object ID 'User1'.'sequence1', enter the Base64URL encoded value, J1VzZXIxJy4nc2VxdWVuY2UxJw==.

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

{
    "items":{
        "type":"array",
        "$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: 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":{
            "items":{
                "type":"array",
                "$ref":"#/components/schemas/taskInformation"
            }
        }
    }
}

Nested Schema : jobTasks

Type: array

Show Source

Array of: object taskInformation

{
    "items":{
        "type":"array",
        "$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 a job run for a given sequenceID. The object ID of the sequence is 'john.smith@mycompany.com'.'MySalesSequences' which has the Base64URL-safe encoded sequenceID value: J2pvaG4uc21pdGhAbXljb21wYW55LmNvbScuJ015U2FsZXNTZXF1ZW5jZXMn.

cURL Example:

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

This example returns all history for the sequence.

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'.'MySalesSequence: Enrich MySales Report'",
    "jobIdentifier":"1234ABCD5678EFGH9012IJKL3456MNOP",
    "jobStartTimestamp":"2024-06-06T21:23:47.0+0000",
    "jobExecutionStartTimestamp":"2024-06-06T21:24:02.0+0000",
    "jobStatus":"IN_PROGRESS",
    "jobRunType":"SEQUENCE",
    "jobQueuedDuration":"PT34.691S",
    "jobRunDuration":"PT19.691S",
    "jobOriginOfRequest":"Manual",
    "jobNumberOfTasks":"3",
    "jobTasks":[
        {"taskName":"DFLW : MySalesDataFlow",
        "taskStartTimestamp":"2024-06-06T21:24:09.0+0000",
        "taskEndTimestamp":"2024-06-06T21:24:14.0+0000",
        "taskStatus":"SUCCEEDED",
        "taskDuration":"PT5S"},

        {"taskName":"DSET : MySalesDataSet 1",
        "taskStartTimestamp":"2024-06-06T21:24:14.0+0000",
        "taskStatus":"IN_PROGRESS",
        "taskSourceName":"'john.smith@mycompany.com'.'MySalesDataSet - Set 1'",
        "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'.'MySalesSequence: 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":"SEQUENCE",
    "jobNumberOfSuccessfulRows":"144",
    "jobQueuedDuration":"PT41S",
    "jobRunDuration":"PT24S",
    "jobOriginOfRequest":"Manual",
    "jobNumberOfTasks":"3",
    "jobTasks":[
        {"taskName":"DFLW : MySalesDataFlow",
        "taskStartTimestamp":"2024-04-17T15:20:10.0+0000",
        "taskEndTimestamp":"2024-04-17T15:20:16.0+0000",
        "taskStatus":"SUCCEEDED",
        "taskDuration":"PT6S"},
        
        {"taskName":"DSET : MySalesDataSet 1",
        "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"}
        ]
    },
{"jobName":"'john.smith@mycompany.com'.'MySalesSequence: MySales Sequence Report'",
    "jobIdentifier":"3456ABCD7890EFGH1234IJKL5678MNOP",
    "jobStartTimestamp":"2024-04-15T22:47:47.0+0000",
    "jobExecutionStartTimestamp":"2024-04-15T22:48:03.0+0000",
    "jobEndTimestamp":"2024-04-15T22:48:24.0+0000",
    "jobStatus":"SUCCEEDED",
    "jobRunType":"SEQUENCE",
    "jobNumberOfSuccessfulRows":"144",
    "jobQueuedDuration":"PT37S",
    "jobRunDuration":"PT21S",
    "jobOriginOfRequest":"Manual",
    "jobNumberOfTasks":"3",
    "jobTasks":[
        {"taskName":"DFLW : MySalesDataFlow",
        "taskStartTimestamp":"2024-04-15T22:48:08.0+0000",
        "taskEndTimestamp":"2024-04-15T22:48:13.0+0000",
        "taskStatus":"SUCCEEDED",
        "taskDuration":"PT5S"},

        {"taskName":"DSET : MySalesDataSet 1",
        "taskStartTimestamp":"2024-04-15T22:48:13.0+0000",
        "taskEndTimestamp":"2024-04-15T22:48:19.0+0000",
        "taskStatus":"SUCCEEDED",
        "taskSourceName":"'john.smith@mycompany.com'.'MySalesDataSet - Set 1'",
        "taskTargetName":"Data Set Storage",
        "taskAverageReadThroughput":"1043",
        "taskDataSizeInBytes":"65536",
        "taskNumberOfSuccessfulRows":"72",
        "taskDuration":"PT6S"},

        {"taskName":"DSET : MySalesDataSet 2",
        "taskStartTimestamp":"2024-04-15T22:48:20.0+0000",
        "taskEndTimestamp":"2024-04-15T22:48:23.0+0000",
        "taskStatus":"SUCCEEDED",
        "taskSourceName":"Internal Data Set Storage",
        "taskTargetName":"Data Set Storage",
        "taskAverageReadThroughput":"5142",
        "taskDataSizeInBytes":"13486",
        "taskNumberOfSuccessfulRows":"72",
        "taskDuration":"PT3S"}
        ]
    }
]

cURL Example with Parameters:

If you want to return specific run 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/sequences/J2pvaG4uc21pdGhAbXljb21wYW55LmNvbScuJ015U2FsZXNTZXF1ZW5jZXMn/history?jobStatus=SUCCEEDED&fromStartTime=2024-05-01&includeTasks=false'