Tasks

Indexes and documents

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.

List tasks

GET/v1/tasks?indexUids=products

List recent tasks on the engine behind the named indexes.

Auth
admin key only
Returns
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
limit · numbernumber20Number of tasks to return.
from · numbernumber–Task UID to start from (for pagination).
statuses · stringstring–Comma-separated list of statuses to filter (e.g. "succeeded,failed").
types · stringstring–Comma-separated list of task types to filter.
indexUids · stringstring–Comma-separated list of index UIDs to filter. Recommended: it also picks the engine to ask.

Name the index

Task UIDs are numbered per engine, not per project. Pass ?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 task

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 only
Returns
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"
}