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.
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.
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).
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.
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.
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.
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
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
Get change records for one concept
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".
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.
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.
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.
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).
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.
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.
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.