Getting Started

Install Django Task API

Install the Python library with pip:

$ pip install django-task-api

Django Task API is compatible and tested with Python versions 2.7, 3.5, 3.6, and 3.7, and with Django versions 1.11, 2.0, and 2.1.

Set up Celery

By default, Django Task API uses Celery to manage background tasks. If you’re not already using Celery, follow the First steps with Django document to configure Celery for your project.

Create a task

Create a module in your Django app called and add a task class to it:

from time import sleep

from task_api.params import IntParameter
from task_api.tasks import Task

class WaitTask(Task):
    name = 'wait'

    inputs = {
        'seconds': IntParameter(required=False)

    def run(seconds=10):

        for _ in range(seconds):

The WaitTask task accepts an integer value and counts toward that number, one second at a time. Since it updates its progress, we’ll be able to monitor it from the front-end.

Configure settings & URLS

Edit, add the task_api app, and add tasks to TASK_API_BACKGROUND_TASKS.

TASK_API_BACKGROUND_TASKS = ['myapp.background.WaitTask']

With the app added to settings, run Django’s migrate command:

$ python migrate

We’ll also need a URL route to the task API:
from django.conf.urls import url
from django.urls import include

urlpatterns = [
    url('^', include('task_api.urls'))

Add front-end Java Script

Django Task API includes a JS API for starting and monitoring background tasks. If you’re using Django to manage your static files, then you can include the library using the {% static %} template tag. You can also install the JavaScript library from npm. For purposes of this walk through, let’s create a template with some simple HTML and JavaScript to start and monitor a task:

{% load static %}

<!DOCTYPE html>
<html lang="en">
    <meta charset="UTF-8">
    <title>Task API Example</title>

    <script src="{% static "django-task-api.min.js" %}"></script>
    <script type="text/javascript">
        function startTask() {
  'wait', {'seconds': 10}, function(json) {
                if ( === null || json.progress === null) {
                document.getElementById('status').innerHTML = 'Progress: ' + json.progress + ' / ' +
            }).then(function() {
                document.getElementById('button').disabled = false

            document.getElementById('button').disabled = true
    <style type="text/css">
        .content {
            position: fixed;
            top: 25%;
            left: 50%;
            transform: translate(-50%, -50%);

        .content button {
            margin-top: 5px;
            width: 100px;

        .center {
            text-align: center;
    <div class="content">
        <div id="status">Click "Run" to start the task.</div>
        <div class="center"><button onclick="startTask()" id="button">Run</button></div>

This gives the user a “Run” button, which when clicked, starts the task defined earlier. As the task counts towards its target, the UI updates to show the current progress.

To finish everything out, we need to add a URL route for this template:

from django.conf.urls import url
from django.urls import include
from django.views.generic import TemplateView

url_patterns = [
    # ... other URL patterns
    url('^$', TemplateView.as_view(template_name='example.html'))

If you haven’t already, add your app to your project file:
from django.conf.urls import url
from django.urls import include

urlpatterns = [
    url('^', include('task_api.urls')),
    url('^myapp', include('myapp.urls'))

Try it out

Your new task should be ready to go. Make sure that the Django debug server and Celery worker process are both running, then open the page in your browser. Click “Run” and watch your task progress.



If you run into problems, take a look at the fully-functional example project here.