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: 1526
Content-Type: application/json; charset=UTF-8
Date: Tue, 28 Jul 2015 01:32:38 GMT
Etag: "fcdd75d85a82b4052275e28871d199aac1ece21c"
Server: TornadoServer/4.0.2

{
    "celery@worker1": {
        "active_queues": [
            {
                "alias": null,
                "auto_delete": false,
                "binding_arguments": null,
                "bindings": [],
                "durable": true,
                "exchange": {
                    "arguments": null,
                    "auto_delete": false,
                    "delivery_mode": 2,
                    "durable": true,
                    "name": "celery",
                    "passive": false,
                    "type": "direct"
                },
                "exclusive": false,
                "name": "celery",
                "no_ack": false,
                "queue_arguments": null,
                "routing_key": "celery"
            }
        ],
        "conf": {
            "CELERYBEAT_SCHEDULE": {},
            "CELERY_INCLUDE": [
                "celery.app.builtins",
                "__main__"
            ],
            "CELERY_SEND_TASK_SENT_EVENT": true,
            "CELERY_TIMEZONE": "UTC"
        },
        "registered": [
            "tasks.add",
            "tasks.echo",
            "tasks.error",
            "tasks.retry",
            "tasks.sleep"
        ],
        "stats": {
            "broker": {
                "alternates": [],
                "connect_timeout": 4,
                "heartbeat": null,
                "hostname": "127.0.0.1",
                "insist": false,
                "login_method": "AMQPLAIN",
                "port": 5672,
                "ssl": false,
                "transport": "amqp",
                "transport_options": {},
                "uri_prefix": null,
                "userid": "guest",
                "virtual_host": "/"
            },
            "clock": "918",
            "pid": 90494,
            "pool": {
                "max-concurrency": 4,
                "max-tasks-per-child": "N/A",
                "processes": [
                    90499,
                    90500,
                    90501,
                    90502
                ],
                "put-guarded-by-semaphore": false,
                "timeouts": [
                    0,
                    0
                ],
                "writes": {
                    "all": "100.00%",
                    "avg": "100.00%",
                    "inqueues": {
                        "active": 0,
                        "total": 4
                    },
                    "raw": "1",
                    "total": 1
                }
            },
            "prefetch_count": 16,
            "rusage": {
                "idrss": 0,
                "inblock": 211,
                "isrss": 0,
                "ixrss": 0,
                "majflt": 6,
                "maxrss": 26996736,
                "minflt": 11450,
                "msgrcv": 4968,
                "msgsnd": 1227,
                "nivcsw": 1367,
                "nsignals": 0,
                "nswap": 0,
                "nvcsw": 1855,
                "oublock": 93,
                "stime": 0.414564,
                "utime": 0.975726
            },
            "total": {
                "tasks.add": 1
            }
        },
        "timestamp": 1438049312.073402
    }
}

Query Parameters

• refresh – run inspect to get updated list of workers

• workername – get info for workername

• status – only get worker status info

Request Headers

• Authorization – optional OAuth token to authenticate

Status Codes

• 200 OK – no error

• 401 Unauthorized – 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 OK – no error

• 401 Unauthorized – unauthorized request

• 404 Not Found – 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 OK – no error

• 401 Unauthorized – unauthorized request

• 403 Forbidden – pool restart is not enabled (see CELERYD_POOL_RESTARTS)

• 404 Not Found – 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 OK – no error

• 401 Unauthorized – unauthorized request

• 403 Forbidden – failed to grow

• 404 Not Found – 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 OK – no error

• 401 Unauthorized – unauthorized request

• 403 Forbidden – failed to shrink

• 404 Not Found – 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 OK – no error

• 401 Unauthorized – unauthorized request

• 403 Forbidden – autoscaling is not enabled (see CELERYD_AUTOSCALER)

• 404 Not Found – 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 OK – no error

• 401 Unauthorized – unauthorized request

• 403 Forbidden – failed to add consumer

• 404 Not Found – 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 OK – no error

• 401 Unauthorized – unauthorized request

• 403 Forbidden – failed to cancel consumer

• 404 Not Found – 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",
        "worker": "celery@worker1"
    },
    "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",
        "worker": "celery@worker1"
    }
}

Query Parameters

• limit – maximum number of tasks

• offset – skip first n tasks

• sort_by – sort tasks by attribute (name, state, received, started)

• workername – filter task by workername

• taskname – filter tasks by taskname

• state – filter tasks by state

• received_start – filter tasks by received date (must be greater than) format %Y-%m-%d %H:%M

• received_end – filter tasks by received date (must be less than) format %Y-%m-%d %H:%M

Request Headers

• Authorization – optional OAuth token to authenticate

Status Codes

• 200 OK – no error

• 401 Unauthorized – 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 OK – no error

• 401 Unauthorized – unauthorized request

GET /api/queues/length

Return length of all active queues

Example request:

GET /api/queues/length
Host: localhost:5555

Example response:

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

{
    "active_queues": [
        {"name": "celery", "messages": 0},
        {"name": "video-queue", "messages": 5}
    ]
}

Request Headers

• Authorization – optional OAuth token to authenticate

Status Codes

• 200 OK – no error

• 401 Unauthorized – unauthorized request

• 503 Service Unavailable – result backend is not configured

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 OK – no error

• 401 Unauthorized – unauthorized request

• 404 Not Found – unknown task

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

Execute a task by name and wait results

Example request:

POST /api/task/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

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

Query Parameters

• args – a list of arguments

• kwargs – a dictionary of arguments

Request Headers

• Authorization – optional OAuth token to authenticate

Status Codes

• 200 OK – no error

• 401 Unauthorized – unauthorized request

• 404 Not Found – 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 OK – no error

• 401 Unauthorized – unauthorized request

• 404 Not Found – 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 OK – no error

• 401 Unauthorized – unauthorized request

• 404 Not Found – 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"
}

Query Parameters

• timeout – how long to wait, in seconds, before the operation times out

Request Headers

• Authorization – optional OAuth token to authenticate

Status Codes

• 200 OK – no error

• 401 Unauthorized – unauthorized request

• 503 Service Unavailable – result backend is not configured

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

Abort a running task

Example request:

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

Example response:

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

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

Request Headers

• Authorization – optional OAuth token to authenticate

Status Codes

• 200 OK – no error

• 401 Unauthorized – unauthorized request

• 503 Service Unavailable – 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": "time limits set successfully"
}

Query Parameters

• workername – worker name

Request Headers

• Authorization – optional OAuth token to authenticate

Status Codes

• 200 OK – no error

• 401 Unauthorized – unauthorized request

• 404 Not Found – 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": "new rate limit set successfully"
}

Query Parameters

• workername – worker name

Request Headers

• Authorization – optional OAuth token to authenticate

Status Codes

• 200 OK – no error

• 401 Unauthorized – unauthorized request

• 404 Not Found – 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

• signal – name of signal to send to process if terminate (default: ‘SIGTERM’)

Request Headers

• Authorization – optional OAuth token to authenticate

Status Codes

• 200 OK – no error

• 401 Unauthorized – unauthorized request