Opens in a new tab
Tutorial

Running a Que Campaign From Code: Campaigns, Jobs, Satellites and Cleanup With the Que API

Published October 29, 2026Last modified November 3, 2026

Running a Que campaign from code comes down to five moves in a fixed order: set up a campaign with its defaults, push jobs in, read them back, watch the campaign’s statistics until the work is done, then clean up. Every one of those moves has its own endpoint in the Que API, and a few of them can delete things you cannot get back. This guide walks the whole cycle in that order, so you know which call to make at each stage and what it will cost you to get it wrong.

It picks up where our guide to getting started with the Que API, keys and your first job leaves off. That page covers the API key, the bearer header and the first job you send. We will not repeat any of it here. If you have not sent a job yet, start there and come back. Everything below assumes you have a working key, at least one satellite and at least one autograf in your account.

Every endpoint name, method and field in this guide comes from our technical API reference at que-api-docs.dataclay.com. Paths are written there, and here, as /api/v1/ followed by the resource. Take the host from the reference itself.

The campaign comes first, because it holds your defaults

A campaign is a container for jobs. For an app, the more important thing a campaign does is hold two defaults: an autograf and a satellite. An autograf is the JSON description of a rigged After Effects project, built in Templater. A satellite is a machine in your environment that runs After Effects and pulls job data from Que. When you add a job without saying which autograf or which machine it belongs to, the campaign’s defaults fill the gap. Get the defaults right and your job payloads stay small. Get them wrong and every job you send quietly inherits the mistake.

You create a campaign with POST /api/v1/campaigns. The reference marks three fields as required: name, defaultSatellite and defaultTemplate. The last one takes the ID of an autograf, even though the field still says template. Both IDs have to point at things that already exist, because the reference says a campaign cannot be created until your account has at least one autograf and one satellite. If your app runs before a designer has registered either one, the campaign call is where it will fail, so check the account first with GET /api/v1/autografs and GET /api/v1/satellites and stop early with a clear message if either list is empty.

Copying a campaign is where developers expect more than the reference gives. The reference lists a “Create a new Campaign Copy” entry, but it uses the same method, the same path and the same body fields as creating a new campaign. It does not describe a separate copy field or a way to clone a campaign’s jobs. Our reading is that a copy, in API terms, is a new campaign that reuses an existing one’s defaults. So the practical way to copy is to call GET /api/v1/campaigns, find the campaign you want to mirror, take its default satellite and default autograf IDs, and post a new campaign with a new name and those two IDs. You get the same setup, without the old campaign’s jobs.

Changing a campaign later is a PUT to /api/v1/campaigns//update, where the campaign ID goes in the path and has to be a valid MongoDB ObjectId. Watch the field names here, because they are not the same as the create call. The update body uses _defaultSatellite and _defaultTemplate, each starting with an _ character, alongside name. All three are marked required. If your code reuses the create payload for an update, the default fields will not match what the reference documents. Build the two bodies separately and you will not trip over it.

Why change defaults at all? The common reason is a machine change. The reference says that when a satellite is deleted, any campaign that named it as the default has to be pointed at another one. So the update call is part of any satellite replacement plan, and it belongs in the same script, run in the same order, every time.

One decision is worth making before you write a line: how many campaigns does your app create? One per client, one per day, or one for everything. Our reference frames the campaign as the unit where you decide how many renders a client receives and which machines do the work. For an app, the answer usually follows the cleanup plan you will read about further down. A campaign that lives forever and gets purged on a schedule is simple to reason about. A new campaign for every run is easier to audit but leaves you with more containers to manage and delete.

Putting jobs in, reading them back, and changing them

There are two ways to add jobs, and the choice is about volume and feedback rather than features.

POST /api/v1/jobs creates one job. The body needs projectId, which is the campaign ID, plus whatever keys your autograf expects. You can also send Templater’s reserved names, such as output for the output file name and target for the target composition. A new job’s render-status starts as ready unless you send a different value. If you leave out aep or bot, Que fills them with the campaign’s default autograf and satellite. The response gives you back the created job, including its new _id, and an updatedProject object that shows the campaign’s new job count. Store that _id. Every later call that touches a single job needs it.

POST /api/v1/jobs/batch imports many jobs into one campaign in a single request. The body has projectId and an array called batchJobs, where each object is one job’s key and value pairs. The same defaults apply: missing aep, bot or render-status keys are filled in with the campaign’s defaults and ready. The response is a short status rather than the jobs themselves. The example in the reference returns totalJobs, addedJobs and campaignId. That is the number to check. If addedJobs is lower than totalJobs, something in your array did not go in, and your app should say so loudly instead of assuming the batch landed whole.

