API Reference

GET /api/workers

List workers

Example request:

GET /api/workers HTTP/1.1
Host: localhost:5555

Example response:

HTTP/1.1 200 OK
Content-Length: 119
Content-Type: application/json; charset=UTF-8

{
    "celery@worker1": {
        "completed_tasks": 0,
        "concurrency": 4,
        "queues": [
            "celery"
        ],
        "running_tasks": 0,
        "status": true
    },
    "celery@worker2": {
        "completed_tasks": 0,
        "concurrency": 4,
        "queues": [],
        "running_tasks": 0,
        "status": false
    }
}

Request Headers:  

• Authorization – optional OAuth token to authenticate

Status Codes:

• 200 – no error
• 401 – unauthorized request

POST /api/worker/shutdown/(.+)

Shut down a worker

Example request:

POST /api/worker/shutdown/celery@worker2 HTTP/1.1
Content-Length: 0
Host: localhost:5555

Example response:

HTTP/1.1 200 OK
Content-Length: 29
Content-Type: application/json; charset=UTF-8

{
    "message": "Shutting down!"
}

Request Headers:  

• Authorization – optional OAuth token to authenticate

Status Codes:

• 200 – no error
• 401 – unauthorized request
• 404 – unknown worker

POST /api/worker/pool/restart/(.+)

Restart worker’s pool

Example request:

POST /api/worker/pool/restart/celery@worker2 HTTP/1.1
Content-Length: 0
Host: localhost:5555

Example response:

HTTP/1.1 200 OK
Content-Length: 56
Content-Type: application/json; charset=UTF-8

{
    "message": "Restarting 'celery@worker2' worker's pool"
}

Request Headers:  

• Authorization – optional OAuth token to authenticate

Status Codes:

• 200 – no error
• 401 – unauthorized request
• 403 – pool restart is not enabled (see CELERYD_POOL_RESTARTS)
• 404 – unknown worker

POST /api/worker/pool/grow/(.+)

Grow worker’s pool

Example request:

POST /api/worker/pool/grow/celery@worker2?n=3 HTTP/1.1
Content-Length: 0
Host: localhost:5555

Example response:

HTTP/1.1 200 OK
Content-Length: 58
Content-Type: application/json; charset=UTF-8

{
    "message": "Growing 'celery@worker2' worker's pool by 3"
}

Query Parameters:  

• n – number of pool processes to grow, default is 1

Request Headers:  

• Authorization – optional OAuth token to authenticate

Status Codes:

• 200 – no error
• 401 – unauthorized request
• 403 – failed to grow
• 404 – unknown worker

POST /api/worker/pool/shrink/(.+)

Shrink worker’s pool

Example request:

POST /api/worker/pool/shrink/celery@worker2 HTTP/1.1
Content-Length: 0
Host: localhost:5555

Example response:

HTTP/1.1 200 OK
Content-Length: 60
Content-Type: application/json; charset=UTF-8

{
    "message": "Shrinking 'celery@worker2' worker's pool by 1"
}

Query Parameters:  

• n – number of pool processes to shrink, default is 1

Request Headers:  

• Authorization – optional OAuth token to authenticate

Status Codes:

• 200 – no error
• 401 – unauthorized request
• 403 – failed to shrink
• 404 – unknown worker

POST /api/worker/pool/autoscale/(.+)

Autoscale worker pool

Example request:

POST /api/worker/pool/autoscale/celery@worker2?min=3&max=10 HTTP/1.1
Content-Length: 0
Content-Type: application/x-www-form-urlencoded; charset=utf-8
Host: localhost:5555

Example response:

HTTP/1.1 200 OK
Content-Length: 66
Content-Type: application/json; charset=UTF-8

{
    "message": "Autoscaling 'celery@worker2' worker (min=3, max=10)"
}

Query Parameters:  

• min – minimum number of pool processes
• max – maximum number of pool processes

Request Headers:  

• Authorization – optional OAuth token to authenticate

Status Codes:

• 200 – no error
• 401 – unauthorized request
• 403 – autoscaling is not enabled (see CELERYD_AUTOSCALER)
• 404 – unknown worker

POST /api/worker/queue/add-consumer/(.+)

Start consuming from a queue

Example request:

POST /api/worker/queue/add-consumer/celery@worker2?queue=sample-queue HTTP/1.1
Content-Length: 0
Content-Type: application/x-www-form-urlencoded; charset=utf-8
Host: localhost:5555

Example response:

HTTP/1.1 200 OK
Content-Length: 40
Content-Type: application/json; charset=UTF-8

{
    "message": "add consumer sample-queue"
}

Query Parameters:  

• queue – the name of a new queue

Request Headers:  

• Authorization – optional OAuth token to authenticate

Status Codes:

• 200 – no error
• 401 – unauthorized request
• 403 – failed to add consumer
• 404 – unknown worker

POST /api/worker/queue/cancel-consumer/(.+)

Stop consuming from a queue

Example request:

POST /api/worker/queue/cancel-consumer/celery@worker2?queue=sample-queue HTTP/1.1
Content-Length: 0
Content-Type: application/x-www-form-urlencoded; charset=utf-8
Host: localhost:5555

Example response:

HTTP/1.1 200 OK
Content-Length: 52
Content-Type: application/json; charset=UTF-8

{
    "message": "no longer consuming from sample-queue"
}

Query Parameters:  

• queue – the name of queue

Request Headers:  

• Authorization – optional OAuth token to authenticate

Status Codes:

