Given a tag, returns every folder, job, and step that carries it -- direct or inherited (a job in a tagged folder shows up here even if it was never tagged itself).

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 tag's id (from List Tags).
3. Request what it applies to.

The call

GET /api/tags/{tagId}/items

Permission needed: Job.View.

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 tag's id (from List Tags).
var tagId = 5;

// Step 3: Request what it applies to.
var response = await client.GetAsync($"/api/tags/{tagId}/items");
if (response.StatusCode == System.Net.HttpStatusCode.NotFound)
{
    Console.WriteLine("No tag with that id.");
}
else
{
    response.EnsureSuccessStatusCode();
    var items = await response.Content.ReadFromJsonAsync<TagItems>(jsonOptions);
    Console.WriteLine($"{items!.Jobs.Count()} job(s), {items.Steps.Count()} step(s), {items.Folders.Count()} folder(s).");
}

record TagInfo(int TagID, string TagName, string Color);
record TaggedFolder(int FolderId, string FolderName);
record TaggedJob(int JobId, string JobName);
record TaggedStep(int JobStepId, string StepName, int JobId, string JobName);
record TagItems(TagInfo Tag, IEnumerable<TaggedFolder> Folders, IEnumerable<TaggedJob> Jobs, IEnumerable<TaggedStep> Steps);

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 tag's id (from List Tags).
$tagId = 5

# Step 3: Request what it applies to. (-AllowUnencryptedAuthentication: PowerShell requires this for Windows auth over plain http to anything but localhost -- see "Network Access & Authentication Security".)
try {
    $items = Invoke-RestMethod -Uri "http://your-minion-agent-server:5443/api/tags/$tagId/items" -UseDefaultCredentials -AllowUnencryptedAuthentication -Headers $headers
    "$($items.jobs.Count) job(s), $($items.steps.Count) step(s), $($items.folders.Count) folder(s)."
}
catch [Microsoft.PowerShell.Commands.HttpResponseException] {
    if ($_.Exception.Response.StatusCode -eq 404) {
        "No tag with that id."
    } else {
        throw
    }
}

What you get back

200 OK:

{
    "tag": { "tagID": 5, "tagName": "prod", "color": "#c0392b" },
    "folders": [ { "folderId": 3, "folderName": "ETL" } ],
    "jobs": [ { "jobId": 42, "jobName": "Nightly ETL Load" } ],
    "steps": [ { "jobStepId": 101, "stepName": "Stage table 2", "jobId": 42, "jobName": "Nightly ETL Load" } ]
}

Every job/step under a tagged folder counts as carrying that tag here, whether or not it was tagged directly.

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 anywhere.
• 404 -- no tag exists with that id.

See also: List Tags, Update a Tag's Color.