---
title: "Audit Records"
section: "API Reference"
route: /apiaudit
account: {accountId}
bruce_api: https://{accountId}.api.nextspace.host
guardian_api: https://guardian.nextspace.host
---
# Audit Records

Audit records are the account's log of what the API did. Each record is either a log line written while a request or job ran (info, warnings and errors), or a change record saying a record was created, updated or deleted, and by which user.

Account admins see them in Operator under Audit Logs, and on the Record Audit panel of an Entity, Entity Type or Project View. The same records are what you should read when debugging a problem on an account: an import that failed, a record that changed unexpectedly, or a job that errored.

This article will cover the audit record data model, how to request and page through records, and recipes for debugging with them.

## Data model

Below is the data model for an audit record. Records are written by the API only; there is no request to create, update or delete them.

```typescript
interface IAudit {
    // Unique numeric ID, increasing as records are stored.
    ID: number;
    // ID of the user whose request wrote the record.
    // Null when the request was anonymous.
    "CreatedBy.User.ID": string | null;
    // ISO 8601 date time when the API logged the event.
    // Use this to order events, it is when the event happened.
    Logged: string;
    // ISO 8601 date time when the record was stored.
    // Log records are stored in batches, so this can trail Logged by about 10 seconds.
    Created: string;
    // See the types and severities section below.
    Type: EType;
    Severity: ESeverity;
    // The log text. Set on log records ("L"), empty on change records.
    Message?: string;
    // Code of the kind of record that changed. Eg: "E" for Entity.
    // Set on change records only. See the concepts section below.
    Concept?: string;
    // Correlation value shared by every record written in the same request or job run.
    // See the scope section below.
    Scope: string;
    // Extra detail. Its shape depends on the type, see the change data section below.
    Data?: any;
}
```

Before a record is stored, the API replaces anything in "Message" and "Data" that looks like a credential with a "<REDACTED:RULE_X>" marker: database connection strings, session IDs, access tokens, authorisation headers, signed file store URLs and OpenAI keys.

## Types and severities

"Type" says what kind of record it is and "Severity" how serious it is. Change records are always "I" severity.

```typescript
enum EType {
    // Log line written while a request or job ran. Eg: import progress, a failed row, an exception.
    LOG = "L",
    // A record was created.
    CREATE = "C",
    // A record was updated.
    UPDATE = "U",
    // A record or a batch of records was deleted.
    DELETE = "D"
}

enum ESeverity {
    // Debug. Only written by our internal development environment.
    DEBUG = "D",
    // Info. Every change record, and progress logs such as "Starting CSV import job".
    INFO = "I",
    // Warning. Something was skipped or looked wrong but the work carried on.
    WARN = "W",
    // Error. Something failed. "Data.Exception" holds the exception message when there was one.
    ERROR = "E"
}
```

Log records come from the import, export, conversion and account jobs, file uploads, tileset generation and the other server jobs. Every new Pending Action progress message is also written as an "I" log record with the message as its "Message". You can read about Pending Actions in [Pending Actions (Server Jobs)](/apipendingaction).

## Concepts

"Concept" is a short code for the kind of record a change record is about. The list below is every concept the API writes change records for. Workflow records, users, user groups and permissions are not audited.

```typescript
enum EConcept {
    ACCOUNT_COUNT = "AC",
    ASSEMBLY = "A",
    ATTACHMENT_TYPE = "AT",
    // Change Sets.
    CHANGE_SET = "CS",
    CLIENT_FILE = "CLF",
    CLIENT_FILE_FOLDER = "CLFF",
    COMMENT = "CM",
    CUSTOM_FORM = "CSF",
    DATA_FEED = "DF",
    // DataLab queries and query groups.
    DATA_LAB_QUERY = "Q",
    DATA_LAB_QUERY_GROUP = "QG",
    DATA_SOURCE = "DS",
    DATA_TRANSFORM = "DT",
    DATA_VALIDATION = "DVAL",
    DOCUMENT_VIEW = "DV",
    ENTITY = "E",
    // Entity index definitions managed through v3/entityIndexes.
    ENTITY_INDEX = "EIX",
    ENTITY_LOD = "EL",
    ENTITY_RELATION = "ER",
    // Entity Types, and their data schemas, sources, triggers and relations.
    ENTITY_TYPE = "ET",
    // Entity Type LODs and Entity Type LOD styles.
    ENTITY_TYPE_LOD = "ETL",
    ONTOLOGY = "ON",
    // Entity Tags.
    LAYER = "L",
    LOD_CATEGORY = "LC",
    PROJECT_VIEW = "PV",
    PENDING_ACTION = "PA",
    RELATION_TYPE = "RT",
    SCENARIO = "SC",
    // Entity Styles.
    UI_ENTITY_DISPLAY_SETTING = "S",
    UI_DASHBOARD_VIEW = "DBV",
    UI_MARKUP = "UM",
    UI_PLUGIN = "PG",
    // Project View bookmarks and bookmark groups.
    UI_SLIDE = "PVS",
    UI_SLIDE_GROUP = "SG",
    PROGRAM_KEY = "PK",
    TILESET = "TS",
    UI_TABLE_VIEW = "TV"
}
```

