# Task Queue REST API Reference <span class="exp-feat">Experimental!</span> - Google App Engine - Google Code

English ▼
Skip to page content Skip to main navigation
e.g. "templates" or "datastore"

# Task Queue REST API Reference Experimental!

The following table summarizes the REST methods exposed by the Google Task Queue API.

Resource | Method | REST URI relative to https://www.googleapis.com/taskqueue/v1beta1
--- | --- | ---
TaskQueue | Get | `GET .../projects/projectname/taskqueues/queuename`
Task | List | `GET .../projects/projectname/taskqueues/queuename/tasks`
Get | `GET .../projects/projectname/taskqueues/queuename/tasks/taskname`
Delete | `DELETE .../projects/projectname/taskqueues/queuename/tasks/taskname`
Lease | `POST .../projects/projectname/taskqueues/queuename/lease`

## TaskQueue Resource

A TaskQueue resource represents a queue created by an App Engine application. You create TaskQueue resources within a project namespace defined by your App Engine App ID. You can use the TaskQueue resource to get information about a queue. By default, a user has no rights on a TaskQueue unless they are explicitly granted rights in `queues.yaml`.

Each project can hold an unlimited number of TaskQueue resources. It is currently not possible to create, modify, or delete queues using the REST API.

- TaskQueue Resource Description
- TaskQueue Methods

### TaskQueue Resource Description

#### JSON

    {
      "kind": "taskqueues#taskqueue",
      "id": string,
      "maxLeases": number,
      "stats": {
        "totalTasks": number,
        "oldestTask": number,
        "leasedLastMinute": number,
        "leasedLastHour": number
      }
    }

Property Name | Value | Description | Mutable
--- | --- | --- | ---
`kind` | `string` | Identifies the resource type. | No
`id` | `string` | The name of the task queue. This name must be unique among all queue names within this project. See the naming restrictions. | Required and mutable on insert only
`maxLeases` | `number` | The number of times a client can lease a specific task before it will be automatically dropped from the queue. If not specified, all tasks will be available for indefinite retries. In practice, you should set this value to a reasonably small value so that a difficult task does not block the whole queue. | Yes
`stats` | `object` | An object that holds statistics for this queue. | No
`stats.``totalTasks` | `number` | The total number of tasks in the queue. | No
`stats.``oldestTask` | `number` | The timestamp of the oldest task in the queue, in seconds since the epoch. | No
`stats.``leasedLastMinute` | `number` | The number of tasks leased in the last minute. | No
`stats.``leasedLastHour` | `number` | The number of tasks leased in the last hour. | No

### TaskQueue Collection Methods

#### Get TaskQueue

Returns information about a specified TaskQueue resource.

Authentication is required.

Request (REST)

    GET
    https://www.googleapis.com/taskqueue/v1beta1/projects/{PROJECT_NAME}/taskqueues/{TASKQUEUE_NAME}?{QUERY_PARAMS}

Query Parameters:

Name | Type | Description | Required
--- | --- | --- | ---
getStats | boolean | Whether to populate the stats field of the returned resource. Default value is false. | False

Response

Returns a TaskQueue resource.

## Task Resource

A Task resource represents a single task to be handled by a client. A task is defined by an arbitrary blob of data that should be understood by the client.

The standard usage is that a client calls TaskQueue.lease to get the next available task, performs that task, and then calls TaskQueue.delete on that task before the lease expires. If the client cannot finish the task before the lease expires, and has a reasonable chance of completing the task, it should call TaskQueue.lease again before the lease expires. If the client completes the task after the lease has expired, it still needs to delete the task. Tasks should be designed to be idempotent to avoid errors if multiple clients complete the same task.

- Task Resource Description
- Task Resource Methods

### Task Resource Description

#### JSON

    {
      "kind": "taskqueues#task",
      "id": string,
      "queueName": string,
      "payloadBase64": string,
      "enqueueTimestamp": number,
      "leaseTimestamp": number
    }

Property Name | Value | Description | Mutable
--- | --- | --- | ---
`kind` | `string` | The type of resource. | No
`id` | `string` | The name of the task, which can be specified when inserting the task from App Engine. If not specified, a random name will be generated. We strongly recommend against specifying a task name yourself. | Optional, used on insert only
`queueName` | `string` | Name of the TaskQueue that holds this task. | No
`payloadBase64` | `string` | The bytes describing the task to perform. This is a base64-encoded string. The client is expected to understand the payload format. The maximum size is 1MB. This value will be empty in calls to Tasks.list. | No
`enqueueTimestamp` | `number` | The time when the task was enqueued, in seconds since the epoch. | No
`leaseTimestamp` | `number` | The time at which the task lease will expire, in seconds since the epoch. If this task has never been leased, it will be zero. If this this task has been previously leased and the lease has expired, this value will be < Now(). | No

### Task Collection Methods

- List Tasks
- Get Task
- Delete Task
- Lease Task

#### List Tasks

Lists all undeleted Tasks in a TaskQueue, whether or not they are currently leased, up to a maximum of 100. The retrieved tasks will not include the task payload. Deleted tasks take up to three days to appear in this list, and the names of these tasks are unavailable until they appear here. Tasks are returned in the same order they are stored on the queue.

Authentication is required.

Request (REST)

    GET
    https://www.googleapis.com/taskqueue/v1beta1/projects/{PROJECT_NAME}/taskqueues/{TASKQUEUE_NAME}/tasks

Response (JSON)

An array of tasks, as shown here:

    {
      "kind": "taskqueues#tasks",
      "items": [
        Task resource array
      ]
    }

#### Get Task

Gets the named task in a TaskQueue. This does not lease the task. You shouldn't need to call this method in your typical work flow.

Authentication is required.

Request (REST)

    GET
    https://www.googleapis.com/taskqueue/v1beta1/projects/{PROJECT_NAME}/taskqueues/{TASKQUEUE_NAME}/tasks/{TASK_NAME}

Response

The requested Task resource.

#### Delete Task

Deletes a task from a TaskQueue. You should only call this method if you own the lease for a task and have completed it, unless you have some other compelling reason to remove a task from the queue.

Authentication is required.

Request (REST)

    DELETE
    https://www.googleapis.com/taskqueue/v1beta1/projects/{PROJECT_NAME}/taskqueues/{TASKQUEUE_NAME}/tasks/{TASK_NAME}

Response

An HTTP 200 response if successful, or an HTTP error code on failure.

#### Lease Task

Acquires a lease on the topmost N unowned tasks in the specified queue.

Authentication is required.

Request (REST)

    POST
    https://www.googleapis.com/taskqueue/v1beta1/projects/{PROJECT_NAME}/taskqueues/{TASKQUEUE_NAME}/tasks/lease?{QUERY_PARAMS}

Query Parameters:

Name | Type | Description | Required
--- | --- | --- | ---
leaseSecs | integer | How long to lease this task, in seconds. | True
numTasks | integer | How many tasks to lease. | True

Response

An array of leased Task resources, as shown here:

    {
      "kind": "taskqueues#tasks",
      "items": [
        Task resource array
      ]
    }