GET/admin/audit-log

Platform-wide audit log

list_admin_audit_log

audit:read
A token needs the audit:read scope: Read the audit log (org owners / platform admins)Granted by read_api, write_api.Every operation this scope unlocks
Single-resource
x-gitmoap-isolation: {"kind":"single_or_self_scoped"}
Paginated
Pass the cursor a page returns to get the next one.

For platform administrators only. With scope, reads one audit trail — the platform's, an organization's or a user's; otherwise actor or resource selects records by who acted or what was acted on; with none of them, it reads the platform's own trail. Newest first, and the other filters narrow each page, so a page can hold fewer than limit records while more remain.

Parameters

Query

scopestringoptionalThe audit trail to read: PLATFORM, ROOT# followed by an organization's top-level group id, or USER# followed by a user id
actorstringoptionalFilter to one actor id
resourcestringoptionalFilter to one target resource id
categorystringoptionalFilter to one category
fromstringoptionalLower time bound (RFC-3339, inclusive)
tostringoptionalUpper time bound (RFC-3339, exclusive)
limitinteger · int32optionalPage size (1-100, default 20)
cursorstringoptionalOpaque pagination cursor

Responses

200A page of audit recordsapplication/json

recordsarray of AuditRecord
- The AuditRecord schema
- actorAuditActor
  - The AuditActor schema
  - actor_typestringWhat kind of caller acted: user, service_account, pipeline_run, anonymous, or scim — an organization's identity provider calling with its SCIM token.
  - auth_methodAuthMethodjwtaccess_tokenanonymousHow the caller authenticated.
  - idstringThe id of the user, service account or pipeline run that acted, or anonymous.
  - avatar_urlstring or nulloptional
  - emailstringoptional
  - token_idstring or nulloptional
  - usernamestringoptional