Wherever a request takes a concept you can send the code or the name, in any case and with or without underscores. Eg: "ET", "EntityType" and "entity_type" all mean Entity Type.

## Change data

The API writes change records in two ways, and they carry different "Data".

Deletes are always recorded. When an Entity, Entity Type, Client File, Project View, bookmark, Custom Form, Tag or most other records are deleted, we store a short delete record. Most carry the deleted record's ID and name. Client File deletes and bulk Entity deletes carry the list of IDs, cut down to the first 10 for Entities.

```typescript
// Data on a delete record of one record.
interface IDeleteData {
    ID: number | string;
    Name: string;
}

// Data on a delete record of an Entity Type.
interface IEntityTypeDeleteData {
    "EntityType.ID": string;
    "EntityType.Name": string;
}

// Data on a Client File or bulk Entity delete record.
interface IBulkDeleteData {
    IDs: (number | string)[];
    // Set when the list was cut down. Eg: "Truncated to 10 IDs. Original total: \"250\"."
    Warning?: string[];
}
```

Creates, updates and full deletes with the record's content are only recorded when detailed auditing is turned on for the account, through the "DetailedAuditEnabled" account limit. When it is off, Operator's Record Audit panel says the account only has shallow auditing. These records are stored straight away rather than in batches, and an update that changes nothing writes no record.

```typescript
// Data on a detailed change record.
interface IDetailedChangeData {
    // ID of the changed record. For most concepts this is the record's own ID.
    // Sub-records of an Entity Type use a compound ID. Eg:
    //   "Source/12" for an Entity Type source.
    //   "Trigger/3" for an Entity Type trigger.
    //   "Relation/5" for an Entity Type relation.
    //   "{entity_type_id}/{schema_id}" for an Entity Type data schema.
    //   "{entity_type_id}/{lod_category_key}/Style" for an Entity Type LOD style.
    // Entity relations use "{principal_entity_id}|{relation_type_id}|{other_entity_id}|{dimension_id}".
    "Record.ID": string;
    // Same value as the record's Type: "C", "U" or "D".
    Action: string;
    // The record before the change. Not set on creates.
    Before?: any;
    // The record after the change. Not set on deletes.
    After?: any;
}
```

The limit's number sets how much an update stores. At 2, which is the default when the limit is on with no number, "Before" and "After" are full copies of the record. At 1 they hold only the fields that differ, so a changed Entity attribute shows as just that path under "Data". The top level "Created", "CreatedDate", "Updated" and "UpdatedDate" fields are left out at both levels.

For an Entity, "Before" and "After" hold the Entity's "ID", "Type.ID", "Name", "Layer.ID", "Bruce" and "Data" (its attributes), so you can see which attribute changed and to what.

## Scope

Every record written while handling one API request, or one run of a server job, shares the same "Scope". Search by a record's "Scope" to get everything else that request or job wrote.

The value is built from the API instance and the request. A server job that runs in its own worker includes "PA:" and its Pending Action ID in the value, and so do progress messages posted to a Pending Action. Eg: a job for Pending Action 4821 writes a "Scope" containing "_PA:4821_". Treat the rest of the value as opaque.

## Requesting records

All audit requests need an admin user session on the account. They are read only.

The first request lists every kind of record, log records included, and always returns the full record. Use it to read what happened during a request or job.

### Get a list of audit records

```http
GET https://{accountId}.api.nextspace.host/v3/accountAudits?PageSize={50}&PageIndex={0}&OrderBy={Logged}&SortOrder={DESC}&LastSeenID={id}&Search={value}&Concept={concept}
```

**Requires:**

- Account ID: Account ID must be specified in the subdomain of the request url.
- Logged in user auth token: A token for an active user session on the account, sent as "Authorization: Bearer <token>".
- Admin user auth token: A token for an active admin user session on the account, sent as "Authorization: Bearer <token>".

