Runs a piece of command text against a step's target server right now, without saving it or touching the step's own saved command text -- the same thing the Console's "Test" button does. Like Run a Job, this only queues the request; Worker actually runs it.

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

  1. Authenticate to the API.
  2. Get the step's id.
  3. Send the command text to try, and start it.
  4. Check its status the same way you would a job run (see below).

The call

POST /api/job-steps/{jobStepId}/run

Permission needed: Job.Run on this step.

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: You already have the jobStepId (from List a Job's Steps).
var jobStepId = 214;

// Step 3: Send the command text to try, and start it.
var adHoc = new RunStepRequest(CommandText: "SELECT COUNT(*) FROM dbo.StagingTable");
var response = await client.PostAsJsonAsync($"/api/job-steps/{jobStepId}/run", adHoc, jsonOptions);
response.EnsureSuccessStatusCode();
var ack = await response.Content.ReadFromJsonAsync<RunAck>(jsonOptions);
Console.WriteLine($"Queued. Correlation id: {ack!.RunCorrelationId}");

record RunStepRequest(string CommandText, bool PreviewOnly = false);
record RunAck(Guid RunCorrelationId);

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: You already have the jobStepId (from List a Job's Steps).
$jobStepId = 214

# Step 3: Send the command text to try, and start it. (-AllowUnencryptedAuthentication: PowerShell requires this for Windows auth over plain http to anything but localhost -- see "Network Access & Authentication Security".)
$body = @{ CommandText = "SELECT COUNT(*) FROM dbo.StagingTable" } | ConvertTo-Json
$ack = Invoke-RestMethod -Uri "http://your-minion-agent-server:5443/api/job-steps/$jobStepId/run" `
    -Method Post -Body $body -ContentType "application/json" -UseDefaultCredentials -AllowUnencryptedAuthentication -Headers $headers

"Queued. Correlation id: $($ack.runCorrelationId)"

What you get back

202 Accepted:

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

There's no dedicated "check ad-hoc step run status" endpoint documented yet -- this pairs with the same Check a Job Run's Status-style polling pattern; check back here once that page covers the ad-hoc case specifically.

Codes this call can return

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

  • 202 -- queued.
  • 400 -- the command text contains a blacklisted phrase, or the step's resolved target server is deactivated.
  • 403 -- you don't have Job.Run on this step.
  • 404 -- no step exists with that id.

See also: Run a Job, List a Job's Steps.