Commands / Get-sqmAgentJobHistory
Get-sqmAgentJobHistory
Performance sqmSQLTool v1.8.2+ · Monitoring
Returns the execution history of SQL Agent jobs, with filtering by job name, status (Success/Failure/Retry/Cancelled), time range, or last X executions. Each history entry includes job name, step name, run date, outcome, message, and duration formatted as Xh Ym Zs.

Can optionally export results to CSV for auditing or reporting.

Parameters

ParameterTypeRequiredDefaultNotes
-SqlInstancestringOptional$env:COMPUTERNAMETarget SQL Server instance.
-SqlCredentialPSCredentialOptional—Credentials for the connection.
-JobNamestringOptional* = all jobsJob name or wildcard pattern (e.g. *Backup*).
-StatusstringOptional—Filter by outcome: Success, Failure, Retry, Cancelled. Default: all statuses.
-SincedatetimeOptional7 days agoShow history from this date onwards.
-LastXintOptional—Instead of a time range: return the last X executions per job.
-OutputPathstringOptional—Optional CSV export path.
-EnableExceptionswitchSwitch$falseRe-throw exceptions instead of returning $null.

Execution Flow

START dbatools available? NO throw: dbatools not found YES Get-DbaAgentJob (load all jobs) Apply -JobName wildcard filter via -like Map -Status param to dbatools OutcomeType Success→Succeeded, Failure→Failed, Retry→Retry, Cancelled→Cancelled foreach $job in $jobs Get-DbaAgentJobHistory -Job $job.Name -StartDate $Since (or -OutcomeType filter) If -LastX: Select-Object -First $LastX For each history entry: format Duration (convert TimeSpan to "XhYmZs") Add [PSCustomObject] to results: JobName, StepName, RunDate, Outcome, Message, Duration, SqlInstance catch job: log ERROR (continue) -OutputPath specified? YES Export-Csv -Path $OutputPath NO Return [PSCustomObject[]] job history

Examples

Get all job history from the last 7 days (default)
Get-sqmAgentJobHistory
Get failed backup job history from the last 24 hours
Get-sqmAgentJobHistory -JobName "*Backup*" -Status Failure -Since (Get-Date).AddDays(-1)
Get last 5 executions per job and export to CSV
Get-sqmAgentJobHistory -LastX 5 -OutputPath "D:\Reports\job-history.csv"
← Back
Command Index