| Parameter | In | Required | Description |
| --- | --- | --- | --- |
| `{accountId}` | path | yes | The account id of the account to perform the request on. |
| `PageSize={50}` | query | no | How many records to return per page. Default is 50. Set both PageSize and PageIndex to -1 to get only the TotalCount. |
| `PageIndex={0}` | query | no | Which page to return, starting from 0. TotalCount is only returned on page 0. |
| `OrderBy={Logged}` | query | no | Column to sort by. One of ID, Logged, Created, Severity, Type, Message, Concept, Scope or User.ID. Default is Logged, and any other value is treated as Logged. |
| `SortOrder={DESC}` | query | no | ASC or DESC. Default is DESC, newest first. Any value other than ASC is treated as DESC. |
| `LastSeenID={id}` | query | no | Only return records with an ID greater than this. Use it to fetch records stored since your last request. |
| `Search={value}` | query | no | Exact match against the record's Scope, Data.ID or Data.Record.ID. It does not search the message text. |
| `Concept={concept}` | query | no | Only return records of these concepts. Repeat the parameter or separate values with commas. Eg: Concept=E,ET. |

**Response**

```typescript
interface IResponse {
    // The records on this page.
    // See the data model above for the record structure.
    Items: IAudit[];
    // How many records match. Only returned on page 0.
    TotalCount?: number;
    // One line per Concept value that was not recognised.
    Warning?: string[];
}
```

**Javascript example**

```javascript
const url = "https://{accountId}.api.nextspace.host/v3/accountAudits";
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);
});
```

The next two requests only return change records ("C", "U" and "D"), add a filter on the changed record's ID, and return a short summary of each record unless you ask for the full one. Operator's Record Audit panel uses them.

### Get change records for concepts

```http
GET https://{accountId}.api.nextspace.host/v3/accountAudits/concepts?Concept={concept}&RecordID={record_id}&DetailLevel={summary}&PageSize={50}&PageIndex={0}&OrderBy={Logged}&SortOrder={DESC}&LastSeenID={id}&Search={value}
```

**Requires:**

- Account ID: Account ID must be specified in the subdomain of the request url.
- Logged in user auth token: A token for an active user session on the account, sent as "Authorization: Bearer <token>".
- Admin user auth token: A token for an active admin user session on the account, sent as "Authorization: Bearer <token>".

| Parameter | In | Required | Description |
| --- | --- | --- | --- |
| `{accountId}` | path | yes | The account id of the account to perform the request on. |
| `Concept={concept}` | query | no | Only return records of these concepts. Repeat the parameter or separate values with commas. Eg: Concept=ET,ETL. |
| `RecordID={record_id}` | query | no | Exact match against the record's Data.Record.ID, the ID of the changed record. |
| `DetailLevel={summary}` | query | no | summary or full. Default is summary. full returns the whole record including Data. Any other value is a 400 error. |
| `PageSize={50}` | query | no | How many records to return per page. Default is 50. Set both PageSize and PageIndex to -1 to get only the TotalCount. |
| `PageIndex={0}` | query | no | Which page to return, starting from 0. TotalCount is only returned on page 0. |
| `OrderBy={Logged}` | query | no | Column to sort by. Same values as the list request. Default is Logged. |
| `SortOrder={DESC}` | query | no | ASC or DESC. Default is DESC, newest first. |
| `LastSeenID={id}` | query | no | Only return records with an ID greater than this. |
| `Search={value}` | query | no | Exact match against the record's Scope, Data.ID or Data.Record.ID. |

**Response**

```typescript
interface IResponse {
    // The concept codes the request was filtered by.
    Concepts: string[];
    // "summary" or "full".
    DetailLevel: string;
    // ISummaryAudit when DetailLevel is summary, IAudit when it is full.
    Items: ISummaryAudit[] | IAudit[];
    // How many records match. Only returned on page 0.
    TotalCount?: number;
    // One line per Concept value that was not recognised.
    Warning?: string[];
}

interface ISummaryAudit {
    ID: number;
    Logged: string;
    Created: string;
    "CreatedBy.User.ID": string | null;
    Concept: string;
    // Data."Record.ID" of the record. Null on short delete records.
    "Record.ID": string | null;
    // "C", "U" or "D".
    Type: string;
    // "Created", "Updated" or "Deleted".
    Action: string;
}
```

**Javascript example**

```javascript
const url = "https://{accountId}.api.nextspace.host/v3/accountAudits/concepts";
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);
});
```

### Get change records for one concept

```http
GET https://{accountId}.api.nextspace.host/v3/accountAudits/concept/{concept}?RecordID={record_id}&DetailLevel={summary}&PageSize={50}&PageIndex={0}&OrderBy={Logged}&SortOrder={DESC}&LastSeenID={id}&Search={value}
```

**Requires:**

- Account ID: Account ID must be specified in the subdomain of the request url.
- Logged in user auth token: A token for an active user session on the account, sent as "Authorization: Bearer <token>".
- Admin user auth token: A token for an active admin user session on the account, sent as "Authorization: Bearer <token>".

