Get a Job : MinionWare

Returns the full detail for one job -- its steps, dependencies, tags, and settings -- not just the summary row you get from List Jobs. This is the richest single call in the Jobs API; if you only need a handful of fields, deserialize into your own smaller type instead of the full shape below (extra JSON properties are just ignored).

Having trouble reaching the API, or logging in from another machine? See Network Access & Authentication Security -- by default the Api only answers localhost, and PowerShell needs an extra flag once it does answer elsewhere.

Order of Operations

Authenticate to the API.
Get the job's id (by name or from the list).
Request the job's detail.

The call

GET /api/jobs/{jobId}

Permission needed: Job.View on this job.

C# example

var jsonOptions = new JsonSerializerOptions(JsonSerializerDefaults.Web);

// Step 1: Authenticate to the API.
using var handler = new HttpClientHandler { UseDefaultCredentials = true };
using var client = new HttpClient(handler) { BaseAddress = new Uri("http://your-minion-agent-server:5443") };
client.DefaultRequestHeaders.Add("X-App-Name", "MyIntegration");

// Step 2: Get the job's id by name.
var jobName = Uri.EscapeDataString("Nightly ETL Load");
var jobRef = await (await client.GetAsync($"/api/jobs/by-name/{jobName}")).Content.ReadFromJsonAsync<JobRef>(jsonOptions);

// Step 3: Request the job's detail.
// Only declaring the fields we actually care about here -- System.Text.Json
// ignores any JSON property that isn't on the target type, so you don't have
// to model the entire (much larger) real response just to read a few fields.
var job = await client.GetFromJsonAsync<JobDetailSubset>($"/api/jobs/{jobRef!.JobID}", jsonOptions);
Console.WriteLine($"{job!.JobName}: {job.Steps.Count()} step(s), active = {job.IsActive}");

record JobRef(int JobID);
record JobDetailSubset(int JobID, string JobName, bool IsActive, IEnumerable<StepRef> Steps);
record StepRef(string StepName, byte StepTypeCode);

Not on a domain machine? Swap in the app-account login from Calling the API From Your Own Code.

PowerShell example

# Step 1: Authenticate to the API.
$headers = @{ "X-App-Name" = "MyIntegration" }

# Step 2: Get the job's id by name. (-AllowUnencryptedAuthentication: PowerShell requires this for Windows auth over plain http to anything but localhost -- see "Network Access & Authentication Security".)
$jobName = [Uri]::EscapeDataString("Nightly ETL Load")
$jobRef = Invoke-RestMethod -Uri "http://your-minion-agent-server:5443/api/jobs/by-name/$jobName" -UseDefaultCredentials -AllowUnencryptedAuthentication -Headers $headers

# Step 3: Request the job's detail.
$job = Invoke-RestMethod -Uri "http://your-minion-agent-server:5443/api/jobs/$($jobRef.jobID)" -UseDefaultCredentials -AllowUnencryptedAuthentication -Headers $headers

"$($job.jobName): $($job.steps.Count) step(s), active = $($job.isActive)"

What you get back

200 OK. The real shape carries a lot more than shown in the earlier examples -- a trimmed-down look at what's actually there:

{
    "jobID": 42,
    "jobName": "Nightly ETL Load",
    "description": "Loads the warehouse tables from the OLTP source.",
    "isActive": true,
    "folderId": 3,
    "contactName": "Data Team",
    "contactEmail": "data-team@example.com",
    "contactPhone": null,
    "credentialId": null,
    "credentialName": null,
    "jobVersionID": 7,
    "steps": [ { "stepKey": "...", "stepName": "Stage table 1", "stepTypeCode": 0, "commandText": "...", "...": "..." } ],
    "tags": [ { "tagID": 5, "tagName": "prod", "color": "#c0392b" } ],
    "inheritedTags": [],
    "dependencies": [ { "jobStepDependencyId": 12, "jobStepId": 101, "dependsOnJobStepId": 100, "requiredStatusCode": 2 } ],
    "targetServerId": 7,
    "targetServerName": "SQLPROD01",
    "isGlobal": false,
    "requireAllGates": false
}

Each step in steps carries its own large set of fields (command text, credential, target server, canvas position, pool/gate/delay settings, and more) -- if you need those, model the specific fields you want rather than the whole thing.

Codes this call can return

See API Response Codes for what each one means in general. For this specific call:

200 -- found it.
403 -- you don't have Job.View on this job.
404 -- no job exists with that id.

See also: List Jobs, Get a Job by Name.

Get a Job Print