> ## Documentation Index
> Fetch the complete documentation index at: https://docs.guidinghand.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Audit log

> Who did what in your org, and when: people, API keys, agents and GuidingHand itself.

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`:

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

```json Response theme={null}
{
  "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](#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](#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](/concepts/recordings#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](/concepts/agents#the-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](/api-reference/introduction#the-older-session-token-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](/concepts/tasks#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](/guides/errors#pagination). |

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

```bash theme={null}
# 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:

<CodeGroup>
  ```javascript Node theme={null}
  for await (const e of gh.auditEvents.listAll({ object_type: 'agent', object_id: 'billing' })) {
    console.log(e.at, e.action, e.actor.type);
  }
  ```

  ```python Python theme={null}
  for e in client.audit_events.list_all(object_type="agent", object_id="billing"):
      print(e["at"], e["action"], e["actor"]["type"])
  ```
</CodeGroup>