Skip to main content
This quickstart applies to one-off tasks and recurring cron and rrule schedules.

​
1. Define your task

Your task definition is where you'll perform your tasks, such as sending emails, processing files, or moving data between systems. With Mergent, tasks are defined by HTTP request handlers inside your application.
pages/api/tasks.js
import Mergent from "mergent";

export default async function handler(req, res) {
  try {
    await performTask(req);
    // task was successful, respond with 200
    res.status(200).send("");
  } catch (err) {
    // task failed, respond with 500 so Mergent will retry
    res.status(500).send({ error: err });
  }
}

async function performTask(req) {
  // This is where you'll perform your task.
  // For now, we'll just log it.
  console.log("Performing task: ", req.body);
}
For a list of all the available parameters, visit the API Reference.

​
2. Get your handler's URL

Before you can run your task, your handler must be accessible from the internet. To do this, you can use a tool like ngrok, or deploy your application to a platform like Vercel or Render. For more information, see our guide to localhost dev & webhooks.

​
3. Create your first task

Once your task handler is reachable via a URL, you can create your first task. Go to the Mergent Tasks Dashboard and click the Create button.
In this step, you'll set the Request URL to your task handler's URL. You'll also provide the required parameters (in the request body) for your handler to carry out the task.
Typically, developers use a type parameter to distinguish between different tasks. This allows your task handler to route and process tasks accordingly. Feel free to structure your parameters in a way that works best for your application.
Click Create to queue the task. Once the task executes, you should see the related log in your console, indicating a successful run. 🎊

​
4. Next Steps

At this point, you have a few options:
Create your first schedule by clicking Create in the Schedules Dashboard.
Your schedule will now create tasks using the cron schedule you provided. 🎊

​
1. Obtain your API keys

Mergent authenticates all requests using project API keys.API keys can be obtained from the Project Settings screen in the Dashboard.

​
2. Install the SDK

npm install mergent --save
# or
yarn add mergent

​
3. Create your task

Create a task whenever you need to. For example, you might create a task any time a user signs up.Use the URL of the task definition you'd like to run.
const Mergent = require("mergent");

// set the Mergent API key
const mergent = new Mergent("...");

// create a task that will run in 5 minutes
// the URL should be set to the URL of your task handler
// if using JSON, don't forget to set the Content-Type header
mergent.tasks
  .create({
    request: {
      url: "...",
      headers: { "Content-Type": "application/json" },
      body: JSON.stringify({ hello: "world" }),
    },
    delay: { minutes: 5 },
  })
  .then((task) => console.log(task))
  .catch((error) => console.error(error));
You can now create a task any time you'd like to perform some work in the background. 🎊

​
1. Obtain your API keys

Mergent authenticates all requests using project API keys.API keys can be obtained from the Project Settings screen in the Dashboard.

​
2. Create your task

Create a task whenever you need to. For example, you might create a task any time a user signs up.Use the URL of the task definition you'd like to run.
const fetch = require("node-fetch");

// set the Mergent API key
const apiKey = "...";

// create a task that will run in 5 minutes
// the URL should be set to the URL of your task handler
// if using JSON, don't forget to set the Content-Type header
fetch("https://api.mergent.co/v2/tasks", {
  method: "POST",
  headers: { Authorization: `Bearer ${apiKey}` },
  body: JSON.stringify({
    request: {
      url: "...",
      headers: { "Content-Type": "application/json" },
      body: JSON.stringify({ hello: "world" }),
    },
    delay: "PT5M", // 5 minutes
  }),
})
  .then((response) => response.json())
  .then((task) => console.log(task))
  .catch((error) => console.error(error));
You can now create a task any time you'd like to perform some work in the background. 🎊
Check out our Next.js example repository on GitHub.

​
Learn More

Tasks & Schedules

Better understand the two core concepts of Mergent: tasks & schedules

How Tasks Work

Learn more about tasks for one-off asynchronous workloads

How Schedules Work

Learn more about schedules and how they create tasks

Request Failures & Retries

Learn how Mergent retries tasks when they fail
⌘I