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

Pending Action records is how we track job progress and results. Most actions will return a Pending Action ID that you can use to check the status of the job. As a result, it's important to understand how to use the Pending Action API.

## Data model

Below is the data model for a Pending Action record. These records are one of our oldest and don't have a tidied up v3 variant yet.

When checking for completion, you can see if the `.Status` stops equaling `IN_PROGRESS`.

The `Result` property is the primary candidate for a v3 overhaul where it returns a stringified JSON object you have to parse yourself.
This is the result of us migrating from a singular result line to a more complex result object. Some of our oldest jobs may return a non-JSON string in this field.

```typescript
/**
 * Available Pending Action statuses.
 */
export enum EStatus {
    InProgress = "IN_PROGRESS",
    Cancelled = "CANCELLED",
    Complete = "COMPLETE",
    Failed = "FAILED"
}

/**
 * The Pending Action record itself.
 */
interface IAction {
    // ID of the Pending Action record.
    ID: number;
    // ID of the application that created the Pending Action.
    "CreatedBy.Application": string;
    // ID of the user that created the pending action.
    "CreatedByUser.ID": string;
    // Result string is a stringified JSON object.
    // This is not always the case so please check the data before parsing it.
    Result: string;
    // Progress % of the pending action.
    Progress: number;
    // Description on why the Pending Action was started.
    Description: string;
    // Status of the Pending Action.
    Status: EStatus;
    // Created/updated/completed date/time in ISO 8601 UTC.
    Created: string;
    Updated?: string;
    Completed?: string;
}
```

## Request the record

We recommend requesting the Pending Action record every 5 seconds until it's marked as no longer in progress.

### Get Pending Action by ID

```http
GET https://{accountId}.api.nextspace.host/pendingaction/{action_id}
```

**Requires:**

- Account ID: Account ID must be specified in the subdomain of the request url.

| Parameter | In | Required | Description |
| --- | --- | --- | --- |
| `{accountId}` | path | yes | The account id of the account to perform the request on. |
| `{action_id}` | path | yes | ID of the Pending Action record. |

**Response**

```typescript
// Response is the same as IAction definition above.
// It returns the JSON directly.
```

**Javascript example**

```javascript
const url = "https://{accountId}.api.nextspace.host/pendingaction/{action_id}";
const method = "get";
const token = "your-token";
const body = null;

async function doRequest(type, url, body, token) {
    const headers = {
        "Authorization": `Bearer ${token}`,
        "Content-Type": "application/json"
    };
    const options = {
        method: type,
        headers: headers,
        body: body ? JSON.stringify(body) : null
    };
    const res = await fetch(url, options);
    const json = await res.json();
    return json;
}

doRequest(method, url, body, token).then((res) => {
    console.log(res);
}).catch((err) => {
    console.error(err);
});
```

## Request progress messages

If you'd like expanded information about the progress of a Pending Action, you can request for progress messages.

### Get Pending Action Progress Messages

```http
GET https://{accountId}.api.nextspace.host/pendingaction/{action_id}/progressmessages?SortOrder={order}&PageSize={size}&PageIndex={index}&Type={type}
```

**Requires:**

- Account ID: Account ID must be specified in the subdomain of the request url.

| Parameter | In | Required | Description |
| --- | --- | --- | --- |
| `{accountId}` | path | yes | The account id of the account to perform the request on. |
| `{action_id}` | path | yes | ID of the Pending Action record. |
| `SortOrder={order}` | query | no | Sort order of the messages. Lets you get newest or oldest first. |
| `PageSize={size}` | query | no | Number of messages to get per page. |
| `PageIndex={index}` | query | no | Page number to get. The first page is 0. |
| `Type={type}` | query | no | Filter messages by type. Add multiple query params to filter for multiple types. Eg: Type=INFO&Type=ERROR |

**Response**

```typescript
interface IResponse {
    // Array of progress messages found for your search.
    Items: {
        // ID of the pending action record.
        "PendingAction.ID": number;
        // ID of the message record.
        ID: number;
        // ID of the application that created the message.
        "CreatedBy.Application": string;
        // Date/time the message was created.
        "Created": string;
        // Message type. Certain types can be hidden from end-users as they are only used for debugging.
        "Message.Type": string;
        // Message text.
        Message: string;
    }[];
}
```

**Javascript example**

```javascript
const url = "https://{accountId}.api.nextspace.host/pendingaction/{action_id}/progressmessages";
const method = "get";
const token = "your-token";
const body = null;

async function doRequest(type, url, body, token) {
    const headers = {
        "Authorization": `Bearer ${token}`,
        "Content-Type": "application/json"
    };
    const options = {
        method: type,
        headers: headers,
        body: body ? JSON.stringify(body) : null
    };
    const res = await fetch(url, options);
    const json = await res.json();
    return json;
}

doRequest(method, url, body, token).then((res) => {
    console.log(res);
}).catch((err) => {
    console.error(err);
});
```

## Cancel a Pending Action

If you need to cancel a Pending Action, you can do so with this request.

### Cancel Pending Action by ID

```http
DELETE https://{accountId}.api.nextspace.host/pendingaction/{action_id}
```

**Requires:**

- Account ID: Account ID must be specified in the subdomain of the request url.

| Parameter | In | Required | Description |
| --- | --- | --- | --- |
| `{accountId}` | path | yes | The account id of the account to perform the request on. |
| `{action_id}` | path | yes | ID of the Pending Action record. |

**Javascript example**

```javascript
const url = "https://{accountId}.api.nextspace.host/pendingaction/{action_id}";
const method = "delete";
const token = "your-token";
const body = null;

async function doRequest(type, url, body, token) {
    const headers = {
        "Authorization": `Bearer ${token}`,
        "Content-Type": "application/json"
    };
    const options = {
        method: type,
        headers: headers,
        body: body ? JSON.stringify(body) : null
    };
    const res = await fetch(url, options);
    const json = await res.json();
    return json;
}

doRequest(method, url, body, token).then((res) => {
    console.log(res);
}).catch((err) => {
    console.error(err);
});
```

---

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/apipendingaction