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
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
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/tasks

List tasks

Example request:

GET /api/tasks HTTP/1.1
Host: localhost:5555
User-Agent: HTTPie/0.8.0

Example response:

HTTP/1.1 200 OK
Content-Length: 1109
Content-Type: application/json; charset=UTF-8
Etag: "b2478118015c8b825f7b88ce6b660e5449746c37"
Server: TornadoServer/3.1.1

{
    "e42ceb2d-8730-47b5-8b4d-8e0d2a1ef7c9": {
        "args": "[3, 4]",
        "client": null,
        "clock": 1079,
        "eta": null,
        "exception": null,
        "exchange": null,
        "expires": null,
        "failed": null,
        "kwargs": "{}",
        "name": "tasks.add",
        "received": 1398505411.107885,
        "result": "'7'",
        "retried": null,
        "retries": 0,
        "revoked": null,
        "routing_key": null,
        "runtime": 0.01610181899741292,
        "sent": null,
        "started": 1398505411.108985,
        "state": "SUCCESS",
        "succeeded": 1398505411.124802,
        "timestamp": 1398505411.124802,
        "traceback": null,
        "uuid": "e42ceb2d-8730-47b5-8b4d-8e0d2a1ef7c9"
    },
    "f67ea225-ae9e-42a8-90b0-5de0b24507e0": {
        "args": "[1, 2]",
        "client": null,
        "clock": 1042,
        "eta": null,
        "exception": null,
        "exchange": null,
        "expires": null,
        "failed": null,
        "kwargs": "{}",
        "name": "tasks.add",
        "received": 1398505395.327208,
        "result": "'3'",
        "retried": null,
        "retries": 0,
        "revoked": null,
        "routing_key": null,
        "runtime": 0.012884548006695695,
        "sent": null,
        "started": 1398505395.3289,
        "state": "SUCCESS",
        "succeeded": 1398505395.341089,
        "timestamp": 1398505395.341089,
        "traceback": null,
        "uuid": "f67ea225-ae9e-42a8-90b0-5de0b24507e0"
    }
}

Query Parameters:  

• limit – maximum number of tasks
• workername – filter task by workername
• taskname – filter tasks by taskname
• state – filter tasks by state

Request Headers:  

• Authorization – optional OAuth token to authenticate

Status Codes:

• 200 – no error
• 401 – unauthorized request

GET /api/task/types

List (seen) task types

Example request:

GET /api/task/types HTTP/1.1
Host: localhost:5555

Example response:

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

{
    "task-types": [
        "tasks.add",
        "tasks.sleep"
    ]
}

Request Headers:  

• Authorization – optional OAuth token to authenticate

Status Codes:

• 200 – no error
• 401 – unauthorized request

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

Get a task info

Example request:

GET /api/task/info/91396550-c228-4111-9da4-9d88cfd5ddc6 HTTP/1.1
Accept: */*
Accept-Encoding: gzip, deflate, compress
Host: localhost:5555

Example response:

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

{
    "args": "[2, 2]",
    "client": null,
    "clock": 25,
    "eta": null,
    "exception": null,
    "exchange": null,
    "expires": null,
    "failed": null,
    "kwargs": "{}",
    "name": "tasks.add",
    "received": 1400806241.970742,
    "result": "'4'",
    "retried": null,
    "retries": null,
    "revoked": null,
    "routing_key": null,
    "runtime": 2.0037889280356467,
    "sent": null,
    "started": 1400806241.972624,
    "state": "SUCCESS",
    "succeeded": 1400806243.975336,
    "task-id": "91396550-c228-4111-9da4-9d88cfd5ddc6",
    "timestamp": 1400806243.975336,
    "traceback": null,
    "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
• options – a dictionary of apply_async keyword 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:  

• 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/revoke/(.+)

Revoke a task

Example request:

POST /api/task/revoke/1480b55c-b8b2-462c-985e-24af3e9158f9?terminate=true
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