Operations API — track and manage async tasks

Operations are background tasks that Hindsight executes asynchronously. They are created when you retain content with async: true, upload files, or create mental models. Each operation has a lifecycle from pending through processing to a terminal state. You can poll operation status, cancel pending operations, and retry failed ones. By default, all background operations execute in-process within the API service.

Operation types

Operation	Trigger	Description
`batch_retain`	`retain` with `async: true`	Processes content batches in the background
`file_retain`	File upload	Converts and ingests uploaded files
`consolidate`	After `retain`	Consolidates new facts into observations
`mental_model`	`create_mental_model` or `refresh_mental_model`	Generates or refreshes a mental model

Operation status values

Status	Description
`pending`	Operation is queued and waiting to be picked up
`processing`	Operation is actively being processed by a worker
`completed`	Operation finished successfully
`failed`	Operation failed — check `error_message` for details
`cancelled`	Operation was cancelled before processing began

List operations

GET /v1/{tenant}/banks/{bank_id}/operations

Returns all operations for the specified bank, ordered by creation time (most recent first).

Query parameters

status

string

Filter by operation status: pending, processing, completed, failed, cancelled.

limit

integer

default:"100"

Maximum number of operations to return.

offset

integer

default:"0"

Pagination offset.

Response fields

bank_id

string

required

The memory bank these operations belong to.

operations

object[]

required

List of operations.

Show operation fields

string

required

Unique operation ID.

task_type

string

required

The type of operation: retain, file_retain, consolidate, or mental_model.

status

string

required

Current status: pending, processing, completed, failed, or cancelled.

items_count

integer

Number of content items processed (for retain operations).

document_id

string

The document ID associated with this operation, if applicable.

error_message

string

Error details when status is "failed". null otherwise.

created_at

string

required

ISO 8601 timestamp of when the operation was created.

completed_at

string

ISO 8601 timestamp of when the operation finished. null if still in progress.

Example

curl "https://your-hindsight-host/v1/default/banks/my-bank/operations" \
  -H "Authorization: Bearer $HINDSIGHT_API_KEY"

Get an operation

GET /v1/{tenant}/banks/{bank_id}/operations/{operation_id}

Returns the current status and details for a single operation.

Example

curl "https://your-hindsight-host/v1/default/banks/my-bank/operations/550e8400-e29b-41d4-a716-446655440000" \
  -H "Authorization: Bearer $HINDSIGHT_API_KEY"

Cancel an operation

DELETE /v1/{tenant}/banks/{bank_id}/operations/{operation_id}

Cancels a pending operation before it starts processing. Has no effect on operations that are already processing, completed, or failed.

Example

curl -X DELETE "https://your-hindsight-host/v1/default/banks/my-bank/operations/550e8400-e29b-41d4-a716-446655440000" \
  -H "Authorization: Bearer $HINDSIGHT_API_KEY"

Retry a failed operation

POST /v1/{tenant}/banks/{bank_id}/operations/{operation_id}/retry

Re-queues a failed or cancelled operation for execution. The operation status resets to pending and the worker picks it up again. Returns 409 if the operation is not in a retriable state.

Response fields

success

boolean

required

Whether the retry was successfully queued.

message

string

required

Human-readable confirmation message.

operation_id

string

required

The operation ID that was re-queued.

Example

curl -X POST "https://your-hindsight-host/v1/default/banks/my-bank/operations/550e8400-e29b-41d4-a716-446655440000/retry" \
  -H "Authorization: Bearer $HINDSIGHT_API_KEY"

Polling pattern

The recommended pattern for async retain is to submit the request, capture the operation ID, and poll until the operation reaches a terminal state.

import time
from hindsight_client import Hindsight

client = Hindsight(base_url="https://your-hindsight-host", api_key="...")

# Submit async retain
response = client.retain_batch(
    bank_id="my-bank",
    items=[{"content": "Large amount of content to process..."}],
    retain_async=True,
)
operation_id = response.operation_id

# Poll for completion
while True:
    op = await client.operations.get_operation_status("my-bank", operation_id)
    if op.status in ("completed", "failed", "cancelled"):
        break
    time.sleep(2)

if op.status == "completed":
    print("Processing complete")
elif op.status == "failed":
    print(f"Processing failed: {op.error_message}")

Error codes

Status	Code	Description
`400`	`invalid_request`	Malformed request.
`401`	`unauthorized`	Missing or invalid API key.
`404`	`operation_not_found`	The specified operation does not exist.
`409`	`invalid_state`	Operation is not in a retriable state (retry endpoint).
`500`	`internal_error`	Server error.

Core Methods

Resources

Operations API — track and manage async tasks

Operation types

Operation status values

List operations

Query parameters

Response fields

Example

Get an operation

Example

Cancel an operation

Example

Retry a failed operation

Response fields

Example

Polling pattern

Error codes

Build docs developers (and LLMs) love

Core Methods

Resources

Documentation Index

​Operation types

​Operation status values

​List operations

​Query parameters

​Response fields

​Example

​Get an operation

​Example

​Cancel an operation

​Example

​Retry a failed operation

​Response fields

​Example

​Polling pattern

​Error codes

Build docs developers (and LLMs) love

Operation types

Operation status values

List operations

Query parameters

Response fields

Example

Get an operation

Example

Cancel an operation

Example

Retry a failed operation

Response fields

Example

Polling pattern

Error codes