> ## 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. # List audit events > Who did what in the org, newest first: people, API keys, agents (their file writes during a task), the person at the computer and GuidingHand itself. Needs the admin role or an API key. For one object’s history, send `object_type` and `object_id`: an agent’s includes its files’, and a session’s its tasks’. ## OpenAPI ````yaml /api-reference/openapi.json get /v1/audit_events openapi: 3.1.0 info: title: GuidingHand API version: 1.0.0 description: >- Create sessions (an invite link with a code for the person at the computer), run tasks on their computer with one of your agents, follow them, answer their questions and approvals, and fetch history and recordings. Test your agents with evals: test cases on fresh machines, run in test sets, scored by a check script or a rubric. Agents are versioned (save a draft, publish it), have tools (their own file system, and your HTTP endpoints), and every change is in the org’s audit log. servers: - url: https://guidinghand.ai description: Production - url: https://dev.guidinghand.ai description: Development (Stripe test mode) security: - bearerAuth: [] tags: - name: Agents - name: Agent files - name: Agent tools - name: Sessions - name: Tasks - name: Webhooks - name: Audit log - name: Test cases - name: Test sets - name: Test runs - name: Start states - name: Runners paths: /v1/audit_events: get: tags: - Audit log summary: List audit events description: >- Who did what in the org, newest first: people, API keys, agents (their file writes during a task), the person at the computer and GuidingHand itself. Needs the admin role or an API key. For one object’s history, send `object_type` and `object_id`: an agent’s includes its files’, and a session’s its tasks’. operationId: listAuditEvents parameters: - name: object_type in: query required: false description: Only events about this kind of object. schema: type: string enum: - agent - file - session - task - key - member - invite - webhook - org - billing - name: object_id in: query required: false description: >- With `object_type`: only this object’s events, such as an agent’s `agent_id` or a session’s code. schema: type: string - name: actor_type in: query required: false description: Only events by this kind of actor. schema: type: string enum: - user - api_key - agent - customer - session - system - name: limit in: query required: false description: How many to return, 1 to 100. schema: type: integer default: 20 minimum: 1 maximum: 100 - name: cursor in: query required: false description: '`next_cursor` from the previous page.' schema: type: string responses: '200': description: OK content: application/json: schema: type: object required: - data - has_more - next_cursor properties: data: type: array items: $ref: '#/components/schemas/AuditEvent' has_more: type: boolean next_cursor: type: - string - 'null' description: Pass as `cursor` to get the next page. '400': $ref: '#/components/responses/E400' '401': $ref: '#/components/responses/E401' '403': $ref: '#/components/responses/E403' components: schemas: AuditEvent: type: object properties: object: const: audit_event id: type: string action: type: string example: agent.published description: >- What happened. Agents: `agent.created`, `agent.draft_saved`, `agent.draft_discarded`, `agent.published`, `agent.version_restored`, `agent.deleted`, `agent.reset` (the default agent). Their files: `file.written`, `file.deleted`. Sessions: `session.created`, `session.claimed`, `session.disconnected`, `session.expired`, `session.deleted`. Tasks: `task.started`, `task.answered` and `task.approval_decided` (by your team), `task.stopped`. API keys: `key.created`, `key.revoked`. People: `member.role`, `member.removed`, `member.left`, `invite.created`, `invite.accepted`, `invite.revoked`. The webhook: `webhook.updated`, `webhook.secret_rotated`, `webhook.removed`. The 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`. More may be added. object_type: type: string example: agent description: >- What it was about: the action’s first word (`agent`, `file`, `session`, `task`, `key`, `member`, `invite`, `webhook`, `org` or `billing`). object_id: type: - string - 'null' example: billing description: >- That object’s id as the API names it: an agent’s `agent_id`, a session’s code, a task’s `task_id`, a key’s id, a file as its agent and path (`billing/notes/a.md`). target: type: - string - 'null' description: >- What it was about, in words: an agent’s id, a session’s code, an email address, a key’s name and prefix, a file’s path. data: type: - object - 'null' description: >- Details, by action. For example `agent.published`: `{ version, note?, changes?: { fields, … } }` (which fields changed, with the model, effort, tools and guardrails before and after); `task.started`: `{ session, agent, version?, draft? }`; `task.approval_decided`: `{ session, decision }`; `file.written`: `{ agent, bytes, created? }`. Never prompts, answers, file contents or secrets. actor: $ref: '#/components/schemas/AuditActor' at: type: string format: date-time AuditActor: oneOf: - title: Person type: object description: A person in the org (in the console). properties: type: const: user user_id: type: string email: type: - string - 'null' example: jane@acme.com name: type: - string - 'null' - title: API key type: object description: One of the org’s API keys. properties: type: const: api_key key_id: type: string name: type: - string - 'null' example: Zendesk prefix: type: - string - 'null' description: The key’s first characters. example: gh_live_AbC1 - title: Agent type: object description: 'An agent during a task: its own file writes.' properties: type: const: agent task_id: type: string - title: Customer type: object description: The person at the computer, in the GuidingHand app. properties: type: const: customer - title: Session token type: object description: >- Whoever holds a session’s token (the older task API): usually the integration that made the session. properties: type: const: session - title: GuidingHand type: object description: 'GuidingHand itself: support, auto top-up.' properties: type: const: system description: Who did it. A person also has `name`. Error: type: object required: - error properties: error: type: object required: - type - message properties: type: type: string enum: - invalid_request - authentication - payment_required - permission - not_found - conflict - rate_limit - server_error message: type: string code: type: string description: >- Why it was refused, when there’s more to say than the status. Starting a task: `insufficient_balance`, `auto_topup_limit_reached` or `card_needs_attention` (402: the balance can’t cover a minute; add funds, raise the auto top-up limit, or update the card), `concurrency_limit` (429), `model_unavailable` (503: the agent’s `model` can’t run on this server; choose another). On `/respond`: `already_answered` (someone answered or decided first: see `answered_by`) or `not_pending` (that question or approval isn’t open any more). The GuidingHand app hears two more, which the API never returns: `customer_answers_off` and `customer_approvals_off` (the agent keeps its questions or approvals for your team). Deleting a start state that test cases use: `in_use` (409, with `test_case_ids`). answered_by: type: string enum: - customer - operator - timeout description: >- With `already_answered`: who answered or decided first (`customer`: the person at the computer; `timeout`: nobody decided an approval within the agent’s `approval_timeout_minutes`, so it was denied). test_case_ids: type: array items: type: string description: 'With `in_use`: the test cases that use the start state.' responses: E400: description: The request is invalid. content: application/json: schema: $ref: '#/components/schemas/Error' E401: description: Missing or invalid API key. content: application/json: schema: $ref: '#/components/schemas/Error' E403: description: Your role can’t do this. content: application/json: schema: $ref: '#/components/schemas/Error' securitySchemes: bearerAuth: type: http scheme: bearer description: An org API key (`gh_live_…`) from Settings → API keys in the console. ````