Skip to main content

Audit events

The audit log records every change and every refusal in the workspace, with who did it and with which credential.

Belongs to: Credential

AuditEvent object​

An audit event records one call that changed something or was refused: who made it, with which credential, on what, and how it ended.

iduuidrequired

The event's id.

occurred_atdate-timerequired

When the event first happened.

last_occurred_atdate-timerequired

When it last happened: the same refusal repeated within a minute folds into one event, which keeps the first call's details, an MCP tool call's mcp_operation_id included.

occurrencesintegerrequired

How many times it happened.

actor_kindstringrequired

What acted: user for a person, workspace_key for a workspace token, and others.

actor_idstringrequired

The id of who acted.

actor_descstring or nullrequired

Who acted, for a person to read. In a signed-in session, the member's email address. With an API token, the token's kind and the first 8 characters of its id (an OAuth token's app registration id), after the email address of the member it acts as: 'name@example.com (API token 1a2b3c4d)', 'name@example.com (connected app 9f8e7d6c)', 'workspace token 1a2b3c4d'. Null on older events and for someone outside the workspace.

credential_kindstringrequired

The credential used: session, user_key, oauth or workspace_key.

credential_iduuid or nullrequired

The API token used; null for a session.

actionstringrequired

What was done, such as organization.create.

privilegesarray of stringrequired

The privileges the route asks for, not what the actor holds.

target_kindstring or nullrequired

The kind of thing acted on.

target_idstring or nullrequired

The id of the thing acted on; null when you are not shown it.

target_descstring or nullrequired

The thing acted on, for a person to read; null when you are not shown it.

target_hiddenboolean

Sent as true when the target's id or name is withheld from you.

org_idsarray of uuid or nullrequired

The organizations the event touched that you can see; null when the event names no organization.

all_orgsbooleanrequired

Whether the event covered every organization; org_ids then lists only those its details name.

other_orgsboolean

Sent as true when the event touched an organization you cannot see, left out without an id or a count.

details_withheldboolean

Sent as true when the event has details you are not shown.

outcomestringrequired

How the call ended, such as allowed, denied or failed.

reasonstring or nullrequired

Why a call was refused or failed: on a refusal, token_scope when only the API token's scopes refused it, else the privileges the call needs; on a failure, the error code.

detailsmap of any or nullrequired

What the event recorded about the call, as an object whose keys depend on the action. A call made with an API token adds credential_short_id, as in actor_desc, and credential_label, the token's label or the OAuth app's name as it was when the event was written, or {"hidden": true} when the token covers an organization you cannot see. Null when the event recorded no details, or when you are not shown them (details_withheld).

details_vinteger

Sent as 1 when details are shown field by field as the action declares them; left out on an older event, shown whole or withheld whole.

ipstring or nullrequired

The address the call came from. For a call made through the SparkLogs MCP server, the address of the MCP client.

user_agentstring or nullrequired

The user agent the call sent. For a call made through the SparkLogs MCP server, the user agent of the MCP client.

invocation_methodone of the values belowrequired

How the call reached SparkLogs.

  • direct The call came to the REST API or the app directly.
  • mcp An MCP client made the call through the SparkLogs MCP server.

List audit events​

GET/workspaces/{workspace_id}/audit-events
Preview

Returns the workspace's audit log a page at a time, newest first, filtered by actor, credential, organization, target, action, outcome and time; filters combine, a row passing every one given. Needs auditlog.query. Held over every organization, it shows every event. Held at some organizations, it shows a change when one of its organizations is inside them, a data read when one of its organizations is inside them or above them, or it covers every organization, and no event that names no organization, such as a change to the workspace itself; organizations you cannot see are left out of each event shown. Pages follow with cursor, as on every list.

curl -X GET \  "https://engine.sparklogs.app/app-api/workspaces/5e1f0a00-0000-4000-8000-000000000001/audit-events?credential_id=4b1d0000-0000-4000-8000-000000000801&occurred_since=2026-10-11T00%3A00%3A00Z&limit=1" \  -H "Authorization: Bearer $SPARKLOGS_TOKEN"

Access

Works with
Signed-in person, Personal token, OAuth token, Workspace token
Scope
any of admin:readadmin:write
Privilege
auditlog.query

Needs auditlog.query. auditlog.query applies at each organization a grant covers and every organization below it.

Behavior

Retry
Safe to send again
Paging
Cursor · 500 a page by default, up to 5000 · newest first

Path parameters

workspace_iduuidrequired

The workspace's id.

Query parameters

actor_idstring

Only events done by this actor: a user id, or a workspace token's id.

credential_iduuid

Only events done with this API token: what one token did, and so what it created.

organization_iduuid

Only events touching this organization.

target_idstring

Only events done to this thing, such as one agent, group or member: what happened to it. An event whose target you are not shown never matches.

actionarray of string

Only events of these actions, such as member.remove. Each operation states the action it is recorded under as audit_action. A SparkLogs Agent changed before the agent. actions existed is recorded under the ingest_key. ones. A restore recorded before the .restore actions reached the workspace's region is under <kind>.undelete. A comma-separated list matches any of its values, each exactly and ignoring case.

action_prefixstring

Only events whose action starts with this, ignoring case, such as organization..

outcomearray of one of the values below

Only events with one of these outcomes. A comma-separated list matches any of its values.

  • allowed The call was allowed.
  • denied The call was refused.
  • failed The call failed.
invocation_methodarray of one of the values below

Only events whose call reached SparkLogs one of these ways. A comma-separated list matches any of its values.

  • direct Calls made to the REST API or in the app directly.
  • mcp Calls an MCP client made through the SparkLogs MCP server: its tool calls, and the REST calls it made through them.
occurred_sincedate-time

Only events at or after this time. An RFC 3339 time.

occurred_beforedate-time

Only events before this time. An RFC 3339 time.

cursorstring

The next_cursor of the previous page, sent with the same filters: the page after it.

limitinteger

How many events a page holds: 1 to 5000, 500 by default. It may change between pages.

Default: 5001 to 5000

Response 200

audit_eventsarray of AuditEventrequired

The events, newest first.

next_cursorstring or nullrequired

Null on the last page. Otherwise pass it as cursor, with the same filters, for the next page of older events.

messagestringrequired

What the call did, as a short phrase for a person to read. Its wording may change: act on the HTTP status.

Errors

StatusCodeWhenSend again?
400APP_API_ERR_BAD_PARAMETERSA query parameter it does not take, or one given twice.No
400APP_API_ERR_BAD_PARAMETERSA filter's value is empty, names an empty item, is not one of the values the filter takes, or is not an id or a time where the filter asks for one; parameter names the filter.No
400APP_API_ERR_BAD_PARAMETERSlimit is not 1 to 5000, organization_id is not a UUID, or cursor cannot be read or was sent with other filters.No
403APP_API_ERR_NO_PRIVILEGEtoken_scopeno_privilegeYou do not hold auditlog.query, or it covers no organization. The same refusal comes when the path names a workspace other than the token's own.No
403APP_API_ERR_NO_PRIVILEGEtoken_scopeno_privilegeorganization_id names an organization outside your audit reach.No

Plus the errors every call can return.

Related

Read an audit event​

GET/workspaces/{workspace_id}/audit-events/{id}
Preview

Returns one audit event as the list shows it, its lists whole. Needs auditlog.query. One you cannot see returns 404, as one that does not exist does.

curl -X GET \  "https://engine.sparklogs.app/app-api/workspaces/5e1f0a00-0000-4000-8000-000000000001/audit-events/ad170000-0000-4000-8000-000000000701" \  -H "Authorization: Bearer $SPARKLOGS_TOKEN"

Access

Works with
Signed-in person, Personal token, OAuth token, Workspace token
Scope
any of admin:readadmin:write
Privilege
auditlog.query

Needs auditlog.query. auditlog.query applies at each organization a grant covers and every organization below it.

Behavior

Retry
Safe to send again

Path parameters

workspace_iduuidrequired

The workspace's id.

iduuidrequired

The audit event's id.

Response 200

audit_eventAuditEventrequired

The event, its lists whole.

messagestringrequired

What the call did, as a short phrase for a person to read. Its wording may change: act on the HTTP status.

Errors

StatusCodeWhenSend again?
400APP_API_ERR_BAD_PARAMETERSA query parameter it does not take, or one given twice.No
400APP_API_ERR_BAD_PARAMETERSid is not a UUID.No
403APP_API_ERR_NO_PRIVILEGEtoken_scopeno_privilegeYou do not hold auditlog.query. The same refusal comes when the path names a workspace other than the token's own.No
404APP_API_ERR_RECORD_NOT_FOUNDNo such event, or one you cannot see.No

Plus the errors every call can return.

Related