Tasks

Many operations (index creation, document ingestion, settings updates) are processed asynchronously. These operations return a taskUid you can poll to track progress. Reading tasks needs an admin key.

Task UIDs are numbered per engine, not per project, so tell Headband which index the task belongs to: ?index=<uid> on a single task, or ?indexUids=<uid> on the list. When every index in the project runs on one engine, Headband can find it without them, but passing the index always works.

GET/v1/tasks?indexUids=products

List recent tasks on the engine behind the named indexes.

Auth admin key onlyReturns 200
Response
{
  "results": [
    {
      "uid": 1,
      "indexUid": "products",
      "status": "succeeded",
      "type": "indexCreation",
      "enqueuedAt": "2025-01-15T08:30:00Z",
      "startedAt": "2025-01-15T08:30:01Z",
      "finishedAt": "2025-01-15T08:30:01Z"
    },
    {
      "uid": 2,
      "indexUid": "products",
      "status": "processing",
      "type": "documentAdditionOrUpdate",
      "enqueuedAt": "2025-01-15T09:00:00Z",
      "startedAt": "2025-01-15T09:00:01Z"
    }
  ]
}
ParameterTypeDefaultDescription
limitnumber20Number of tasks to return.
fromnumber--Task UID to start from (for pagination).
statusesstring--Comma-separated list of statuses to filter (e.g. "succeeded,failed").
typesstring--Comma-separated list of task types to filter.
indexUidsstring--Comma-separated list of index UIDs to filter. Recommended: it also picks the engine to ask.
GET/v1/tasks/:taskUid?index=products

Get the status and details of a single task. Pass the index the write went to.

Task statuses: enqueued, processing, succeeded, failed.

Auth admin key onlyReturns 200
Response
{
  "uid": 2,
  "indexUid": "products",
  "status": "succeeded",
  "type": "documentAdditionOrUpdate",
  "details": {
    "receivedDocuments": 1500,
    "indexedDocuments": 1500
  },
  "enqueuedAt": "2025-01-15T09:00:00Z",
  "startedAt": "2025-01-15T09:00:01Z",
  "finishedAt": "2025-01-15T09:00:03Z"
}