The trade-off is plain. Single creates hand you each job’s ID at the moment you make it, which is useful when your own database needs to link a record to a job. Batch import is one round trip for many rows, but you only learn the IDs when you read the jobs back. If your source data has its own stable identifier, put it on each job as a property. Then you can always find a job again by filtering on that property, no matter how it was created. Our article on unique IDs in a spreadsheet or JSON data source explains why a stable ID on every row pays off, and the same reasoning carries over to Que jobs. If your jobs start life in a file rather than in code, the Dash route in our guide to inserting a batch of jobs from Excel, CSV or JSON may be all you need.

Reading jobs back is a POST, not a GET, which surprises people the first time. POST /api/v1/jobs/ returns a paginated list of jobs in one campaign. The body carries filters, each switched on by a true or false flag. jobIdFilter with jobId returns one job by ID. jobStatusFilter with jobStatus filters on render-status, and the documented values are ready, queued, processing and done. jobPropertyFilter with jobProperty matches jobs whose keys hold the values you pass, which is how you find a job by your own identifier. dateFilter with startDate and endDate, in MM-DD-YYYY format, limits the list to jobs created in a range. You sort with jobSortingProperty, a comma-separated list of keys, and jobSortDirection, where 1 is ascending and -1 is descending. You page with resultsPerPage and page.

Two small warnings from reading the reference closely. The field list names startDate and endDate directly, but the example body nests them inside a dateSearch object under creation. The example also sends jobSortDirection as 0, which is neither of the two documented values. When the field list and the example disagree, test both shapes against your own account before you depend on either one. And because the documented status filter covers only the four normal states, do not assume it accepts canceled or an error code. Pull the jobs and check render-status in your own code.

There is a second way to read jobs: POST /api/v1/satellites/jobs returns jobs assigned to one satellite, with the same filters. The difference is the credential. This call needs a satellite access token in the Authorization header, not your organization’s API key. That token comes from authorizing a satellite, which we cover in the next section. In practice this is the view a render machine has of its own work. Most apps will read per campaign. Reach for the per-satellite call when you are building tooling that runs on, or speaks for, a specific machine.

Changing a job uses the same split. PUT /api/v1/jobs/ updates a job with your API key. You send only the keys you want to change. Keys can never be removed from a job, so to clear a value you set it to an empty string. The example response returns the whole updated job. PUT /api/v1/satellites/jobs/ does the same thing, and the reference says so in as many words, except that it requires a satellite access token. Its example body sets render-status to done, and its example response is a short status and message rather than the full job. The way we read it, the first is for your app and the second is for code acting as a render machine reporting on its own work. If you are writing an app that feeds Que, use the first one.

A note on what a job carries. Every example job in the reference has a stream object with a status of pending. That belongs to distribution. Arie Stavchansky, our founder and CEO, describes stream-status as the lifecycle of delivering output to a streaming or hosting platform, with values that run pending, staged, transcoding, deploying, onstream and error. Nothing in this guide depends on it.

Tracking a campaign, and the satellite and autograf calls you will rarely need

Once jobs are in, your app needs one question answered over and over: how far along is this campaign? GET /api/v1/campaigns//stats answers it in one call. The reference describes it as a quick view of how many jobs sit in each render-status and which satellites you could assign work to. The example response has a jobStats object with a total and a count per state, including a count for canceled jobs (the example spells that key with a double l) and an err::media count. It also has a satelliteInfo list giving each machine’s name, a status flag and jobs_assigned, plus the campaign’s default satellite.

To read those counts you need the vocabulary. Arie gave it to us plainly. Ready means a job has all its data and is prepared for processing but is not queued yet. Queued means it is waiting in line for its assigned satellite. Processing means Templater is versioning and rendering it right now. Done means the render finished. Canceled means it stopped before finishing. Error codes mean it failed during processing, with ERR::MEDIA pointing at asset problems and ERR::AFXHOST pointing at After Effects itself. Our guide to Que job states and what to do next goes through each one and what to check when a job will not move. This page cares about one thing: turning those counts into a decision in code.

A simple rule works for most apps. The campaign is finished when done plus canceled plus every error count equals total. It is healthy while done keeps rising between checks. It needs a person when an error count rises, or when ready stays flat while a satellite shows jobs assigned. Do not hard-code a fixed list of error keys. The reference states that new data points will be added to these statistics as the API develops, and the example shows only one error key. A parser that rejects keys it does not recognize will break on the day the response grows.

