1. Description

The Task API allows users to monitor the status of Ingest Tasks running against an index.

An Ingest Task represents a request to add data to an index which was successfully submitted to Globus Search but might not have been completed yet.

To read about how to submit Ingest Tasks, go to the Ingest API page

2. Task Documents

A Task document has a Task ID which uniquely identifies the task, an Index ID for the index to which the Task applies, a State, which describes which stage of processing the task is in, and informational details.

For example,

{
  "state_description": "Task succeeded",
  "task_id": "05c1ec1b-2400-44e2-9797-922c29199042",
  "state": "SUCCESS",
  "creation_date": "2018-12-13T18:08:42.746911",
  "completion_date": "2018-12-13T18:08:44.539611",
  "additional_details": null,
  "message": null,
  "index_id": "696af25c-8c24-469a-b5e0-67d3e4b71df7"
}

describes a task in the SUCCESS state.

The valid task states are

PENDING

The task hasn’t started yet, it is waiting in the queue

PROGRESS

The task has started, but has not yet completed. Search queries may retrieve some of the contents which have been processed

SUCCESS

The task completed without errors or with only temporary errors which resolved

FAILED

The task failed to complete. Partial data may have been processed

3. API Methods

The Task APIs require that your user have permissions to write data to the index for the tasks which you query.

If you request information about a Task for an index for which you do not have write permissions, you will receive a HTTP 403 Forbidden.

3.1. Get Task

The Task API provides a method for getting a specific task by ID

URL

/v1/task/<task_id>

Method

GET

HTTP Headers

Authorization: Bearer <Globus Auth token with scope urn:globus:scopes:search.api.globus.org:ingest or stronger>

Response Body

a Task document

3.1.1. Examples

  • with an ID of 05c1ec1b-2400-44e2-9797-922c29199042

curl 'https://search.api.globus.org/v1/task/05c1ec1b-2400-44e2-9797-922c29199042'

3.2. List Tasks

You can list up to the last 1000 tasks submitted against an index.

URL

/v1/task_list/<index_id>

Method

GET

HTTP Headers

Authorization: Bearer <Globus Auth token with scope urn:globus:scopes:search.api.globus.org:ingest or stronger>

Response Body

a Task List document

A Task List response has two fields: index_id and tasks. index_id is the same as the one used to call this API. tasks is a list of Task Documents.

For example:

{
  "index_id": "696af25c-8c24-469a-b5e0-67d3e4b71df7",
  "tasks": [
    {
      "state_description": "Task succeeded",
      "task_id": "05c1ec1b-2400-44e2-9797-922c29199042",
      "state": "SUCCESS",
      "creation_date": "2018-12-13T18:08:42.746911",
      "completion_date": "2018-12-13T18:08:44.539611",
      "additional_details": null,
      "message": null,
      "index_id": "696af25c-8c24-469a-b5e0-67d3e4b71df7"
    }
  ]
}

3.2.1. Examples

  • for an index with an ID of 696af25c-8c24-469a-b5e0-67d3e4b71df7

curl 'https://search.api.globus.org/v1/task_list/696af25c-8c24-469a-b5e0-67d3e4b71df7'

© 2010- The University of Chicago Legal