---
title: "Pending Actions (Server Jobs)"
section: "Libraries: Python"
route: /pythonpendingactions
account: {accountId}
bruce_api: https://{accountId}.api.nextspace.host
guardian_api: https://guardian.nextspace.host
---
# Pending Actions (Server Jobs)

A Pending Action is the record of a background process running on the server. Endpoints that start long-running work, such as imports, exports and Value Map generation, return one of these instead of making you wait, and it is the handle you use to follow that work to completion.

See [Pending Actions](/apipendingaction) in the API reference for the underlying endpoints.

## Waiting for completion

Rather than polling yourself, hand the ID to `on_completion`. It blocks until the action reaches a terminal state and returns both the final record and every progress message it saw along the way.

```python
import bruce_models as BM

result = BM.PendingAction.on_completion(bruce, action_id)

action = result.get("action")
print(action.get("Status"))
print(action.get("Result"))

for message in result.get("messages"):
    print(message.get("Message"))
```

A failed or cancelled action returns normally rather than raising, because the messages are usually what you need in order to find out why. Check `Status` to tell the outcomes apart.

```python
import bruce_models as BM

result = BM.PendingAction.on_completion(bruce, action_id)
action = result.get("action")

if action.get("Status") == BM.EStatus.COMPLETE:
    print("Done:", action.get("Result"))
elif action.get("Status") == BM.EStatus.FAILED:
    print("Failed. Messages:")
    for message in result.get("messages"):
        print(" ", message.get("Message.Type"), message.get("Message"))
```

You can follow progress as it happens, and give up after a while instead of waiting indefinitely.

```python
import bruce_models as BM

result = BM.PendingAction.on_completion(
    bruce,
    action_id,
    # Seconds between status checks. Defaults to 3.
    interval=5,
    # Raises a TimeoutError once exceeded. Waits indefinitely when omitted.
    timeout=600,
    on_progress=lambda a: print(f"{a.get('Progress')}%"),
    on_message=lambda m: print(m.get("Message"))
)
```

## Reading records directly

The `Result` property is always a dictionary. The API returns it as a string by default, which is usually but not always stringified JSON, so this library requests the parsed form and saves you guessing. A result that was not JSON arrives as `{ "Output": "..." }`.

```python
import bruce_models as BM

# A single record.
action = BM.PendingAction.get(bruce, action_id)
print(action.get("Progress"), action.get("Status"))
print(action.get("Result"))

# Recent records, optionally filtered by status.
actions = BM.PendingAction.get_list(bruce, start_index=0, amount=20).get("Items")
in_progress = BM.PendingAction.get_list(
    bruce,
    status=BM.EStatus.IN_PROGRESS
).get("Items")

# Progress messages, newest first.
messages = BM.PendingAction.get_messages(bruce, action_id, amount=30)

# Ask the server to stop the work.
BM.PendingAction.cancel(bruce, action_id)
```

## Statuses

`BM.EStatus` holds the available statuses, and `BM.EStatus.FINISHED` is the set of terminal ones so you do not have to list them yourself.

```python
import bruce_models as BM

BM.EStatus.IN_PROGRESS
BM.EStatus.COMPLETE
BM.EStatus.FAILED
BM.EStatus.CANCELLED

# Every status other than IN_PROGRESS.
if action.get("Status") in BM.EStatus.FINISHED:
    print("Nothing more to wait for.")

# Message types, useful for hiding debug output from end users.
BM.EMessageType.INFO
BM.EMessageType.STATUS
BM.EMessageType.WARNING
BM.EMessageType.ERROR
```

---

Urls on this page are resolved for account `{accountId}`.
Site index: https://docs.nextspace.host/llms.txt · whole site in one file: https://docs.nextspace.host/llms-full.txt
Human-readable version of this page: https://docs.nextspace.host/pythonpendingactions