Check run status
When you store memories, Engram processes them asynchronously through a pipeline. Each request returns a run_id that you can use to track progress.
In most cases, you don't need to poll for completion — memories are eventually consistent and will be available for search once the pipeline finishes. Check the initial response from memories.add to catch immediate errors. Use runs.get only when you need to confirm that a specific run has completed, such as during testing or debugging.
All examples below use a connected client
See Connect to Engram for how to instantiate one.
import os
from engram import EngramClient
client = EngramClient(api_key=os.environ["ENGRAM_API_KEY"])
Poll a run
status = client.runs.wait(run.run_id)
print(status.run_id)
print(status.status)
print(status.committed_operations)
Response
{
"run_id": "run-uuid",
"status": "completed",
"group_id": "group-uuid",
"user_id": "user-uuid",
"starting_step": 1,
"input_type": "string",
"committed_operations": {
"created": [
{
"memory_id": "memory-uuid-1",
"committed_at": "2025-01-01T00:00:01Z"
}
]
},
"created_at": "2025-01-01T00:00:00Z",
"updated_at": "2025-01-01T00:00:01Z"
}
Run statuses
| Status | Meaning |
|---|---|
running | Pipeline is actively processing the content |
in_buffer | Run is paused at a buffer step, waiting for a trigger to continue |
completed | All operations have been committed successfully |
failed | An error occurred during processing |
Committed operations
When a run completes, the committed_operations field tells you exactly what changed:
created— New memories that were added to storage.updated— Existing memories that were modified (e.g. merged or refined).deleted— Memories that were removed (e.g. superseded by an update).
Each entry includes the memory_id and a committed_at timestamp.
Handling failures
If a run fails, the error field contains a description of what went wrong.
{
"run_id": "run-uuid",
"status": "failed",
"group_id": "group-uuid",
"user_id": "user-uuid",
"starting_step": 1,
"input_type": "string",
"error": "extraction failed: invalid input format",
"created_at": "2025-01-01T00:00:00Z",
"updated_at": "2025-01-01T00:00:01Z"
}
Questions and feedback
If you have any questions or feedback, let us know in the user forum.