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
- GET
List audit events/workspaces /{workspace_id} /audit-events - GET
Read an audit event/workspaces /{workspace_id} /audit-events /{id}
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.
iduuidrequiredThe event's id.
occurred_at date-timerequiredWhen the event first happened.
last_occurred_at date-timerequiredWhen 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.
occurrencesintegerrequiredHow many times it happened.
actor_kind stringrequiredWhat acted: user for a person, workspace_key for a workspace token, and others.
actor_id stringrequiredThe id of who acted.
actor_desc string or nullrequiredWho 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_kind stringrequiredThe credential used: session, user_key, oauth or workspace_key.
credential_id uuid or nullrequiredThe API token used; null for a session.
actionstringrequiredWhat was done, such as organization.create.
privilegesarray of stringrequiredThe privileges the route asks for, not what the actor holds.
target_kind string or nullrequiredThe kind of thing acted on.
target_id string or nullrequiredThe id of the thing acted on; null when you are not shown it.
target_desc string or nullrequiredThe thing acted on, for a person to read; null when you are not shown it.
target_hidden booleanSent as true when the target's id or name is withheld from you.
org_ids array of uuid or nullrequiredThe organizations the event touched that you can see; null when the event names no organization.
all_orgs booleanrequiredWhether the event covered every organization; org_ids then lists only those its details name.
other_orgs booleanSent as true when the event touched an organization you cannot see, left out without an id or a count.
details_withheld booleanSent as true when the event has details you are not shown.
outcomestringrequiredHow the call ended, such as allowed, denied or failed.
reasonstring or nullrequiredWhy 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 nullrequiredWhat 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_v integerSent 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 nullrequiredThe address the call came from. For a call made through the SparkLogs MCP server, the address of the MCP client.
user_agent string or nullrequiredThe user agent the call sent. For a call made through the SparkLogs MCP server, the user agent of the MCP client.
invocation_method one of the values belowrequiredHow the call reached SparkLogs.
directThe call came to the REST API or the app directly.mcpAn MCP client made the call through the SparkLogs MCP server.
List audit events
/workspaces/{workspace_id}/audit-events 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.
- Request
- Response
- curl
- PowerShell
- Python
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"Invoke-RestMethod -Method Get ` -Uri "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" ` -Headers @{ Authorization = "Bearer $env:SPARKLOGS_TOKEN" }import os import requests response = requests.get( "https://engine.sparklogs.app/app-api/workspaces/5e1f0a00-0000-4000-8000-000000000001/audit-events" , headers={"Authorization": f"Bearer {os.environ['SPARKLOGS_TOKEN']}"}, params={ "credential_id": "4b1d0000-0000-4000-8000-000000000801", "occurred_since": "2026-10-11T00:00:00Z", "limit": "1", },)response.raise_for_status(){ "message": "audit events retrieved", "audit_events": [ { "id": "ad170000-0000-4000-8000-000000000701", "occurred_at": "2026-11-09T16:00:00Z", "last_occurred_at": "2026-11-09T16:00:00Z", "occurrences": 1, "actor_kind": "workspace_key", "actor_id": "4b1d0000-0000-4000-8000-000000000801", "actor_desc": null, "credential_kind": "workspace_key", "credential_id": "4b1d0000-0000-4000-8000-000000000801", "action": "organization.update", "privileges": [ "organization.write" ], "target_kind": "organization", "target_id": "0a9e0000-0000-4000-8000-000000000105", "target_desc": "Harbor Dental", "org_ids": [ "0a9e0000-0000-4000-8000-000000000105" ], "all_orgs": false, "outcome": "allowed", "reason": null, "details": { "changes": [ { "field": "psa_client_id", "new": "10057", "old": null } ] }, "details_v": 1, "ip": "203.0.113.24", "user_agent": "psa-sync/2.3", "invocation_method": "direct" } ], "next_cursor": "eyJ2IjoxLCJleGFtcGxlIjoiYXVkaXQifQ"}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_id uuidrequiredThe workspace's id.
Query parameters
actor_id stringOnly events done by this actor: a user id, or a workspace token's id.
credential_id uuidOnly events done with this API token: what one token did, and so what it created.
organization_id uuidOnly events touching this organization.
target_id stringOnly 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 stringOnly 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_prefix stringOnly events whose action starts with this, ignoring case, such as organization..
outcomearray of one of the values belowOnly events with one of these outcomes. A comma-separated list matches any of its values.
allowedThe call was allowed.deniedThe call was refused.failedThe call failed.
invocation_method array of one of the values belowOnly events whose call reached SparkLogs one of these ways. A comma-separated list matches any of its values.
directCalls made to the REST API or in the app directly.mcpCalls an MCP client made through the SparkLogs MCP server: its tool calls, and the REST calls it made through them.
occurred_since date-timeOnly events at or after this time. An RFC 3339 time.
occurred_before date-timeOnly events before this time. An RFC 3339 time.
cursorstringThe next_cursor of the previous page, sent with the same filters: the page after it.
limitintegerHow many events a page holds: 1 to 5000, 500 by default. It may change between pages.
Response 200
The events, newest first.
next_cursor string or nullrequiredNull on the last page. Otherwise pass it as cursor, with the same filters, for the next page of older events.
messagestringrequiredWhat the call did, as a short phrase for a person to read. Its wording may change: act on the HTTP status.
Errors
400APP_API_ERR_BAD_PARAMETERS A query parameter it does not take, or one given twice.NoAPP_API_ERR_BAD_PARAMETERS A 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.NoAPP_API_ERR_BAD_PARAMETERS limit is not 1 to 5000, organization_id is not a UUID, or cursor cannot be read or was sent with other filters.No403APP_API_ERR_NO_PRIVILEGE token_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.NoAPP_API_ERR_NO_PRIVILEGE token_scopeno_privilegeorganization_id names an organization outside your audit reach.NoPlus the errors every call can return.
Related
Read an audit event
/workspaces/{workspace_id}/audit-events/{id} 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.
- Request
- Response
- curl
- PowerShell
- Python
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"Invoke-RestMethod -Method Get ` -Uri "https://engine.sparklogs.app/app-api/workspaces/5e1f0a00-0000-4000-8000-000000000001/audit-events/ad170000-0000-4000-8000-000000000701" ` -Headers @{ Authorization = "Bearer $env:SPARKLOGS_TOKEN" }import os import requests response = requests.get( "https://engine.sparklogs.app/app-api/workspaces/5e1f0a00-0000-4000-8000-000000000001/audit-events/ad170000-0000-4000-8000-000000000701" , headers={"Authorization": f"Bearer {os.environ['SPARKLOGS_TOKEN']}"},)response.raise_for_status(){ "message": "audit event retrieved", "audit_event": { "id": "ad170000-0000-4000-8000-000000000701", "occurred_at": "2026-11-09T16:00:00Z", "last_occurred_at": "2026-11-09T16:00:00Z", "occurrences": 1, "actor_kind": "workspace_key", "actor_id": "4b1d0000-0000-4000-8000-000000000801", "actor_desc": null, "credential_kind": "workspace_key", "credential_id": "4b1d0000-0000-4000-8000-000000000801", "action": "organization.update", "privileges": [ "organization.write" ], "target_kind": "organization", "target_id": "0a9e0000-0000-4000-8000-000000000105", "target_desc": "Harbor Dental", "org_ids": [ "0a9e0000-0000-4000-8000-000000000105" ], "all_orgs": false, "outcome": "allowed", "reason": null, "details": { "changes": [ { "field": "psa_client_id", "new": "10057", "old": null } ] }, "details_v": 1, "ip": "203.0.113.24", "user_agent": "psa-sync/2.3", "invocation_method": "direct" }}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_id uuidrequiredThe workspace's id.
iduuidrequiredThe audit event's id.
Response 200
The event, its lists whole.
messagestringrequiredWhat the call did, as a short phrase for a person to read. Its wording may change: act on the HTTP status.
Errors
400APP_API_ERR_BAD_PARAMETERS A query parameter it does not take, or one given twice.NoAPP_API_ERR_BAD_PARAMETERS id is not a UUID.No403APP_API_ERR_NO_PRIVILEGE token_scopeno_privilegeYou do not hold auditlog.query. The same refusal comes when the path names a workspace other than the token's own.No404APP_API_ERR_RECORD_NOT_FOUND No such event, or one you cannot see.NoPlus the errors every call can return.