- audit_idAuditId (string · uuid)
- categoryAuditCategorymutationauth_eventsensitive_readWhat kind of operation the record captures.
- hashstringSHA256(canonical_json(record without hash) ‖ prev_hash), hex.
- http_methodstring
- monthstringThe month the record belongs to, YYYY-MM. Each month's records form one segment of the chain.
- occurred_atstring
- operation_idstring
- outcomeAuditOutcomesuccessdeniedfailureThe result of the audited operation.
- prev_hashstringHash of the previous record in the chain (genesis = 64 zeros; first of a month links to the prior month's tip).
- recorded_atstringWhen the record was written to the log, RFC 3339 with microseconds.
- request_idstring
- routestring
- scopestringWhich audit chain the record belongs to — an organisation, a user, or the platform.
- seqinteger · int640–∞Monotonic position within (scope, month).
- status_codeinteger · int320–∞
- accessAccessAuditDetail or nulloptionalFor an operation that changed who can do what: each grant it made, changed or revoked, with the role before and after. Absent everywhere else — and absent fields do not enter the hash, so every record written before this field existed verifies unchanged.
  - The AccessAuditDetail schema
  - changesarray of AccessAuditChange
  - inheritanceInheritanceAuditChange or nulloptionalA scope's inheritance switched.
  - limitLimitAuditChange or nulloptionalA limit set or removed.
  - roleRoleAuditChange or nulloptionalA custom role's permissions changing — which changes access wherever the role is granted, without any grant changing.
- mcpMcpAuditDetail or nulloptionalFor a request an AI agent made through the MCP server: the tool and the client. Absent everywhere else, and so outside the hash of every record that does not carry it.
  - The McpAuditDetail schema
  - toolstringThe tool whose execution made the request.
  - clientstring or nulloptionalThe client application the tool call came from, as that application named itself.
  - oauth_client_idstring or nulloptionalThe app the access token was issued to, when an app connected through sign-in — its own registered identifier, which, unlike the self-reported client name, the person consented to.
- resource_bindingstring or nulloptional
- source_ipstring or nulloptional
- target_idstring or nulloptional
- target_typestring or nulloptional
- user_agentstring or nulloptional
next_cursorstring or nulloptional

200 exampleSynthesized example

400A query parameter is not a well-formed value of its typeapplication/json

Error codes

BAD_REQUESTThe request is malformed: a parameter or a body field is not a well-formed value of its type

errorErrorBody
- The ErrorBody schema
- codestringThe coarse category, tied to the status: NOT_FOUND, CONFLICT, INSUFFICIENT_SCOPE. Every error has one; the API reference's error catalogue lists them all.
- messagestringWhat went wrong, for a person. Written to be read, not parsed: match on reason or code.
- fieldstring or nulloptionalOn a 400 that refused one field's value, the field, as its JSON path: email, items[0].name. Put the message under that input. Absent on every other error.
- reasonstring or nulloptionalThe specific code, when the error has one: LAST_ORGANIZATION_OWNER, BRANCH_PROTECTED. The message starts with it too. Match on this when it is present, and on code otherwise.
- required_scopestring or nulloptionalThe scope the access token was missing, on INSUFFICIENT_SCOPE.
- violationsanyoptionalPresent on the structured-validation errors (PROVIDER_VALIDATION_FAILED per-node, PIPELINE_VALIDATION_FAILED DAG): a JSON array of the offending elements, so a caller can fix every one in a single round-trip. Absent (omitted) on every other error.

400 exampleSynthesized example

401Unauthenticated — no credential, or an invalid oneapplication/json

Error codes

UNAUTHORIZEDNo credential was sent, or the one sent is invalid, expired or revoked

errorErrorBody
- The ErrorBody schema
- codestringThe coarse category, tied to the status: NOT_FOUND, CONFLICT, INSUFFICIENT_SCOPE. Every error has one; the API reference's error catalogue lists them all.
- messagestringWhat went wrong, for a person. Written to be read, not parsed: match on reason or code.
- fieldstring or nulloptionalOn a 400 that refused one field's value, the field, as its JSON path: email, items[0].name. Put the message under that input. Absent on every other error.
- reasonstring or nulloptionalThe specific code, when the error has one: LAST_ORGANIZATION_OWNER, BRANCH_PROTECTED. The message starts with it too. Match on this when it is present, and on code otherwise.
- required_scopestring or nulloptionalThe scope the access token was missing, on INSUFFICIENT_SCOPE.
- violationsanyoptionalPresent on the structured-validation errors (PROVIDER_VALIDATION_FAILED per-node, PIPELINE_VALIDATION_FAILED DAG): a JSON array of the offending elements, so a caller can fix every one in a single round-trip. Absent (omitted) on every other error.

401 exampleSynthesized example

403Not a platform administratorapplication/json

Error codes

FORBIDDENYou are signed in but may not do this here; reason names the permission or the rule that refused it
INSUFFICIENT_SCOPEThe access token lacks the scope this operation needs; required_scope names it
PERMISSION_REQUIREDYou need a permission you do not hold here; the message names it

errorErrorBody
- The ErrorBody schema
- codestringThe coarse category, tied to the status: NOT_FOUND, CONFLICT, INSUFFICIENT_SCOPE. Every error has one; the API reference's error catalogue lists them all.
- messagestringWhat went wrong, for a person. Written to be read, not parsed: match on reason or code.
- fieldstring or nulloptionalOn a 400 that refused one field's value, the field, as its JSON path: email, items[0].name. Put the message under that input. Absent on every other error.
- reasonstring or nulloptionalThe specific code, when the error has one: LAST_ORGANIZATION_OWNER, BRANCH_PROTECTED. The message starts with it too. Match on this when it is present, and on code otherwise.
- required_scopestring or nulloptionalThe scope the access token was missing, on INSUFFICIENT_SCOPE.
- violationsanyoptionalPresent on the structured-validation errors (PROVIDER_VALIDATION_FAILED per-node, PIPELINE_VALIDATION_FAILED DAG): a JSON array of the offending elements, so a caller can fix every one in a single round-trip. Absent (omitted) on every other error.

403 exampleSynthesized example

501The audit log is not configured on this deploymentapplication/json

Error codes

NOT_IMPLEMENTEDThis deployment has not configured the feature the operation needs; the message names it

errorErrorBody
- The ErrorBody schema
- codestringThe coarse category, tied to the status: NOT_FOUND, CONFLICT, INSUFFICIENT_SCOPE. Every error has one; the API reference's error catalogue lists them all.
- messagestringWhat went wrong, for a person. Written to be read, not parsed: match on reason or code.
- fieldstring or nulloptionalOn a 400 that refused one field's value, the field, as its JSON path: email, items[0].name. Put the message under that input. Absent on every other error.
- reasonstring or nulloptionalThe specific code, when the error has one: LAST_ORGANIZATION_OWNER, BRANCH_PROTECTED. The message starts with it too. Match on this when it is present, and on code otherwise.
- required_scopestring or nulloptionalThe scope the access token was missing, on INSUFFICIENT_SCOPE.
- violationsanyoptionalPresent on the structured-validation errors (PROVIDER_VALIDATION_FAILED per-node, PIPELINE_VALIDATION_FAILED DAG): a JSON array of the offending elements, so a caller can fix every one in a single round-trip. Absent (omitted) on every other error.

501 exampleSynthesized example

CLI

gitmoap audit list-admin-audit-log

--actorstringoptionalFilter to one actor id
--categorystringoptionalFilter to one category
--cursorstringoptionalOpaque pagination cursor
--fromstringoptionalLower time bound (RFC-3339, inclusive)
--limitnumberoptionalPage size (1-100, default 20)
--resourcestringoptionalFilter to one target resource id
--scopestringoptionalThe audit trail to read: `PLATFORM`, `ROOT#` followed by an organization's top-level group id, or `USER#` followed by a user id
--tostringoptionalUpper time bound (RFC-3339, exclusive)

Used in these guides

Audit log

Request

curl "https://api.gitmoap.com/admin/audit-log" \
  -H "Authorization: Bearer $GITMOAP_TOKEN"

gitmoap audit list-admin-audit-log

import { createApiClient } from "@gitmoap/backend-types";

const client = createApiClient({
  baseUrl: "https://api.gitmoap.com",
  headers: { Authorization: `Bearer ${process.env.GITMOAP_TOKEN}` },
});

const { data, error } = await client.GET("/admin/audit-log");

GET /admin/audit-log HTTP/1.1
Host: api.gitmoap.com
Authorization: Bearer $GITMOAP_TOKEN

⌘↵

Send to see the sandbox's answer. Nothing leaves your browser.