This command filters job information.

API request 

Method PUT

/users/{account_id}/devices/{connector_id}/jobs

Elements table

Root object element: filter

Example 1

Filter only active jobs via API:

Method PUT

https://dk-co.keepit.com/users/5t1sbe-s6zsgx-rtutxq/devices/11ptlk-st7sly-ggba4c/jobs

Body

<filter>
    <from-time>2024-10-14T08:12:14Z</from-time>
    <to-time>2024-10-16T08:12:14Z</to-time>
    <active-only>true</active-only>
</filter>

• <from-time> and <to-time> define the time range for which jobs should be retrieved.
• <active-only> determines whether to return only active jobs or finished jobs:
• 'true' returns only active jobs
• 'false' returns only finished jobs 

Response

Code: 200 OK

Response body:

 <jobs>
    <job>
        <guid>va14e0-sa8c7o-giq88n-hsfgdx</guid>
        <description>[backup][bl][auto][o365-admin]{Microsoft 365 Backup(8)}</description>
        <type>backup</type>
        <priority>0</priority>
        <active>true</active>
        <start>2024-10-15T00:54:29Z</start>
        <scheduled>2024-10-15T12:54:51Z</scheduled>
    </job>
</jobs>

PowerShell script

try {
    $username = '<API Token username>'
    $password = '<API Token password>'
    $userId = '<Account GUID>'
    $connectorId = '<Connector GUID>'
    $hostname = 'dk-co.keepit.com'

    $body = @"

<filter>
    <from-time>2024-10-14T08:12:14Z</from-time>
    <to-time>2024-10-16T08:12:14Z</to-time>
    <active-only>true</active-only>
</filter>
"@

    $basicauth = [Convert]::ToBase64String([System.Text.Encoding]::ASCII.GetBytes("${username}:${password}"))

    $headers = @{
        "User-Agent"    = "PowerShell-Keepit-API-Agent-1.0"
        "Authorization" = "Basic $basicauth"
        "Content-Type"  = "application/xml"
    }

    $response = Invoke-WebRequest -Uri "https://${hostname}/users/${userId}/devices/${connectorId}/jobs" `
        -Method Put -Headers $headers -Body $body -ErrorAction Stop
    $xmlContent = [xml]$response.Content

    $xmlContent.SelectNodes("//job") | ForEach-Object {
        $started = if ($_.started) { $_.started } else { "Scheduled" }

        Write-Host "GUID: $($_.guid)"
        Write-Host "Type: $($_.type)"
        Write-Host "Active: $($_.active)"
        Write-Host "Started: $started"
        Write-Host "---------------------------"
    }
}
catch {
    $line = $_.InvocationInfo.ScriptLineNumber
    Write-Host "Cannot query Keepit API due to: $_"
    Write-Host "at line $line"
}

Script result

GUID: va14e0-sa8c7o-giq88n-hsfgdx
Type: srestore
Active: true
Started: 2024-10-15T00:54:29Z

---------------------------

GUID: p6eqb9-4t1wwi-2vnnuw-y1oh5c
Type: backup
Active: true
Started: Scheduled

---------------------------

Additional information

• The <active> element indicates whether the job is currently running or has finished.
• The <succeeded> element indicates whether the job completed successfully. If it failed, the <failed> element will be shown instead.

Example 2

Filter by job type and add a fail reason:

Method PUT

https://dk-co.keepit.com/users/5t1sbe-s6zsgx-rtutxq/devices/11ptlk-st7sly-ggba4c/jobs

Body

<filter>
    <from-time>2024-10-14T08:27:14Z</from-time>
    <to-time>2024-10-16T08:27:14Z</to-time>
    <type>srestore</type>
    <limit>100</limit>
    <stats>
        <name>fail_reason</name>
    </stats>
</filter>

• The <type> element indicates the job type: backup, restore, srestore.
• The 'restore' value indicates restore via the restore wizard, while 'srestore' is selective restore (restoring via connector browsing).

Response

Code: 200 OK

Response body:

<jobs>
    <job>
        <guid>fsglzll-yvsqx2-1shdhk-fuhxgd</guid>
        <description>[srestore] [webui2] [user] [o365-admin] {Microsoft 365 Backup}</description>
        <execsummary>&lt;?xml version=&quot;1.0&quot; encoding=&quot;utf-8&quot;?&gt;&lt;execsummary&gt;&lt;summary&gt;Failed to process one or more items&lt;/summary&gt;&lt;exitreason&gt;done&lt;/exitreason&gt;&lt;/execsummary&gt;&lt;!-- End of Document 2024-10-15T16:46:12Z --&gt;</execsummary>

        <type>srestore</type>
        <priority>1</priority>
        <active>false</active>
        <start>2024-10-15T16:45:22Z</start>
        <scheduled>2024-10-15T16:45:22Z</scheduled>
        <dispatched>2024-10-15T16:45:40Z</dispatched>
        <started>2024-10-15T16:45:40Z</started>
        <failed>2024-10-15T16:46:12Z</failed>
        <progress>1.0</progress>
        <stats>
            <stat>
                <name>fail_reason</name>
                <value>failed_to_restore_some_items</value>
            </stat>
        </stats>
    </job>
</jobs>

PowerShell script

try {
    $username = '<API Token username>'
    $password = '<API Token password>'
    $userId = '<Account GUID>'
    $connectorId = '<Connector GUID>'
    $hostname = 'dk-co.keepit.com'

    $body = @"
<filter>
    <from-time>2024-10-14T08:27:14.245Z</from-time>
    <to-time>2024-10-16T08:27:14.245Z</to-time>
    <type>srestore</type>
    <limit>100</limit>
    <stats>
        <name>fail_reason</name>
    </stats>
</filter>
"@

    $basicauth = [Convert]::ToBase64String([System.Text.Encoding]::ASCII.GetBytes("${username}:${password}"))
    $headers = @{
        "User-Agent"    = "PowerShell-Keepit-API-Agent-1.0"
        "Authorization" = "Basic $basicauth"
        "Content-Type"  = "application/xml"
    }

    $response = Invoke-WebRequest -Uri "https://${hostname}/users/${userId}/devices/${connectorId}/jobs" `
        -Method Put -Headers $headers -Body $body -ErrorAction Stop
    $xmlContent = [xml]$response.Content

    $xmlContent.SelectNodes("//job") | ForEach-Object {
        $guid = $_.guid
        $type = $_.type
        $active = $_.active
        $started = if ($_.started) { $_.started } else { "Scheduled" }
        $succeeded = $_.succeeded
        $failed = $_.failed
        $progress = $_.progress

        $status = if ($succeeded) {
            "Succeeded at $succeeded"
        } elseif ($failed) {
            "Failed at $failed"
        }

        $failReason = ""
        if ($failed) {
            $xmlContent.SelectNodes("//stats/stat[name='fail_reason']/value") | ForEach-Object {

                $failReason = $_.InnerText
            }
        }

        Write-Host "Job GUID: $guid"
        Write-Host "Type: $type"
        Write-Host "Active: $active"
        Write-Host "Started: $started"
        Write-Host "Status: $status"
        Write-Host "Progress: $progress"

        if ($failReason) {
            Write-Host "Fail Reason: $failReason"
        }

        Write-Host "---------------------------"
    }
}
catch {
    $line = $_.InvocationInfo.ScriptLineNumber
    Write-Host "Cannot query Keepit API due to: $_"
    Write-Host "at line $line"
}

Script result

Job GUID: va14e0-sa8c7o-giq88n-hsfgdx
Type: srestore
Active: false
Started: 2024-10-15T00:54:29Z
Status: Succeeded at 2024-10-15T00:56:21Z
Progress: 1.0
---------------------------

Job GUID: fsglzll-yvsqx2-1shdhk-fuhxgd
Type: srestore
Active: false
Started: 2024-10-15T16:45:40Z
Status: Failed at 2024-10-15T16:46:12Z
Progress: 1.0
Fail Reason: failed_to_restore_some_items
---------------------------

Additional information

• In this example, the job type is selective restore, indicated by 'srestore' in the <type> element.
• The job monitor functionality in the UI is described here.