Job Tags — Rotor Docs

Tags are short string labels you attach to a job at enqueue time. They pass through to the dashboard, the REST API, and the archived job history — letting you filter and group runs without embedding metadata in your job payload.

Add tags when enqueueing

import { Rotor } from "@rotorsh/sdk";
 
const rotor = new Rotor({ apiKey: process.env.ROTOR_API_KEY! });
 
const job = await rotor.jobs.enqueue("outreach", {
  payload: { contactId: "cid_123" },
  tags: ["campaign:q2-outbound", "contact:cid_123", "env:production"],
});

Tags are returned in the response:

{
  "id": "job_abc",
  "state": "waiting",
  "tags": ["campaign:q2-outbound", "contact:cid_123", "env:production"]
}

Limits: up to 10 tags per job, each tag max 64 characters.

Batch enqueue with tags

Each job in a batch can carry its own tags:

await rotor.jobs.enqueueBatch("outreach", [
  { payload: { contactId: "cid_001" }, tags: ["campaign:q2-outbound", "contact:cid_001"] },
  { payload: { contactId: "cid_002" }, tags: ["campaign:q2-outbound", "contact:cid_002"] },
]);

Retrieve tags on a job

const job = await rotor.jobs.get("outreach", "job_abc");
console.log(job.tags); // ["campaign:q2-outbound", "contact:cid_123", "env:production"]

Filter the job list by tag

const jobs = await rotor.jobs.list("outreach", { tag: "campaign:q2-outbound" });

Or via REST:

curl "https://api.rotor.sh/v1/queues/outreach/jobs?tag=campaign%3Aq2-outbound" \
  -H "Authorization: Bearer $ROTOR_API_KEY"

Tags in the dashboard

The Runs page shows tags as grey pill badges on each row. You can scan which jobs belong to a campaign at a glance — no payload inspection required.

Tags are archived

When a job completes or fails, its tags are written to the job_history table alongside the result. Historical tag data is retained for your plan's full retention window (7d free, 30d pro, 90d team).

Naming conventions

There is no enforced format. Common patterns:

Pattern	Example	Use case
`key:value`	`campaign:q2-outbound`	Group by named campaign
`entity:id`	`contact:cid_123`	Link a job to a specific record
`env:name`	`env:production`	Distinguish prod vs staging runs
`source:name`	`source:hubspot`	Track the system that triggered the job

Tip

Tags are for filtering and grouping — not for routing or conditional logic. If you need jobs to behave differently based on a value, put that value in the job payload, not in tags.