Now the satellite endpoints. Our reference is direct that a person usually creates and authorizes a satellite in Templater, not code, and it cautions that changing or deleting a satellite anywhere other than Templater or the Que Dash can cause trouble for jobs already in the system. If you are adding a machine the normal way, our guide on what a Que satellite is and how to add one is the better route.

Setting up a satellite through the API is two calls. POST /api/v1/satellites/create registers it with a username and a password you choose. Names must be unique in your organization, and a duplicate name returns an error. Registering does not grant access. POST /api/v1/satellites/auth does that, with five pieces: the username, the password sent as secretKey, your organization key as orgKey, a host object describing the machine, and an engine object describing After Effects and Templater on it. The response is a token. That token expires five years from the day it was created, which is why the reference asks you to keep it private on the machine that requested it.

The rest of the satellite calls follow from that token. POST /api/v1/satellites/revoke takes the token in the body and revokes it for good. A revoked token can never be used again. If you think a token has leaked, the documented fix is to revoke it and authorize again for a fresh one. PUT /api/v1/satellites updates a satellite’s host or engine details, using the satellite’s own token. The reference calls it a convenience and says the better practice after a real machine change is to deauthorize and authorize again. GET /api/v1/satellites lists every satellite you have registered. Authorized ones show host and engine details, a tokenExpireDate and a revokedTokens list, which makes this the call to run if you want your app to warn someone before a token’s expiry date comes around. DELETE /api/v1/satellites/ removes a satellite. Its jobs become unassigned, and any campaign that used it as a default needs updating. If your satellites are misbehaving, our page on troubleshooting Que satellites is the place to look before you reach for delete.

Autografs work the same way. They are meant to come from Templater, where a designer clicks Create Manifest in the Autograf Setup dialog. The API calls exist for the cases that need them. POST /api/v1/autografs creates one from a manifest with two required objects, env and rig. PUT /api/v1/autografs/ merges your body into the stored autograf, though the reference says the best practice is Update Manifest in the same dialog. GET /api/v1/autografs/ returns one and GET /api/v1/autografs returns them all. For most apps, the read calls are the only ones you need. Use them to confirm that the autograf your campaign points at still exists before you send a night’s work at it.

DELETE /api/v1/autografs/ is permanent. The reference warns that a job pointing at a removed autograf stays stuck until you give it a different one. An app should almost never call this.

Cleaning up, and one nightly batch from start to finish

Three calls remove things, in very different amounts. Mixing them up is the most expensive mistake on this page.

DELETE /api/v1/jobs/ removes one job. It is permanent and the job cannot be recovered. The example response is a 204 with no body. Use it for a single row that should never have gone in.

DELETE /api/v1/campaigns//jobs purges a campaign of all its jobs. It is permanent and cannot be undone, and so the reference requires a second credential: your Organization Key in a header named org-secret-key, alongside your normal authorization header. The Organization Key is on the Account page of the Que Dash. The example response shows the campaign still in place with a count of 0. So a purge empties the container and keeps it, defaults and all.

DELETE /api/v1/campaigns/ deletes the campaign itself. The reference says the campaign’s jobs go with it, and you lose access to all of them. It also requires the org-secret-key header. After this call, the campaign’s defaults are gone too, so the next run has to create a new one.

Our advice is to keep the Organization Key out of the part of your app that runs every day. Among the calls in this guide, only purge, campaign delete and satellite authorization (where it goes in the body as orgKey) use it. If the nightly job never needs to delete a campaign, give it nothing that can.

Here is a scenario of our own, built from the documented calls. It is an illustration, not a customer story. A company runs a store app that wants a short video for every product whose price changed that day. A designer has rigged the template, registered it as an autograf, and set up two render machines as satellites in Templater. The developer owns everything after that.

Once, at setup, the developer’s script lists autografs and satellites, finds the right IDs, and creates a campaign named for the price-change videos with those two IDs as defaults. The script saves the campaign ID in the app’s configuration.

Every night, the app collects the day’s changed products. For each one it builds a job object with the keys the designer named, an output value that includes the product’s own ID so files are easy to trace, and a product ID property so the job can be found later with a property filter. It sends all of them in one POST to /api/v1/jobs/batch. Then it compares addedJobs with totalJobs. If they differ, it stops and alerts someone, because a half-loaded night is worse than a clearly failed one.

