Run a Job : MinionWare

Starts a job right now, the same as clicking Run in the Console. This doesn't run the job itself -- it queues the request; Worker picks it up and actually runs it. That's why the response is "accepted," not "here's the result" -- see Check a Job Run's Status for how to find out what actually happened.

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 (see Get a Job by Name if you want just this step on its own).
Start the run.

The call

POST /api/jobs/{jobId}/run-job

{jobId} is the job's numeric id. No request body.

Permission needed: Job.Run on this specific 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 jobResponse = await client.GetAsync($"/api/jobs/by-name/{jobName}");
jobResponse.EnsureSuccessStatusCode();
var job = await jobResponse.Content.ReadFromJsonAsync<JobSummary>(jsonOptions);

// Step 3: Start the run.
var runResponse = await client.PostAsync($"/api/jobs/{job!.JobID}/run-job", content: null);
runResponse.EnsureSuccessStatusCode();
var ack = await runResponse.Content.ReadFromJsonAsync<RunJobAck>(jsonOptions);
Console.WriteLine($"Run queued. Correlation id: {ack!.RunCorrelationId}");

record JobSummary(int JobID, string JobName);
record RunJobAck(Guid RunCorrelationId);

Not on a domain machine, or don't want to hand out Windows credentials? Swap the HttpClient setup in Step 1 for the app-account login shown in Calling the API From Your Own Code -- Steps 2 and 3 stay exactly the same.

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")
$job = Invoke-RestMethod -Uri "http://your-minion-agent-server:5443/api/jobs/by-name/$jobName" `
    -UseDefaultCredentials -AllowUnencryptedAuthentication -Headers $headers

# Step 3: Start the run.
$ack = Invoke-RestMethod -Uri "http://your-minion-agent-server:5443/api/jobs/$($job.jobID)/run-job" `
    -Method Post -UseDefaultCredentials -AllowUnencryptedAuthentication -Headers $headers

"Run queued. Correlation id: $($ack.runCorrelationId)"

What you get back

202 Accepted, with:

{ "runCorrelationId": "3fa85f64-5717-4562-b3fc-2c963f66afa6" }

Hang on to runCorrelationId -- it's what you pass to Check a Job Run's Status to find out what happened. Getting a 202 back only means the request was queued; it says nothing about whether the run itself will succeed.

Codes this call can return

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

202 -- queued successfully.
400 -- the job's steps have a circular dependency, so there's no valid order to run them in. (Also returned, as with any call, if X-App-Name is missing.)
403 -- you don't have Job.Run on this job.
404 -- no job exists with that id.

(Step 2's own lookup call has its own codes -- see Get a Job by Name -- if the job name doesn't exist you'll hit that 404 before you ever get to Step 3.)

Run a Job Print