Audit log

Every change in an org is recorded with who made it: an agent published by someone on your team, a session created with an API key, a task stopped from the console, a note the agent wrote to its own files during a task. Admins see the log in the console under Settings → Audit log. Admins and API keys can read it with GET /v1/audit_events:

curl "https://guidinghand.ai/v1/audit_events?object_type=agent&object_id=billing" \
  -H "Authorization: Bearer $GUIDINGHAND_API_KEY"

Response

{
  "data": [
    {
      "object": "audit_event",
      "id": "1842",
      "action": "agent.published",
      "object_type": "agent",
      "object_id": "billing",
      "target": "billing",
      "data": { "version": 4, "note": "Start from Settings → Billing", "changes": { "fields": ["instructions"] } },
      "actor": { "type": "user", "user_id": "usr_Qm3xV9aK2pLwZ0", "email": "jane@acme.com", "name": "Jane Doe" },
      "at": "2026-09-30T10:12:04.511Z"
    },
    {
      "object": "audit_event",
      "id": "1838",
      "action": "file.written",
      "object_type": "file",
      "object_id": "billing/notes/customers.md",
      "target": "/notes/customers.md",
      "data": { "agent": "billing", "bytes": 512 },
      "actor": { "type": "agent", "task_id": "task_mW8mcFPUN7Of" },
      "at": "2026-09-30T09:58:41.020Z"
    }
  ],
  "has_more": true,
  "next_cursor": "WzE3OTA0MjQ3MjEwMjAsIjE4MzgiXQ"
}

The event

Field	What it is
`id`	The event’s id.
`action`	What happened, such as `agent.published`. See Actions.
`object_type`, `object_id`	What it was about, as the API names it: an agent’s `agent_id`, a session’s code, a task’s `task_id`, a key’s id, or a file as its agent and path (`billing/notes/customers.md`). `object_type` is the action’s first word.
`target`	The same in words, as the console shows it: an email address, a key’s name and prefix, a file’s path.
`data`	Details, by action: the version and which fields changed when an agent is published (with the model, effort, tools and guardrails before and after), the session and agent version when a task starts, the decision on an approval, a file’s size.
`actor`	Who did it. See Actors.
`at`	When, in UTC.

The log never holds prompts, answers, file contents or secrets. It says that a file was written, and by whom, not what it says. It isn’t deleted by retention: it outlasts the tasks it mentions.

Actors

`actor.type`	Who	Also has
`user`	A person in the org, in the console.	`user_id`, `email`, `name`
`api_key`	One of the org’s API keys.	`key_id`, `name`, `prefix`
`agent`	An agent during a task: its writes to its own file system.	`task_id`
`customer`	The person at the computer, in the GuidingHand app.
`session`	Whoever holds a session’s token (the older task API): usually the integration that made the session.
`system`	GuidingHand itself: support credit, auto top-ups.

Objects also say who made and changed them, without a trip to the log: sessions and tasks have created_by, agents have created_by and updated_by, an agent’s draft has saved_by, its versions published_by and its files updated_by.

Actions

Object	Actions
Agents	`agent.created`, `agent.draft_saved`, `agent.draft_discarded`, `agent.published`, `agent.version_restored`, `agent.deleted`, `agent.reset` (the default agent)
Files	`file.written`, `file.deleted`
Sessions	`session.created`, `session.claimed` (a code made signed out, kept in the org), `session.disconnected`, `session.expired`, `session.deleted`
Tasks	`task.started`, `task.answered`, `task.approval_decided`, `task.stopped`
API keys	`key.created`, `key.revoked`
People	`member.role`, `member.removed`, `member.left`, `invite.created`, `invite.accepted`, `invite.revoked`
Webhook	`webhook.updated`, `webhook.secret_rotated`, `webhook.removed`
Org	`org.created`, `org.updated`, `org.tool_secret_viewed`, `org.tool_secret_rotated`, `org.credit`, `org.minutes`
Billing	`billing.topup`, `billing.auto_topup`, `billing.auto_topup_failed`, `billing.card`

task.answered, task.approval_decided and task.stopped are your team’s. What the customer answers, decides or stops is in the task’s events, with answered_by: "customer". More actions may be added, so don’t fail on ones you don’t know.

Filtering and paging

Query	Does
`object_type`	Only events about this kind of object: `agent`, `file`, `session`, `task`, `key`, `member`, `invite`, `webhook`, `org` or `billing`.
`object_id`	With `object_type`: one object’s history. An agent’s includes its files’ events, and a session’s includes its tasks’.
`actor_type`	Only events by this kind of actor: `user`, `api_key`, `agent`, `customer`, `session` or `system`.
`limit`, `cursor`	The page size, 1 to 100 (default 20), and `next_cursor` from the previous page. See pagination.

object_id without object_type is a 400. Reading the log needs the admin role or an API key.

# What the agents wrote to their files
curl "https://guidinghand.ai/v1/audit_events?actor_type=agent" \
  -H "Authorization: Bearer $GUIDINGHAND_API_KEY"

# One session, with its tasks
curl "https://guidinghand.ai/v1/audit_events?object_type=session&object_id=K7QM-24XP" \
  -H "Authorization: Bearer $GUIDINGHAND_API_KEY"

With the SDKs, listAll and list_all walk every page:

for await (const e of gh.auditEvents.listAll({ object_type: 'agent', object_id: 'billing' })) {
  console.log(e.at, e.action, e.actor.type);
}

for e in client.audit_events.list_all(object_type="agent", object_id="billing"):
    print(e["at"], e["action"], e["actor"]["type"])

Get started

SDKs

Concepts

Guides

The event

Actors

Actions

Filtering and paging

​The event

​Actors

​Actions

​Filtering and paging

The event

Actors

Actions

Filtering and paging