| Parameter | In | Required | Description |
| --- | --- | --- | --- |
| `{accountId}` | path | yes | The account id of the account to perform the request on. |
| `{concept}` | path | yes | The concept code or name. Eg: E, Entity or EntityType. |
| `RecordID={record_id}` | query | no | Exact match against the record's Data.Record.ID, the ID of the changed record. |
| `DetailLevel={summary}` | query | no | summary or full. Default is summary. |
| `PageSize={50}` | query | no | How many records to return per page. Default is 50. |
| `PageIndex={0}` | query | no | Which page to return, starting from 0. |
| `OrderBy={Logged}` | query | no | Column to sort by. Same values as the list request. Default is Logged. |
| `SortOrder={DESC}` | query | no | ASC or DESC. Default is DESC, newest first. |
| `LastSeenID={id}` | query | no | Only return records with an ID greater than this. |
| `Search={value}` | query | no | Exact match against the record's Scope, Data.ID or Data.Record.ID. |

**Response**

```typescript
// Same response as the request for concepts above.
```

**Javascript example**

```javascript
const url = "https://{accountId}.api.nextspace.host/v3/accountAudits/concept/{concept}";
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);
});
```

## Paging and filtering

Records come back newest first by "Logged", with ties broken by the highest "ID" first. To get the most recent N records, send PageSize=N and leave the rest at their defaults.

Always send a positive "PageSize". A zero or negative page size, other than the -1 and -1 count request, returns every matching record in one response.

Check "Warning" on every response. If none of the concepts you sent were recognised, the concept filter is dropped and you get records of every concept.

There is no filter on user, severity, message text or date. To narrow by those, page through newest first and filter on "CreatedBy.User.ID", "Severity", "Message" or "Logged" yourself, and stop paging once "Logged" is older than the start of the range you care about.

To follow new records as they arrive, request with OrderBy=ID, SortOrder=ASC and LastSeenID set to the highest "ID" you have seen. Log records are stored in batches every 10 seconds, so poll no faster than that. Operator's Audit Logs panel refreshes every 10 seconds.

## Debugging with audit records

The recipes below are written for an agent or developer looking into a problem on an account. Each uses only the requests above.

### See what happened most recently

Request the newest records across the account, then read the "E" and "W" severity records and their "Message" and "Data.Exception".

```text
GET v3/accountAudits?PageSize=100
```

### Find who changed an Entity

Request the Entity's change records in full. "CreatedBy.User.ID" is who made each change, and "Data.Before" and "Data.After" show what changed. This needs detailed auditing on; without it the account has no update records.

```text
GET v3/accountAudits/concept/Entity?RecordID={entity_id}&DetailLevel=full&PageSize=20
```

To find who deleted an Entity when detailed auditing is off, search the list request by its ID. This finds the short delete record of a single delete. A bulk delete lists its IDs in "Data.IDs", which the search does not match, so look through the "D" records with Concept=E for it instead.

```text
GET v3/accountAudits?Search={entity_id}
GET v3/accountAudits?Concept=E&PageSize=100
```

### Find recent changes to an Entity Type

An Entity Type's own changes use its ID as "Record.ID". Changes to its sources, triggers, relations and data schemas are also recorded under "ET" but with the compound IDs described in the change data section, so list the concept without a record filter to see those.

```text
GET v3/accountAudits/concepts?Concept=ET&RecordID={entity_type_id}&DetailLevel=full
GET v3/accountAudits/concepts?Concept=ET,ETL&DetailLevel=full&PageSize=50
```

### Find out why an import or job failed

Start from the Pending Action, not the audit records. Its "Status", "Result" and progress messages are kept per job and say whether it failed and why. You can read about them in [Pending Actions (Server Jobs)](/apipendingaction).

For more than the Pending Action shows, request recent records and find one whose "Scope" contains "PA:" and the Pending Action ID, or whose "Message" matches one of the progress messages. Then search by that record's "Scope" to get every log line from the run, including errors that were not posted as progress messages.

```text
GET v3/accountAudits?PageSize=200
GET v3/accountAudits?Search={scope}&OrderBy=ID&SortOrder=ASC&PageSize=500
```

With detailed auditing on, Pending Actions are also recorded under "PA" and Change Sets under "CS", so you can see who started a job or staged a Change Set. You can read about Change Sets in [Change Sets](/apichangesets).

### Find what one user did

There is no user filter. Page through the list request newest first and keep the records whose "CreatedBy.User.ID" matches, stopping once "Logged" passes the start of the period you are looking at.

### A user lost access

Audit records do not cover users, user groups or permissions, so they cannot tell you why a user lost access.

---

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