• 200 – no error
• 401 – unauthorized request
• 403 – failed to cancel consumer
• 404 – unknown worker

GET /api/task/info/(.*)

Get a task info

Example request:

GET /api/task/info/c60be250-fe52-48df-befb-ac66174076e6 HTTP/1.1
Accept: */*
Accept-Encoding: gzip, deflate, compress
Host: localhost:5555

Example response:

HTTP/1.1 200 OK
Content-Length: 171
Content-Type: application/json; charset=UTF-8

{
    "args": "[1, 2]",
    "kwargs": "{}",
    "name": "tasks.add",
    "result": "'3'",
    "state": "SUCCESS",
    "task-id": "c60be250-fe52-48df-befb-ac66174076e6",
    "worker": "celery@worker1"
}

Request Headers:  

• Authorization – optional OAuth token to authenticate

Status Codes:

• 200 – no error
• 401 – unauthorized request
• 404 – unknown task

POST /api/task/async-apply/(.+)

Execute a task

Example request:

POST /api/task/async-apply/tasks.add HTTP/1.1
Accept: application/json
Accept-Encoding: gzip, deflate, compress
Content-Length: 16
Content-Type: application/json; charset=utf-8
Host: localhost:5555

{
    "args": [1, 2]
}

Example response:

HTTP/1.1 200 OK
Content-Length: 71
Content-Type: application/json; charset=UTF-8
Date: Sun, 13 Apr 2014 15:55:00 GMT

{
    "state": "PENDING",
    "task-id": "abc300c7-2922-4069-97b6-a635cc2ac47c"
}

Query Parameters:  

• args – a list of arguments
• kwargs – a dictionary of arguments

Request Headers:  

• Authorization – optional OAuth token to authenticate

Status Codes:

• 200 – no error
• 401 – unauthorized request
• 404 – unknown task

POST /api/task/send-task/(.+)

Execute a task by name (doesn’t require task sources)

Example request:

POST /api/task/send-task/tasks.add HTTP/1.1
Accept: application/json
Accept-Encoding: gzip, deflate, compress
Content-Length: 16
Content-Type: application/json; charset=utf-8
Host: localhost:5555

{
    "args": [1, 2]
}

Example response:

HTTP/1.1 200 OK
Content-Length: 71
Content-Type: application/json; charset=UTF-8

{
    "state": "SUCCESS",
    "task-id": "c60be250-fe52-48df-befb-ac66174076e6"
}

Query Parameters:  

• args – a list of arguments
• kwargs – a dictionary of arguments

Request Headers:  

• Authorization – optional OAuth token to authenticate

Status Codes:

• 200 – no error
• 401 – unauthorized request
• 404 – unknown task

GET /api/task/result/(.+)

Get a task result

Example request:

GET /api/task/result/c60be250-fe52-48df-befb-ac66174076e6 HTTP/1.1
Host: localhost:5555

Example response:

HTTP/1.1 200 OK
Content-Length: 84
Content-Type: application/json; charset=UTF-8

{
    "result": 3,
    "state": "SUCCESS",
    "task-id": "c60be250-fe52-48df-befb-ac66174076e6"
}

Request Headers:  

• Authorization – optional OAuth token to authenticate

Status Codes:

• 200 – no error
• 401 – unauthorized request
• 503 – result backend is not configured

POST /api/task/timeout/(.+)

Change soft and hard time limits for a task

Example request:

POST /api/task/timeout/tasks.sleep HTTP/1.1
Content-Length: 44
Content-Type: application/x-www-form-urlencoded; charset=utf-8
Host: localhost:5555

soft=30&hard=100&workername=celery%40worker1

Example response:

HTTP/1.1 200 OK
Content-Length: 46
Content-Type: application/json; charset=UTF-8

{
    "message": "new rate limit set successfully"
}

Query Parameters:  

• workername – worker name

Request Headers:  

• Authorization – optional OAuth token to authenticate

Status Codes:

• 200 – no error
• 401 – unauthorized request
• 404 – unknown task/worker

POST /api/task/rate-limit/(.+)

Change rate limit for a task

Example request:

POST /api/task/rate-limit/tasks.sleep HTTP/1.1
Content-Length: 41
Content-Type: application/x-www-form-urlencoded; charset=utf-8
Host: localhost:5555

ratelimit=200&workername=celery%40worker1

Example response:

HTTP/1.1 200 OK
Content-Length: 61
Content-Type: application/json; charset=UTF-8

{
    "message": "Revoked '1480b55c-b8b2-462c-985e-24af3e9158f9'"
}

Query Parameters:  

• terminate – terminate the task if it is running

Request Headers:  

• Authorization – optional OAuth token to authenticate

Status Codes:

• 200 – no error
• 401 – unauthorized request
• 404 – unknown task/worker

POST /api/task/revoke/(.+)

Revoke a task

Example request:

POST /api/task/revoke/1480b55c-b8b2-462c-985e-24af3e9158f9?terminate=true HTTP/1.1
Content-Length: 0
Content-Type: application/x-www-form-urlencoded; charset=utf-8
Host: localhost:5555

Example response:

HTTP/1.1 200 OK
Content-Length: 61
Content-Type: application/json; charset=UTF-8

{
    "message": "Revoked '1480b55c-b8b2-462c-985e-24af3e9158f9'"
}

Query Parameters:  

• terminate – terminate the task if it is running

Request Headers:  

• Authorization – optional OAuth token to authenticate

Status Codes:

• 200 – no error
• 401 – unauthorized request