API Reference — Flower 1.0.1 documentation

# 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

    - 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