Skip to content

Read the audit log

Read the account's record of changes. Billing owners, admins and members granted audit view can read the organization's record. Other members can read their own actions and changes to Computers they own.

Parameters

#
querystring
Search text, such as a resource name, address, action or actor.
actorstring
Actor to filter by. Give a person's email address or ID, an API key ID, or heaven for changes made by Heaven.
actionstring
Action or group filter, such as computer.website.update or computers.
sincestring
Start of the history window, as an RFC 3339 timestamp or a duration ago such as 24h. Defaults to 7d. The window can go back up to a year.
beforestring
Pagination cursor from the previous response. Returns older entries.
limitstring
Maximum changes per page. Defaults to 50 and accepts up to 500. CSV defaults to 5000 and accepts up to 5000.
formatstring
Output format. Give csv for a spreadsheet-compatible file. Omit for the standard response.
organizationstring
Organization name or ID. A credential, named resource or sole membership can select the organization for you.

Returns

#
dataobjectAlways present
Account audit records matching the request, newest first. Your role determines which records are visible.
Show 6 attributesHide attributes
account_idstringAlways present
Account whose audit log was read.
csvstring
This page rendered as CSV when CSV format was requested. May be omitted.
eventsobject[] | nullAlways present
Audit events in this page.
Show 1 attributeHide attributes
itemsobject
A recorded account action.
Show 16 attributesHide attributes
actionstringAlways present
Machine-readable event name.
actorobjectAlways present
Person, key or Heaven action responsible.
Show 8 attributesHide attributes
api_key_idstring
API key used for the action. May be omitted.
credentialstring
How the person authenticated, such as a browser, SSH key or program sign-in. May be omitted.
emailstring
Person's email. May be omitted.
kindstringAlways present
Actor category: person, api_key or heaven.
labelstring
Key label or MCP client name identifying the credential. May be omitted.
namestring
Person's display name. May be omitted.
picturestring
Person's profile picture URL. May be omitted.
user_idstring
Acting person's ID, including the owner of an API key. May be omitted.
addressstring
Recorded client network address. May be omitted.
atstring (date-time)Always present
When the action was recorded.
changesobject[]
Saved values before and after the action. May be omitted.
Show 1 attributeHide attributes
itemsobject
One value changed by an audited action.
Show 3 attributesHide attributes
afterstringAlways present
Its resulting value rendered as text.
beforestringAlways present
Its previous value rendered as text.
fieldstringAlways present
Setting that changed.
clientstring
Recorded client identification. May be omitted.
commandstring
Command associated with the action, when applicable. May be omitted.
computerobject
Affected Computer, named as it was at the time. May be omitted.
Show 2 attributesHide attributes
idstringAlways present
Object's stable ID.
namestringAlways present
Its name at the time of the event.
groupstringAlways present
Event category used by audit filters.
idstringAlways present
Event ID.
partsobject[] | nullAlways present
Summary segments marking resource and person names.
Show 1 attributeHide attributes
itemsobject
A display segment of an audit event's summary.
Show 2 attributesHide attributes
nameboolean
Whether this segment names a resource or person. May be omitted.
textstringAlways present
Segment's text.
poolobject
Affected pool, named as it was at the time. May be omitted.
Show 2 attributesHide attributes
idstringAlways present
Object's stable ID.
namestringAlways present
Its name at the time of the event.
request_idstring
Request ID for this action. May be omitted.
sourcestringAlways present
Interface through which the action arrived.
subjectstring
Another object concerned by the action. May be omitted.
summarystringAlways present
A sentence describing the action.
nextstring
Cursor for before to fetch the next older page. Absent on the last page. May be omitted.
scopestring
yours limits the read to changes you made and changes to Computers you own. May be omitted.
sincestring (date-time)Always present
Start of the selected time range.

Errors

#
CodeStatusWhat happened
invalid400An input is missing or invalid.
unauthenticated401The credential is missing, invalid, expired or revoked.
denied403The caller lacks permission for this action.
not_found404The resource is absent or inaccessible to this caller.
conflict409The request conflicts with the current resource state or an earlier request.
over_capacity409The request exceeds a resource or credential allowance.
access_list_full409The change would exceed the access-list allowance.
rate_limited429The caller's request rate exceeds its limit.
busy429Too much work is in progress to accept this request.
unknown503The outcome is unconfirmed; a change may have happened.
unavailable503The service or requested feature is unavailable.

Notes

#
  • API key permission: audit view.