> ## Documentation Index
> Fetch the complete documentation index at: https://docs.goliathdata.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Bulk Tasks API

> Poll the status of long-running bulk jobs through the Goliath developer API

## About

Some operations don't finish inline — they kick off async work and return a
`bulkTaskId` before the change is applied (for example, `addPropertiesToList`
on the [Properties API](/developer-api/properties)). Poll that
`bulkTaskId` here to watch the job move from queued to done.

`getBulkTask` returns the task status, progress, and a best-effort ETA — it's
built for polling on a short interval. All operations go through the developer
API gateway — one endpoint, called by `operationId`. If you haven't set up a
key yet, start with the
[Developer API Overview](/developer-api/overview).

## Operations

### Reading bulk-task status (`READ` scope)

| operationId   | Scope  | What it does                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
| ------------- | ------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `getBulkTask` | `READ` | Fetch the current status of an async bulk task by id (the `bulkTaskId` returned by async ops such as `addPropertiesToList`). Returns the status (`CREATED` = queued, `PROCESSING` = being applied, `COMPLETED`, `FAILED`), progress (`processedItemCount` of `estimatedItemCount`), and a best-effort ETA (`secondsRemaining`; `null` means no estimate, not an error — status is authoritative). A `FAILED` status means the change was **not** applied. Returns `null` for ids that don't exist in your workspace. Poll on a 3-5 second interval. |

<Note>
  **Organization guard**

  The `bulkTaskId` is scoped to your organization. Passing a foreign or unknown
  id resolves to `null` rather than leaking another workspace's task — so a task
  you don't own is indistinguishable from one that never existed. See
  [Authorization](/developer-api/authorization) for the model.
</Note>

## Example

Poll a bulk task returned by an async operation:

```bash theme={null}
curl -X POST https://server.goliathdata.com/api/v1/call \
  -H "Authorization: Bearer gsk_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "operationId": "getBulkTask", "variables": { "bulkTaskId": "YOUR_BULK_TASK_ID" } }'
```

Full variable schemas, response shapes, and worked examples for every
operation are available from the
[discovery endpoint](/developer-api/overview#discovering-operations).