Through the night, the app calls the stats endpoint every so often. Done climbs. On one night, err::media goes up by two. The app pulls those jobs with the campaign jobs endpoint, finds the rows whose render-status is the error, and the developer sees that two products point at image files that were moved. They fix the paths with PUT /api/v1/jobs/, sending the corrected keys and render-status set back to ready, since the Bot processes jobs whose render-status is ready. Nothing else in the batch was touched.

Once a week, after the finished videos have been collected, a separate, locked-down script holding the Organization Key purges the campaign. The campaign stays, its defaults stay, and the next night starts with an empty container. Deleting the campaign instead would have meant creating and recording a new campaign ID every week for no gain.

Some things this reference does not cover, and we would rather say so than guess. It does not state a rate limit, a maximum batch size or a maximum page size. It does not publish a catalog of HTTP errors. It does not say which values the status filter accepts beyond the four normal states, or how to cancel a job through the API. It does not describe webhooks either. Those are documented separately, on the Que webhooks page in our help documentation, so if you would rather react to events than poll the stats endpoint, read that page next. For product questions, plans and pricing, see our Que page.

The bottom line is that the Que API rewards an app that respects its order. Let a person create satellites and autografs in Templater. Let your code own campaigns and jobs. Use batch import and check the count it hands back. Read progress from the stats endpoint and write your parser to expect new keys. Then clean up with the smallest tool that does the job: delete one job, purge a campaign you plan to reuse, and delete a whole campaign only when you mean it, with the Organization Key kept far away from anything that runs every night.

Frequently Asked Questions

What is the difference between purging a Que campaign and deleting it?

Purging calls DELETE /api/v1/campaigns//jobs and removes every job in the campaign while the campaign itself stays, with its defaults. Deleting calls DELETE /api/v1/campaigns/ and removes the campaign and all of its jobs. Both are permanent and cannot be undone, and both require your Organization Key in an org-secret-key header. Purge when you will reuse the campaign. Delete only when the campaign is finished for good.

Should I create Que jobs one at a time or with the batch endpoint?

Use POST /api/v1/jobs when your app needs each job’s ID at the moment it is created, for example to link it to a record in your own database. Use POST /api/v1/jobs/batch when you have many rows at once, such as a nightly run. Batch returns a short status, with totalJobs and addedJobs in the documented example, so compare the two and alert someone if they differ. Put your own identifier on every job so you can find any of them later.

When do I use Update a Job as Satellite instead of Update a Job?

Both change the keys you send on an existing job. Update a Job, PUT /api/v1/jobs/, uses your organization API key and returns the full updated job in the example. Update a Job as Satellite, PUT /api/v1/satellites/jobs/, requires a satellite access token instead, and its example returns a short status message. An app that feeds Que should use the first. The second is for code acting as a render machine.

How do I track the progress of a Que campaign from my app?

Call GET /api/v1/campaigns//stats. The example response includes a jobStats object with a total and counts for ready, queued, processing, done, canceled and an err::media error count, plus a satelliteInfo list showing jobs assigned to each machine. Treat the campaign as finished when done, canceled and error counts add up to the total. Do not reject unknown keys, because the reference says new data points will be added over time.

How do I copy an existing Que campaign through the API?

The reference lists a Create a new Campaign Copy entry, but it uses the same POST /api/v1/campaigns call and the same body as creating a campaign, and it does not describe a separate copy field. In practice you read the existing campaign with GET /api/v1/campaigns, take its default satellite and default autograf IDs, and create a new campaign with a new name and those IDs. The new campaign starts with no jobs.

Can I remove a key from a Que job after it has been created?

No. The reference states that keys cannot be deleted from a job. To clear a value, send the key with an empty string in a PUT to /api/v1/jobs/. Plan your job shape before you go live for that reason, because a misnamed key stays on every job you created with it. Clearing the value is the only cleanup available short of deleting the job.

Does the Que API support webhooks?

Webhooks are not part of the API reference this guide is built on. They are documented separately, on the Que webhooks page in our help documentation, so read that page before you design your app around polling. Until then, the documented way to follow progress is to call the campaign statistics endpoint on a schedule and read the job counts it returns.

Leave the first comment

Sign up

Stay up to date with Datclay's newsletter. We won't spam your inbox.

Newsletter Signup
Name
Name
First
Last

By submitting your email, you agree to our Terms and Privacy Policy. You can opt out at any time.